Differential D18404 Diff 49944 untranslatable_pages/python_coding.rst

Changeset View

Standalone View

untranslatable_pages/python_coding.rst

This file was added.

		1		.. meta::
		2		:description:
		3		Guide to working with Python developer tools
		4
		5		.. metadata-placeholder
		6
		7		:authors: - Rebecca Breu <rebecca@rbreu.de>
		8		:license: GNU free documentation license 1.3 or later.
		9
		10		.. _python_coding:
		11
		12		======================
		13		Python Developer Tools
		14		======================
		15
		16		For working with Krita's Python code, there are a couple of tools for running unit tests and code checks.
		17
		18		.. contents::
		19
		20
		21		Setup
		22		-----
		23
		24		To set up a Python environment for running code checks, unit tests etc, it is recommended to use a Python virtual environment for installing the needed Python packages. For this, install virtualenwrapper from your package manager or follow the `installation instructions <https://virtualenvwrapper.readthedocs.io/en/latest/install.html/>`_. It is also possible to install the needed Python packages directly into your system.
		25
		26		To create a virtual environment for Python 3 with virtualenwrapper, run:
		27
		28		.. code::
		29
		30		mkvirtualenv krita -p /usr/bin/python3
		31
		32		This will create a virtual environment called krita and activate it. You will see that your command line now starts with `(krita)` to indicate the active virtual environment.
		33
		34		Now change into your Krita git repository install the needed dependencies into the environment:
		35
		36		.. code::
		37
		38		pip install --upgrade -r dev-tools/python/dev-requirements.txt
		39
		40		You can rerun this command to update the packages should the version numbers in the requirement file get updated.
		41
		42		To get out of the virtual environment, type:
		43
		44		.. code::
		45
		46		deactivate
		47
		48		And to get back into the virtual environment, type:
		49
		50		.. code::
		51
		52		workon krita
		53
		54
		55		Code Checks
		56		-----------
		57
		58		The code checker follows Python's official style guide, `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_.
		59
		60		To run codechecks on all Python files, type:
		61
		62		.. code::
		63
		64		flake8 .
		65
		66		Or limit to a specific directory or file:
		67
		68		.. code::
		69
		70		flake8 plugins/python/plugin_importer/
		71
		72
		73		Unit Tests
		74		----------
		75
		76		To run all Python unit tests, type:
		77
		78		.. code::
		79
		80		pytest .
		81
		82		Or limit to a specific directory, file, or test:
		83
		84		.. code::
		85
		86		pytest plugins/python/plugin_importer/tests/test_plugin_importer.py::PluginImporterTestCase::test_zipfile_doesnt_exist
		87
		88		See `Pytest's Getting Started <https://docs.pytest.org/en/latest/getting-started.html>`_ documentation for more information about pytest in general.
		89
		90		Unit tests for Python plugins should reside in a `tests` folder inside the plugin's folder. See the `plugin_importer` plugin for example unit tests. Note that in order to be able to import Krita's Python plugins outside of Krita in the unit test setup, there is a mock `krita` module that will return mock objects for any attribute names so that importing `krita` and registering plugins etc. become no-ops. Thus, it's only possible to test code units that are independent of Krita-related functions. Another caveat is that the mock krita module doesn't work with wildcard imports (`from krita import *`), but those should be avoided anyway.