Browse Source

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>
maint
John Keeping 12 years ago committed by Junio C Hamano
parent
commit
9ef43dd7ad
  1. 14
      Documentation/CodingGuidelines

14
Documentation/CodingGuidelines

@ -179,6 +179,20 @@ For C programs: @@ -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.

Loading…
Cancel
Save