diff --git a/.gitignore b/.gitignore --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ .directory *.backup *.mo +*~ \ No newline at end of file diff --git a/untranslatable_pages/python_coding.rst b/untranslatable_pages/python_coding.rst new file mode 100644 --- /dev/null +++ b/untranslatable_pages/python_coding.rst @@ -0,0 +1,90 @@ +.. meta:: + :description: + Guide to working with Python developer tools + +.. metadata-placeholder + + :authors: - Rebecca Breu + :license: GNU free documentation license 1.3 or later. + +.. _python_coding: + +====================== +Python Developer Tools +====================== + +For working with Krita's Python code, there are a couple of tools for running unit tests and code checks. + +.. contents:: + + +Setup +----- + +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 `_. It is also possible to install the needed Python packages directly into your system. + +To create a virtual environment for Python 3 with *virtualenwrapper*, run: + +.. code:: + + mkvirtualenv krita -p /usr/bin/python3 + +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. + +Now change into your Krita git repository install the needed dependencies into the environment: + +.. code:: + + pip install --upgrade -r dev-tools/python/dev-requirements.txt + +You can rerun this command to update the packages should the version numbers in the requirement file get updated. + +To get out of the virtual environment, type: + +.. code:: + + deactivate + +And to get back into the virtual environment, type: + +.. code:: + + workon krita + + +Code Checks +----------- + +The code checker follows Python's official style guide, `PEP8 `_. + +To run codechecks on all Python files, type: + +.. code:: + + flake8 . + +Or limit to a specific directory or file: + +.. code:: + + flake8 plugins/python/plugin_importer/ + + +Unit Tests +---------- + +To run all Python unit tests, type: + +.. code:: + + pytest . + +Or limit to a specific directory, file, or test: + +.. code:: + + pytest plugins/python/plugin_importer/tests/test_plugin_importer.py::PluginImporterTestCase::test_zipfile_doesnt_exist + +See `Pytest's Getting Started `_ documentation for more information about *pytest* in general. + +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. diff --git a/user_manual/python_scripting/krita_python_plugin_howto.rst b/user_manual/python_scripting/krita_python_plugin_howto.rst --- a/user_manual/python_scripting/krita_python_plugin_howto.rst +++ b/user_manual/python_scripting/krita_python_plugin_howto.rst @@ -350,6 +350,12 @@ To emit or create slots for objects that aren't standard python objects, you only have to put their names between quotation marks. +A note on unit tests +-------------------- + +If you want to write unit tests for your plugin, have a look at the `mock krita module `_. + + Conclusion ----------