Difference between revisions of "Python style guide"
(→Lint) |
|||
(6 intermediate revisions by the same user not shown) | |||
Line 5: | Line 5: | ||
* As a general rule, '''follow the [http://google.github.io/styleguide/pyguide.html Google Python Style Guide]'''. | * 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. | * 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 == | == Specific rules == | ||
Line 12: | Line 19: | ||
=== Lint === | === Lint === | ||
− | * Make sure your code is [https://flake8.readthedocs.org/ flake8] clean. | + | * Make sure your code is [https://flake8.readthedocs.org/ flake8] and [https://black.readthedocs.io/ Black] clean. |
=== Tests === | === Tests === | ||
− | * use <tt> | + | * use <tt>pytest</tt> as test runner |
* put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested | * put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested | ||
* naming conventions: | * naming conventions: | ||
Line 28: | Line 35: | ||
* 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]. | * 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 == | == See also == |
Revision as of 15:38, 8 April 2020
Coding style and best practices for writing Python code for Software Heritage.
Contents
General rules
- As a general rule, follow the Google Python Style Guide.
- Target Python 3. Do not care about backward compatibility with Python 2.
Black
As of April 2020, we use 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
Tests
- use pytest as test runner
- put tests/ dir down deep in the module hierarchy, near to the code being tested
- naming conventions:
- tests/test_mymodule.py
- class TestMyEntity(unittest.TestCase)
- def behavior(self):
- do not prepend test_ to all test methods; use nose's @istest decorator instead
Classes
- Since we target Python 3, there is no need to inherit from object explicitly.
Docstrings
- docstrings should produce a nice API documentation when run through Sphinx, in particular:
- docstrings should be written in reStructuredText
- docstrings should use the Napoleon style (Google variant) to document arguments, return values, etc.
- see also: a comprehensive style example
- see also: Sphinx gotchas