{"thread":{"id":"32771","subject":"[RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","startedAt":"2013-01-29T19:08:44Z","lastAt":"2013-02-03T15:12:03Z","messageCount":8,"participants":["John Keeping","Junio C Hamano","Michael Haggerty","Pete Wyckoff"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"208208","messageId":"20130129190844.GB1342@serenity.lan","threadId":"32771","inReplyTo":null,"subject":"[RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-29T19:08:44Z","receivedAt":"2013-01-29T19:08:44Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"These are kept short by simply deferring to PEP-8.  Most of the Python\ncode in Git is already very close to this style (some things in contrib/\nare not).\n\nRationale for version suggestions:\n\n - Amongst the noise in [1], there isn't any disagreement about using\n   2.6 as a base (see also [2]), although Brandon Casey recently added\n   support for 2.4 and 2.5 to git-p4 [3].\n\n - Restricting ourselves to 2.6+ makes aiming for Python 3 compatibility\n   significantly easier [4].\n\n - Advocating Python 3 support in all scripts is currently unrealistic\n   because:\n\n     - 'p4 -G' provides output in a format that is very hard to use with\n       Python 3 (and its documentation claims Python 3 is unsupported).\n\n     - Mercurial does not support Python 3.\n\n     - Bazaar does not support Python 3.\n\n - But we should try to make new scripts compatible with Python 3\n   because all new Python development is happening on version 3 and the\n   Python community will eventually stop supporting Python 2 [5].\n\n - Python 3.1 is required to support the 'surrogateescape' error handler\n   for encoding/decodng filenames to/from Unicode strings and Python 3.0\n   is not longer supported.\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/210329\n[2] http://article.gmane.org/gmane.comp.version-control.git/210429\n[3] http://thread.gmane.org/gmane.comp.version-control.git/214579\n[4] http://docs.python.org/3.3/howto/pyporting.html#try-to-support-python-2-6-and-newer-only\n[5] http://www.python.org/dev/peps/pep-0404/\n\n---\nChanges since v1:\n\n- Set 3.1 as the minimum Python 3 version\n\n- Remove the section on Unicode literals - it just adds confusion and\n  doesn't apply to the current code; we can deal with any issues if they\n  ever arise.\n\n Documentation/CodingGuidelines | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 69f7e9b..db7a416 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -179,6 +179,19 @@ For C programs:\n  - Use Git's gettext wrappers to make the user interface\n    translatable. See \"Marking strings for translation\" in po/README.\n \n+For Python scripts:\n+\n+ - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\n+\n+ - As a minimum, we aim to be compatible with Python 2.6 and 2.7.\n+\n+ - Where required libraries do not restrict us to Python 2, we try to\n+   also be compatible with Python 3.1 and later.\n+\n+ - We use the 'b' prefix for bytes literals.  Note that even though\n+   the Python documentation for version 2.6 does not mention this\n+   prefix it is supported since version 2.6.0.\n+\n Writing Documentation:\n \n  Every user-visible change should be reflected in the documentation.\n-- \n1.8.1.1.644.g4977e08\n"},{"id":"208211","messageId":"7vzjzrokag.fsf@alter.siamese.dyndns.org","threadId":"32771","inReplyTo":"20130129190844.GB1342@serenity.lan","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-29T19:34:31Z","receivedAt":"2013-01-29T19:34:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Keeping <john@keeping.me.uk> writes:\n\n> Changes since v1:\n>\n> - Set 3.1 as the minimum Python 3 version\n>\n> - Remove the section on Unicode literals - it just adds confusion and\n>   doesn't apply to the current code; we can deal with any issues if they\n>   ever arise.\n> ...\n> + - We use the 'b' prefix for bytes literals.  Note that even though\n> +   the Python documentation for version 2.6 does not mention this\n> +   prefix it is supported since version 2.6.0.\n\nDo we still need to single out the 'b' prefix?  Even if it were\nnecessary, I'd like to see it toned down a bit to make it clear that\nmost of the time you can write strings as strings without having to\nworry about the \"is it unicode string or a string string\" mess.\nLike\n\n    - When you must make distinction between Unicode literals and\n      byte string literals, it is OK to use 'b' prefix.  Even though\n      ...\n\nperhaps?\n"},{"id":"208215","messageId":"20130129195534.GE1342@serenity.lan","threadId":"32771","inReplyTo":"7vzjzrokag.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-29T19:55:34Z","receivedAt":"2013-01-29T19:55:34Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Tue, Jan 29, 2013 at 11:34:31AM -0800, Junio C Hamano wrote:\n> John Keeping <john@keeping.me.uk> writes:\n> \n> > Changes since v1:\n> >\n> > - Set 3.1 as the minimum Python 3 version\n> >\n> > - Remove the section on Unicode literals - it just adds confusion and\n> >   doesn't apply to the current code; we can deal with any issues if they\n> >   ever arise.\n> > ...\n> > + - We use the 'b' prefix for bytes literals.  Note that even though\n> > +   the Python documentation for version 2.6 does not mention this\n> > +   prefix it is supported since version 2.6.0.\n> \n> Do we still need to single out the 'b' prefix?  Even if it were\n> necessary, I'd like to see it toned down a bit to make it clear that\n> most of the time you can write strings as strings without having to\n> worry about the \"is it unicode string or a string string\" mess.\n> Like\n> \n>     - When you must make distinction between Unicode literals and\n>       byte string literals, it is OK to use 'b' prefix.  Even though\n>       ...\n> \n> perhaps?\n\nYeah, that's better.\n\nI want to include it because if you look in the Python documentation\nthen you'll be misled into thinking that it's not available on 2.6 and\nwe will be supporting that for a while since it is the version included\nin RHEL 6.\n\n\nJohn\n"},{"id":"208254","messageId":"5108F056.9040406@alum.mit.edu","threadId":"32771","inReplyTo":"20130129190844.GB1342@serenity.lan","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2013-01-30T10:05:10Z","receivedAt":"2013-01-30T10:05:10Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 01/29/2013 08:08 PM, John Keeping wrote:\n> These are kept short by simply deferring to PEP-8.  Most of the Python\n> code in Git is already very close to this style (some things in contrib/\n> are not).\n> \n> Rationale for version suggestions:\n> \n>  - Amongst the noise in [1], there isn't any disagreement about using\n>    2.6 as a base (see also [2]), although Brandon Casey recently added\n>    support for 2.4 and 2.5 to git-p4 [3].\n> \n>  - Restricting ourselves to 2.6+ makes aiming for Python 3 compatibility\n>    significantly easier [4].\n> \n>  - Advocating Python 3 support in all scripts is currently unrealistic\n>    because:\n> \n>      - 'p4 -G' provides output in a format that is very hard to use with\n>        Python 3 (and its documentation claims Python 3 is unsupported).\n> \n>      - Mercurial does not support Python 3.\n> \n>      - Bazaar does not support Python 3.\n> \n>  - But we should try to make new scripts compatible with Python 3\n>    because all new Python development is happening on version 3 and the\n>    Python community will eventually stop supporting Python 2 [5].\n> \n>  - Python 3.1 is required to support the 'surrogateescape' error handler\n>    for encoding/decodng filenames to/from Unicode strings and Python 3.0\n>    is not longer supported.\n> \n> [1] http://thread.gmane.org/gmane.comp.version-control.git/210329\n> [2] http://article.gmane.org/gmane.comp.version-control.git/210429\n> [3] http://thread.gmane.org/gmane.comp.version-control.git/214579\n> [4] http://docs.python.org/3.3/howto/pyporting.html#try-to-support-python-2-6-and-newer-only\n> [5] http://www.python.org/dev/peps/pep-0404/\n> \n> ---\n> Changes since v1:\n> \n> - Set 3.1 as the minimum Python 3 version\n> \n> - Remove the section on Unicode literals - it just adds confusion and\n>   doesn't apply to the current code; we can deal with any issues if they\n>   ever arise.\n> \n>  Documentation/CodingGuidelines | 13 +++++++++++++\n>  1 file changed, 13 insertions(+)\n> \n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 69f7e9b..db7a416 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -179,6 +179,19 @@ For C programs:\n>   - Use Git's gettext wrappers to make the user interface\n>     translatable. See \"Marking strings for translation\" in po/README.\n>  \n> +For Python scripts:\n> +\n> + - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\n> +\n> + - As a minimum, we aim to be compatible with Python 2.6 and 2.7.\n> +\n> + - Where required libraries do not restrict us to Python 2, we try to\n> +   also be compatible with Python 3.1 and later.\n> +\n> + - We use the 'b' prefix for bytes literals.  Note that even though\n> +   the Python documentation for version 2.6 does not mention this\n> +   prefix it is supported since version 2.6.0.\n> +\n>  Writing Documentation:\n>  \n>   Every user-visible change should be reflected in the documentation.\n> \n\nNit: s/it is supported/it has been supported/\n\nI think this would be a good Python policy.\n\nI would hate to junk up all Python code with things like\n\n    ' '.encode('ascii')\n\nthough, so maybe we should establish a small Python library of\ncompatibility utilities (like a small \"six\").  It could contain b().\n\nAnother handy utility function could be\n\n    def check_python_version(minimum_v2=0x02060000,\n                             minimum_v3=0x03010000)\n\nwhich checks our default Python requirements by default, but is\noverrideable by specific scripts if they know that they can deal with\nolder Python versions.\n\nBut I haven't had time to think of where to put such a library, how to\ninstall it, etc.\n\nMichael\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"208315","messageId":"20130130203158.GN1342@serenity.lan","threadId":"32771","inReplyTo":"5108F056.9040406@alum.mit.edu","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-30T20:31:58Z","receivedAt":"2013-01-30T20:31:58Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Wed, Jan 30, 2013 at 11:05:10AM +0100, Michael Haggerty wrote:\n> Nit: s/it is supported/it has been supported/\n\nThanks, I'll fix in the re-roll.\n\n> I think this would be a good Python policy.\n> \n> I would hate to junk up all Python code with things like\n> \n>     ' '.encode('ascii')\n> \n> though, so maybe we should establish a small Python library of\n> compatibility utilities (like a small \"six\").  It could contain b().\n> \n> Another handy utility function could be\n> \n>     def check_python_version(minimum_v2=0x02060000,\n>                              minimum_v3=0x03010000)\n> \n> which checks our default Python requirements by default, but is\n> overrideable by specific scripts if they know that they can deal with\n> older Python versions.\n> \n> But I haven't had time to think of where to put such a library, how to\n> install it, etc.\n\nIf we want to go that route, I think restructuring the\n\"git_remote_helpers\" directory and re-using its infrastructure for\ninstalling the \"Git Python modules\" would be the way to go.  The\ndirectory structure would become something like this:\n\n    git/\n    `-- python/\n        |-- Makefile    # existing file pulled out of git_remote_helpers\n        |-- < some new utility library >\n        |-- git_remote_helpers\n        |   |-- __init__.py\n        |   |-- git\n        |   |   |-- __init__.py\n        |   |   |-- exporter.py\n        |   |   |-- git.py\n        |   |   |-- importer.py\n        |   |   |-- non_local.py\n        |   |   `-- repo.py\n        |   `-- util.py\n        |-- setup.cfg   # existing file pulled out of git_remote_helpers\n        `-- setup.py    # existing file pulled out of git_remote_helpers\n\n\nIt looks like the GitPython project[1] as already taken the \"git\" module\nname, so perhaps we should use \"git_core\" if we do introduce a new\nmodule.\n\n[1] http://pypi.python.org/pypi/GitPython\n\n\nJohn\n"},{"id":"208455","messageId":"510B7F4B.7040902@alum.mit.edu","threadId":"32771","inReplyTo":"20130130203158.GN1342@serenity.lan","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2013-02-01T08:39:39Z","receivedAt":"2013-02-01T08:39:39Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 01/30/2013 09:31 PM, John Keeping wrote:\n> On Wed, Jan 30, 2013 at 11:05:10AM +0100, Michael Haggerty wrote:\n>> [...] maybe we should establish a small Python library of\n>> compatibility utilities (like a small \"six\"). [...]\n>> But I haven't had time to think of where to put such a library, how to\n>> install it, etc.\n> \n> If we want to go that route, I think restructuring the\n> \"git_remote_helpers\" directory and re-using its infrastructure for\n> installing the \"Git Python modules\" would be the way to go.  The\n> directory structure would become something like this:\n> \n>     git/\n>     `-- python/\n>         |-- Makefile    # existing file pulled out of git_remote_helpers\n>         |-- < some new utility library >\n>         |-- git_remote_helpers\n>         |   |-- __init__.py\n>         |   |-- git\n>         |   |   |-- __init__.py\n>         |   |   |-- exporter.py\n>         |   |   |-- git.py\n>         |   |   |-- importer.py\n>         |   |   |-- non_local.py\n>         |   |   `-- repo.py\n>         |   `-- util.py\n>         |-- setup.cfg   # existing file pulled out of git_remote_helpers\n>         `-- setup.py    # existing file pulled out of git_remote_helpers\n> \n> \n> It looks like the GitPython project[1] as already taken the \"git\" module\n> name, so perhaps we should use \"git_core\" if we do introduce a new\n> module.\n> \n> [1] http://pypi.python.org/pypi/GitPython\n\nThis sounds reasonable.  But not all Python code will go under the\n\"python\" subdirectory, right?  For example, I am working on a Python\nscript that fits thematically under contrib/hooks.\n\nOTOH (I'm thinking aloud here) it is probably a bad idea for a hook\nscript to depend on a Python module that is part of git itself.  Doing\nso would make the hook script depend on a particular version of git (or\nat least a version with a compatible Python module).  But users might be\nreluctant to upgrade git just to install a hook script.\n\nMichael\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"208471","messageId":"20130201111634.GA2476@farnsworth.metanate.com","threadId":"32771","inReplyTo":"510B7F4B.7040902@alum.mit.edu","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-02-01T11:16:34Z","receivedAt":"2013-02-01T11:16:34Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Fri, Feb 01, 2013 at 09:39:39AM +0100, Michael Haggerty wrote:\n> On 01/30/2013 09:31 PM, John Keeping wrote:\n> > On Wed, Jan 30, 2013 at 11:05:10AM +0100, Michael Haggerty wrote:\n> >> [...] maybe we should establish a small Python library of\n> >> compatibility utilities (like a small \"six\"). [...]\n> >> But I haven't had time to think of where to put such a library, how to\n> >> install it, etc.\n> > \n> > If we want to go that route, I think restructuring the\n> > \"git_remote_helpers\" directory and re-using its infrastructure for\n> > installing the \"Git Python modules\" would be the way to go.  The\n> > directory structure would become something like this:\n> > \n> >     git/\n> >     `-- python/\n> >         |-- Makefile    # existing file pulled out of git_remote_helpers\n> >         |-- < some new utility library >\n> >         |-- git_remote_helpers\n> >         |   |-- __init__.py\n> >         |   |-- git\n> >         |   |   |-- __init__.py\n> >         |   |   |-- exporter.py\n> >         |   |   |-- git.py\n> >         |   |   |-- importer.py\n> >         |   |   |-- non_local.py\n> >         |   |   `-- repo.py\n> >         |   `-- util.py\n> >         |-- setup.cfg   # existing file pulled out of git_remote_helpers\n> >         `-- setup.py    # existing file pulled out of git_remote_helpers\n> > \n> > \n> > It looks like the GitPython project[1] as already taken the \"git\" module\n> > name, so perhaps we should use \"git_core\" if we do introduce a new\n> > module.\n> > \n> > [1] http://pypi.python.org/pypi/GitPython\n> \n> This sounds reasonable.  But not all Python code will go under the\n> \"python\" subdirectory, right?  For example, I am working on a Python\n> script that fits thematically under contrib/hooks.\n\nI was thinking of it as analagous with the \"perl\" directory that\ncurrently exists.  So the \"python\" directory will contain library code\nbut scripts can live wherever is most appropriate.\n\nOne way of looking at it is: could the user want to have this installed\nfor all available versions of Python?  For a script, the answer is \"no\"\nbecause they will call it and it will just run.  For libraries, you want\nthem to be available with whatever Python interpreter you happen to be\nrunning (assuming that it is a version supported by the library).\n\n> OTOH (I'm thinking aloud here) it is probably a bad idea for a hook\n> script to depend on a Python module that is part of git itself.  Doing\n> so would make the hook script depend on a particular version of git (or\n> at least a version with a compatible Python module).  But users might be\n> reluctant to upgrade git just to install a hook script.\n\nI don't think such a dependency is a bad idea in the longer term.  If a\n\"Git Python library\" is developed, then at some point most people who\nhave Git installed will have some version of that library - it becomes a\ncase of perhaps wanting to limit yourself to some subset of the library\nrather than just not using it.\n\nIn fact, git_remote_helpers has been available since Git 1.7.0 and\ncontains a lot of functionality that is more generic than its name\nsuggests.\n\n\nJohn\n"},{"id":"208548","messageId":"20130203151203.GA10423@padd.com","threadId":"32771","inReplyTo":"20130201111634.GA2476@farnsworth.metanate.com","subject":"Re: [RFC/PATCH v2] CodingGuidelines: add Python coding guidelines","fromName":"Pete Wyckoff","fromEmail":"pw@padd.com","sentAt":"2013-02-03T15:12:03Z","receivedAt":"2013-02-03T15:12:03Z","isPatch":true,"sender":{"key":"pw@padd.com","avatar":null},"body":"john@keeping.me.uk wrote on Fri, 01 Feb 2013 11:16 +0000:\n> On Fri, Feb 01, 2013 at 09:39:39AM +0100, Michael Haggerty wrote:\n> > On 01/30/2013 09:31 PM, John Keeping wrote:\n> > > On Wed, Jan 30, 2013 at 11:05:10AM +0100, Michael Haggerty wrote:\n> > >> [...] maybe we should establish a small Python library of\n> > >> compatibility utilities (like a small \"six\"). [...]\n> > >> But I haven't had time to think of where to put such a library, how to\n> > >> install it, etc.\n> > > \n> > > If we want to go that route, I think restructuring the\n> > > \"git_remote_helpers\" directory and re-using its infrastructure for\n> > > installing the \"Git Python modules\" would be the way to go.  The\n> > > directory structure would become something like this:\n> > > \n> > >     git/\n> > >     `-- python/\n> > >         |-- Makefile    # existing file pulled out of git_remote_helpers\n> > >         |-- < some new utility library >\n> > >         |-- git_remote_helpers\n> > >         |   |-- __init__.py\n> > >         |   |-- git\n> > >         |   |   |-- __init__.py\n> > >         |   |   |-- exporter.py\n> > >         |   |   |-- git.py\n> > >         |   |   |-- importer.py\n> > >         |   |   |-- non_local.py\n> > >         |   |   `-- repo.py\n> > >         |   `-- util.py\n> > >         |-- setup.cfg   # existing file pulled out of git_remote_helpers\n> > >         `-- setup.py    # existing file pulled out of git_remote_helpers\n> > > \n> > > \n> > > It looks like the GitPython project[1] as already taken the \"git\" module\n> > > name, so perhaps we should use \"git_core\" if we do introduce a new\n> > > module.\n> > > \n> > > [1] http://pypi.python.org/pypi/GitPython\n> > \n> > This sounds reasonable.  But not all Python code will go under the\n> > \"python\" subdirectory, right?  For example, I am working on a Python\n> > script that fits thematically under contrib/hooks.\n> \n> I was thinking of it as analagous with the \"perl\" directory that\n> currently exists.  So the \"python\" directory will contain library code\n> but scripts can live wherever is most appropriate.\n> \n> One way of looking at it is: could the user want to have this installed\n> for all available versions of Python?  For a script, the answer is \"no\"\n> because they will call it and it will just run.  For libraries, you want\n> them to be available with whatever Python interpreter you happen to be\n> running (assuming that it is a version supported by the library).\n> \n> > OTOH (I'm thinking aloud here) it is probably a bad idea for a hook\n> > script to depend on a Python module that is part of git itself.  Doing\n> > so would make the hook script depend on a particular version of git (or\n> > at least a version with a compatible Python module).  But users might be\n> > reluctant to upgrade git just to install a hook script.\n> \n> I don't think such a dependency is a bad idea in the longer term.  If a\n> \"Git Python library\" is developed, then at some point most people who\n> have Git installed will have some version of that library - it becomes a\n> case of perhaps wanting to limit yourself to some subset of the library\n> rather than just not using it.\n> \n> In fact, git_remote_helpers has been available since Git 1.7.0 and\n> contains a lot of functionality that is more generic than its name\n> suggests.\n\nThis library idea would be a great help; there are 100-odd calls\nto git in git-p4, and we've had to deal with getting the arguments\nand parsing correct.  I'd happily switch to using git_core.\n\nProbably some elements of GitPython can be used too.  I'm not so\ninterested in the raw database manipulation, but the command\nwrappers look reasonable.\n\n\t\t-- Pete\n"}]}