manual
405
edits
Changes
→Imports: Sections grouping and headers
=== Tabs ===
* Do not use TABs. Use space characters. In Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. (TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''.) To summarize:
** uses spaces, no TABs
** indentation is 4
{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}
Generally (i.e. this is guidance, not a inviolable rule) imports should be grouped into three main sections: Python, GTK etc. and Gramps. Not all sections are required, include only those that apply. Other sections, or further grouping can be used if the developer thinks this will be useful. It may be useful to put imports in alphabetical order, but a logical order is also acceptable and may be preferable in some cases. It will often be useful to precede each main section with comment headers as in the following example:
<pre>
# -------------------------------------------------------------------------
#
# Standard Python modules
#
# -------------------------------------------------------------------------
import os
import logging
# -------------------------------------------------------------------------
#
# GTK/Gnome modules
#
# -------------------------------------------------------------------------
from gi.repository import Gtk
# -------------------------------------------------------------------------
#
# Gramps modules
#
# -------------------------------------------------------------------------
from gramps.gen.db.base import DbReadBase
from .mymodule import MyClass
</pre>
Where existing code has not followed this guidance, it will not normally be necessary to change the code to follow this guidance.
== Class headers ==
== Docstrings ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation [[Devhelp#See_also|using sphinxSphinx]], a documentation generator for Python code.
* Apart Aside from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [https://github.com/gramps-project/gramps/tree/master/docs docs directory], for info read the [https://github.com/gramps-project/gramps/blob/master/docs/README.txt /docs/README.txt] file.
:More info
:* [http://www.sphinx-doc.org/en/stable/markup/ Sphinx for python]
:* [http://www.sphinx-doc.org/en/stable/rest.html doc with sphinxSphinx]
Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
== Black ==
Gramps CI checks for code formatting compliance using [https://github.com/psf/black Black]. When Black can be installed as a [https://pypi.org/project/black/ Python PIP package,] as a plugin/integration to many IDEs, or as a [https://github.com/psf/black/releases/ standalone tool] on the system. Follow the [https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html usage instructions] on the Black docs to validate your file changes. Doing this prior to creating the Pull Request ensures that it will pass the lint check. If code in a PR violates formatting rules the PR fails the CI check, code and cannot be merged. Code which requires changes is shown in the Checks tab in the Lint panel. You may update the code manually Make changes required to make it pass, or integrate Black formatter with your preferred editor to ensure that the lint check will pass. Sometimes the changes are not visible because they are white space violations, so look carefully. When using Black locally, use the same version as the CI system to ensure formatting consistency.
== Pylint ==
* Run <code>pylint</code> on your code before checking in.
* New files shall have a Pylint score of 9 or higher. New files will , but not be accepted if they have a Pylint score lower than 9enforced by CI tools as Black formatting is.
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.
Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/master/src$ PYTHONPATH=plugins/lib/ pylint --include-ids=y --reports=y plugins/mapservices/googlemap.py
Set reports to '''n''' to have less output. Information on the meaning of codes can be found here:
* [http://pylint-messages.wikidot.com/all-codes All codes], PyLint 1.1.0] Messages: and what they're trying to tell you* [https://pylint.readthedocs.io/en/stable/user_guide/messages Pylint current stable] documentation - now generally has a bit more detail that the older version
== Best practices ==
* Maintain good code hygiene by following coding guidelines and running code analysis and formatting tools locally
* Always develop with [[Coding_for_translation|language translation]] in mind