Difference between revisions of "Python style guide"

From Software Heritage Wiki
Jump to navigation Jump to search
(→‎Specific rules: document docstring guidelines)
Line 34: Line 34:
 
=== Docstrings ===
 
=== Docstrings ===
  
* docstrings should produce a nice API documentation when run through [http://www.sphinx-doc.org/en/stable/index.html Sphinx], in particular:
+
* 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 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.
 
* docstrings should use the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon style] (Google variant) to document arguments, return values, etc.

Revision as of 13:03, 7 September 2017

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

Strings

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

Docstrings

See also