From: John Keeping <john@keeping.me.uk>
Date: Wed, 30 Jan 2013 20:47:32 +0000 (+0000)
Subject: CodingGuidelines: add Python coding guidelines
X-Git-Tag: v1.8.2-rc0~46^2
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/9ef43dd7ad3427f579285e100cc78de124213815

CodingGuidelines: add Python coding guidelines

These are kept short by simply deferring to PEP-8.  Most of the Python
code in Git is already very close to this style (some things in contrib/
are not).

Rationale for version suggestions:

- Amongst the noise in [1], there isn't any disagreement about using
2.6 as a base (see also [2]), although Brandon Casey recently added
support for 2.4 and 2.5 to git-p4 [3].

- Restricting ourselves to 2.6+ makes aiming for Python 3 compatibility
significantly easier [4].

- Advocating Python 3 support in all scripts is currently unrealistic
because:

- 'p4 -G' provides output in a format that is very hard to use with
Python 3 (and its documentation claims Python 3 is unsupported).

- Mercurial does not support Python 3.

- Bazaar does not support Python 3.

- But we should try to make new scripts compatible with Python 3
because all new Python development is happening on version 3 and the
Python community will eventually stop supporting Python 2 [5].

- Python 3.1 is required to support the 'surrogateescape' error handler
for encoding/decodng filenames to/from Unicode strings and Python 3.0
is not longer supported.

[1] http://thread.gmane.org/gmane.comp.version-control.git/210329
[2] http://article.gmane.org/gmane.comp.version-control.git/210429
[3] http://thread.gmane.org/gmane.comp.version-control.git/214579
[4] http://docs.python.org/3.3/howto/pyporting.html#try-to-support-python-2-6-and-newer-only
[5] http://www.python.org/dev/peps/pep-0404/

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 69f7e9b76c..432c6cdff0 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -179,6 +179,20 @@ For C programs:
  - Use Git's gettext wrappers to make the user interface
    translatable. See "Marking strings for translation" in po/README.
 
+For Python scripts:
+
+ - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
+
+ - As a minimum, we aim to be compatible with Python 2.6 and 2.7.
+
+ - Where required libraries do not restrict us to Python 2, we try to
+   also be compatible with Python 3.1 and later.
+
+ - When you must differentiate between Unicode literals and byte string
+   literals, it is OK to use the 'b' prefix.  Even though the Python
+   documentation for version 2.6 does not mention this prefix, it has
+   been supported since version 2.6.0.
+
 Writing Documentation:
 
  Every user-visible change should be reflected in the documentation.