Python style guide: Difference between revisions

From Software Heritage Wiki
Jump to navigation Jump to search
(move to the main doc)
Tag: Replaced
Line 1: Line 1:
Coding style and best practices for writing Python code for [[Software Heritage]].
This page [https://docs.softwareheritage.org/devel/contributing/python-style-guide.html moved to the main developer documentation]
 
== 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.
 
== Black ==
 
As of April 2020, we use [https://black.readthedocs.io/ 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.
 
== 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] and [https://black.readthedocs.io/ Black] clean.
 
=== Tests ===
 
* use <tt>pytest</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].
 
=== 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]]

Revision as of 07:53, 18 March 2021

This page moved to the main developer documentation

Retrieved from "https://wiki.softwareheritage.org/index.php?title=Python_style_guide&oldid=1536"