Python style guide

Coding style and best practices for writing Python code for Software Heritage.

General rules

• As a general rule, follow the Google Python Style Guide.
• Target Python 3. Do not care about backward compatibility with Python 2.

Specific rules

As supplement/overrides to the above general rules, follow the additional recommendations below.

Lint

• Make sure your code is flake8 clean.

Tests

• 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:
  • 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.

Strings

• Prefer 'single quotes' over "double quotes". Do otherwise only when needed, e.g., for strings that should contain single quotes

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

See also

• Python package layout