Python style guide
Coding style and best practices for writing Python code for Software Heritage.
- As a general rule, follow the Google Python Style Guide.
- Target Python 3. Do not care about backward compatibility with Python 2.
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.
As supplement/overrides to the above general rules, follow the additional recommendations below.
- Make sure your code is flake8 clean.
- use unittest for assertions, nosetests3 as test runner
- put tests/ dir down deep in the module hierarchy, near to the code being tested
- naming conventions:
- class TestMyEntity(unittest.TestCase)
- def behavior(self):
- do not prepend test_ to all test methods; use nose's @istest decorator instead
- Since we target Python 3, there is no need to inherit from object explicitly.
- Prefer 'single quotes' over "double quotes". Do otherwise only when needed, e.g., for strings that should contain single quotes
- 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.