Difference between revisions of "Python style guide"

From Software Heritage Wiki
Jump to navigation Jump to search
(→‎Specific rules: document docstring guidelines)
(Redirect to swhdocs)
Tag: New redirect
 
(7 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/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 ==
 
−
 
 
−
* [[Python package layout]]
 
−
 
 
  
 
[[Category:Guidelines]]
 
[[Category:Guidelines]]
 
[[Category:Software development]]
 
[[Category:Software development]]
 
[[Category:Python]]
 
[[Category:Python]]

Latest revision as of 11:10, 22 March 2021

Redirect to:

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