|
|
| (6 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | Coding style and best practices for writing Python code for [[Software Heritage]].
| + | #REDIRECT [[swhdocs:devel/contributing/python-style-guide.html]] |
| − | | |
| − | == General rules ==
| |
| − | | |
| − | * 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.
| |
| − | | |
| − | == Specific rules ==
| |
| − | | |
| − | As supplement/overrides to the above general rules, follow the additional recommendations below.
| |
| − | | |
| − | === Lint ===
| |
| − | | |
| − | * Make sure your code is [https://flake8.readthedocs.org/ flake8] clean.
| |
| − | | |
| − | === Tests ===
| |
| − | | |
| − | * use <tt>unittest</tt> for assertions, <tt>nosetests3</tt> as test runner
| |
| − | * put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested
| |
| − | * naming conventions:
| |
| − | ** <tt>tests/test_mymodule.py</tt>
| |
| − | ** <tt>class TestMyEntity(unittest.TestCase)</tt>
| |
| − | ** <tt>def behavior(self):</tt>
| |
| − | *** do ''not'' prepend <tt>test_</tt> to all test methods; use nose's <tt>@istest</tt> decorator instead
| |
| − | | |
| − | === Classes ===
| |
| − | | |
| − | * 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].
| |
| − | | |
| − | === Strings ===
| |
| − | | |
| − | * 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/ 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 ==
| |
| − | | |
| − | * [[Python package layout]]
| |
| − | | |
| | | | |
| | [[Category:Guidelines]] | | [[Category:Guidelines]] |
| | [[Category:Software development]] | | [[Category:Software development]] |
| | [[Category:Python]] | | [[Category:Python]] |
