Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines

[Michael Haggerty <mhagger@alum.mit.edu>]

On 01/29/2013 08:08 PM, John Keeping wrote:
> 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/
> 
> ---
> Changes since v1:
> 
> - Set 3.1 as the minimum Python 3 version
> 
> - Remove the section on Unicode literals - it just adds confusion and
>   doesn't apply to the current code; we can deal with any issues if they
>   ever arise.
> 
>  Documentation/CodingGuidelines | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 69f7e9b..db7a416 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -179,6 +179,19 @@ 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.
> +
> + - We use the 'b' prefix for bytes literals.  Note that even though
> +   the Python documentation for version 2.6 does not mention this
> +   prefix it is supported since version 2.6.0.
> +
>  Writing Documentation:
>  
>   Every user-visible change should be reflected in the documentation.
> 

Nit: s/it is supported/it has been supported/

I think this would be a good Python policy.

I would hate to junk up all Python code with things like

    ' '.encode('ascii')

though, so maybe we should establish a small Python library of
compatibility utilities (like a small "six").  It could contain b().

Another handy utility function could be

    def check_python_version(minimum_v2=0x02060000,
                             minimum_v3=0x03010000)

which checks our default Python requirements by default, but is
overrideable by specific scripts if they know that they can deal with
older Python versions.

But I haven't had time to think of where to put such a library, how to
install it, etc.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/