Difference between revisions of "Python style guide"
Jump to navigation
Jump to search
(→Specific rules: document docstring guidelines) |
|||
| Line 31: | Line 31: | ||
* Prefer <tt>'single quotes'</tt> over <tt>"double quotes"</tt>. Do otherwise only [http://google.github.io/styleguide/pyguide.html?showone=Strings#Strings when needed], e.g., for strings that should ''contain'' single quotes | * Prefer <tt>'single quotes'</tt> over <tt>"double quotes"</tt>. Do otherwise only [http://google.github.io/styleguide/pyguide.html?showone=Strings#Strings when needed], e.g., for strings that should ''contain'' single quotes | ||
| + | |||
| + | === 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 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 13:01, 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
- 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