|
|
Line 1: |
Line 1: |
− | Coding style and best practices for writing Python code for [[Software Heritage]].
| + | This page [https://docs.softwareheritage.org/devel/contributing/python-style-guide.html moved to the main developer documentation] |
− | | |
− | == General rules ==
| |
− | | |
− | * As a general rule, '''follow the [http://google.github.io/styleguide/pyguide.html Google Python Style Guide]'''.
| |
− | * Target '''Python 3'''. Do not care about backward compatibility with Python 2.
| |
− | | |
− | == Black ==
| |
− | | |
− | As of April 2020, we use [https://black.readthedocs.io/ Black] as automated code formatter for all Software Heritage Python code.
| |
− | CI, tox, and other linting tools are configured to fail if code is not formatted as black would.
| |
− | | |
− | Note that, as part of this, ''maximum line length is 88 characters'', rather than the default of 79.
| |
− | | |
− | == Specific rules ==
| |
− | | |
− | As supplement/overrides to the above general rules, follow the additional recommendations below.
| |
− | | |
− | === Lint ===
| |
− | | |
− | * Make sure your code is [https://flake8.readthedocs.org/ flake8] and [https://black.readthedocs.io/ Black] clean.
| |
− | | |
− | === Tests ===
| |
− | | |
− | * use <tt>pytest</tt> as test runner
| |
− | * put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested
| |
− | * naming conventions:
| |
− | ** <tt>tests/test_mymodule.py</tt>
| |
− | ** <tt>class TestMyEntity(unittest.TestCase)</tt>
| |
− | ** <tt>def behavior(self):</tt>
| |
− | *** do ''not'' prepend <tt>test_</tt> to all test methods; use nose's <tt>@istest</tt> decorator instead
| |
− | | |
− | === Classes ===
| |
− | | |
− | * Since we target Python 3, there is no need to [http://google.github.io/styleguide/pyguide.html?showone=Classes#Classes inherit from <tt>object</tt> explicitly].
| |
− | | |
− | === Docstrings ===
| |
− | | |
− | * docstrings should produce a nice API documentation when run through [http://www.sphinx-doc.org/en/stable/ Sphinx], in particular:
| |
− | * docstrings should be written in [http://www.sphinx-doc.org/en/stable/rest.html reStructuredText]
| |
− | * docstrings should use the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon style] (Google variant) to document arguments, return values, etc.
| |
− | ** see also: a [http://www.sphinx-doc.org/en/stable/ext/example_google.html#example-google comprehensive style example]
| |
− | ** see also: [[Sphinx gotchas]]
| |
− | | |
− | == See also ==
| |
− | | |
− | * [[Python package layout]]
| |
− | | |
| | | |
| [[Category:Guidelines]] | | [[Category:Guidelines]] |
| [[Category:Software development]] | | [[Category:Software development]] |
| [[Category:Python]] | | [[Category:Python]] |