Difference between revisions of "Python style guide"

Latest revision as of 11:10, 22 March 2021

Redirect to:

swhdocs:devel/contributing/python-style-guide.html

@@ 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.
-== 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] 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:Software development]]
 [[Category:Python]]

Difference between revisions of "Python style guide"

Latest revision as of 11:10, 22 March 2021

Navigation menu

Search