Define Python scripting guidelines
Open, NormalPublic

Description

With the new Python support, we need to agree upon guidelines for Python scripts. At minimum, this means compliance with a style guide.

As Python is a dynamically typed language with few hard rules, style guides are necessary to keep things clean and consistent, reduce merge issues, and make the code more readable.

For simplicity's sake, I suggest we adopt the standard Python style guide–PEP8–with one exception: Make the rule about a max line length of 79 characters optional. In my experience, conforming to this rule can reduce the readability of some scripts.

The full style guide is available here: https://www.python.org/dev/peps/pep-0008/

The primary benefits of using PEP8 over a custom style guide is that it's already wildly adopted, with a number of compliance scripts available, including pep8.py and autopep8.py. Both these scripts can be configured to ignore certain parts of PEP8 via the command line. For example, the 79 character line length rule can be ignored by adding --ignore=E501. A full list of PEP8 error codes is available here.

Another useful tool is flake8, which can enforce PEP8 compliance and identify bad practices and problems that that often lead to bugs and runtime issues, such as variable reuse, unused imports, undefined variable usage, etc. This is very useful as an automated test.

There are also plugins for various IDEs that integrate these scripts to provide visual feedback and shortcuts to autoformat code according to a chosen subset of pep8 rules. A common one is PyDev, which exists as a plugin for Eclipse, but also work in a number of other IDEs.

One of the drawbacks of PEP8 is that some rules will clash with Krita's C++ guidelines. For example, casing of functions: my_function() instead of myFunction().

victorw created this task.Jul 24 2017, 10:15 PM
Restricted Application added a subscriber: woltherav. · View Herald TranscriptJul 24 2017, 10:15 PM

On using autopep:

  1. Install autopep8 via pip3.
  2. Goto folder with python files to autopep.
  3. Do autopep8 --ignore=E501,E241 --in-place *.py

Posting this for future reference.

I have assumed that you want to conform to C++ variableName style, ugly as it is.
There should be guidelines about where scripts ought to persist their data.
I also think there should be thought given to how scripts are listed in menus the flat tools-scripts structure could quickly run out of space.

You should also think about how scripts are distributed and installed. Will any scripts be hosted on phabricator for example? How do people install scripts? How should scripts be packaged?

As it turns out, the coding style will be inconsistent either way.
If you choose Qt style, then references to the Python standard library will be inconsistent and vice versa.

There should be guidelines about where scripts ought to persist their data.

Good point. Do you have any actual use-cases in mind?

Settings I feel should be handled by Krita and exposed via the Krita API in a safe manner.

I also think there should be thought given to how scripts are listed in menus the flat tools-scripts structure could quickly run out of space.

I feel that's more of a UX issue in Krita itself, and not something script writers should have to worry about. If the solution would add something like categories or menu paths to scripts, then it might need guidelines in the future.

As it turns out, the coding style will be inconsistent either way.
If you choose Qt style, then references to the Python standard library will be inconsistent and vice versa.

Yes. There's no good way around that, unfortunately. I would argue, however, that having different styles for different languages is not necessarily bad: It's easier to tell at a glance whether what you're using comes from Python or C++.

There should be guidelines about where scripts ought to persist their data.

Good point. Do you have any actual use-cases in mind?

Nope. But I could imagine a script wanting to maintain local data above and beyond "mere" settings - eg thumbnails for quick loading.

Settings I feel should be handled by Krita and exposed via the Krita API in a safe manner.

I also think there should be thought given to how scripts are listed in menus the flat tools-scripts structure could quickly run out of space.

I feel that's more of a UX issue in Krita itself, and not something script writers should have to worry about. If the solution would add something like categories or menu paths to scripts, then it might need guidelines in the future.

I think there are really only two options

  • flat addition to the tools/scripts menu (which I think will become unworkable)
  • a registration procedure where the script writer nominates the menu structure (either within tools->scripts or within the broader menu categories).

Anything else requires the Krita maintainers to do housekeeping on for each script. How are filters organised?

There may also be scripts which the writer wants to connect to a signal, rather than showing up in the tools->scripts menu. That may call for an "enable/disable" interface (which, in turn, suggests a registration procedure).

As it turns out, the coding style will be inconsistent either way.
If you choose Qt style, then references to the Python standard library will be inconsistent and vice versa.

Yes. There's no good way around that, unfortunately. I would argue, however, that having different styles for different languages is not necessarily bad: It's easier to tell at a glance whether what you're using comes from Python or C++.

I think I am going to return to lowercase_underscore_variables.

There should be guidelines on script I18n, particularly for those with English as a first language.

N802 is lower case function names - will need to be ignored
The sample scripts will not pass PEP8 requirements.

I think settings and other data should be stored in the script's install directory or a subdirectory. If they are all dumped into .config they will be orphaned if the script is removed. There is also less (no?) risk of name collisions.

woltherav moved this task from Backlog to Zeyelth on the Krita board.May 18 2018, 9:06 AM