Python style guide - Revision history

NicolasDandrimont: Redirect to swhdocs

2021-03-22T11:10:56Z

Redirect to swhdocs

← Older revision		Revision as of 11:10, 22 March 2021
Line 1:		Line 1:
	~~This page~~ [~~https~~:~~//docs.softwareheritage.org/~~devel/contributing/python-style-guide.html ~~moved to the main developer documentation~~]		#REDIRECT [[swhdocs:devel/contributing/python-style-guide.html]]

	[[Category:Guidelines]]		[[Category:Guidelines]]
	[[Category:Software development]]		[[Category:Software development]]
	[[Category:Python]]		[[Category:Python]]

2021-03-18T07:53:38Z

move to the main doc

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

2020-04-08T15:38:13Z

Lint

← Older revision		Revision as of 15:38, 8 April 2020
Line 19:		Line 19:
	=== Lint ===		=== Lint ===

	* Make sure your code is [https://flake8.readthedocs.org/ flake8] clean.		* Make sure your code is [https://flake8.readthedocs.org/ flake8] and [https://black.readthedocs.io/ Black] clean.

	=== Tests ===		=== Tests ===

2020-04-08T15:37:44Z

Tests: we now use pytest as test runner

← Older revision		Revision as of 15:37, 8 April 2020
Line 23:		Line 23:
	=== Tests ===		=== Tests ===

	* use <tt>~~unittest</tt> for assertions, <tt>nosetests3~~</tt> as test runner		* use <tt>pytest</tt> as test runner
	* put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested		* put <tt>tests/</tt> dir down deep in the module hierarchy, near to the code being tested
	* naming conventions:		* naming conventions:

2020-04-08T15:37:14Z

Specific rules: drop single quote mention, as black uses double quotes

← Older revision		Revision as of 15:37, 8 April 2020
Line 34:		Line 34:

	* 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].		* 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 ===

2020-04-08T15:35:17Z

document black usage

← Older revision		Revision as of 15:35, 8 April 2020
Line 5:		Line 5:
	* As a general rule, '''follow the [http://google.github.io/styleguide/pyguide.html Google Python Style Guide]'''.		* 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.		* 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 ==		== Specific rules ==

2017-09-07T13:05:18Z

Docstrings

← Older revision		Revision as of 13:05, 7 September 2017
Line 38:		Line 38:
	* docstrings should use the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon style] (Google variant) to document arguments, return values, etc.		* 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: a [http://www.sphinx-doc.org/en/stable/ext/example_google.html#example-google comprehensive style example]
	** see also: [[/Sphinx gotchas]]		** see also: [[Sphinx gotchas]]

	== See also ==		== See also ==

2017-09-07T13:03:43Z

Docstrings

← Older revision		Revision as of 13:03, 7 September 2017
Line 34:		Line 34:
	=== Docstrings ===		=== 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 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 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.		* docstrings should use the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon style] (Google variant) to document arguments, return values, etc.

2017-09-07T13:01:04Z

Specific rules: document docstring guidelines

← Older revision		Revision as of 13:01, 7 September 2017
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 ==

2016-07-22T07:09:30Z

← Older revision		Revision as of 07:09, 22 July 2016
Line 37:		Line 37:


			[[Category:Guidelines]]
	[[Category:Software development]]		[[Category:Software development]]
	[[Category:Python]]		[[Category:Python]]