CodingGuidelines: add Python coding guidelines
commit9ef43dd7ad3427f579285e100cc78de124213815
authorJohn Keeping <john@keeping.me.uk>
Wed, 30 Jan 2013 20:47:32 +0000 (30 20:47 +0000)
committerJunio C Hamano <gitster@pobox.com>
Wed, 30 Jan 2013 20:49:28 +0000 (30 12:49 -0800)
treef8a26cbcebae91fba03a302cb2a77e051c4dfcec
parentfe73786b482f11e7a37a269c95d222a384fc5a39
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>
Documentation/CodingGuidelines