{"thread":{"id":"32663","subject":"[RFC/PATCH] CodingGuidelines: add Python code guidelines","startedAt":"2013-01-18T18:06:39Z","lastAt":"2013-01-18T23:05:57Z","messageCount":7,"participants":["John Keeping","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"207208","messageId":"20130118180639.GD31172@serenity.lan","threadId":"32663","inReplyTo":null,"subject":"[RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-18T18:06:39Z","receivedAt":"2013-01-18T18:06:39Z","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 [2], there isn't any disagreement about using\n   2.6 as a base (see also [3]).\n\n - The Git INSTALL document currently says:\n\n      Python version 2.6 or later is needed to use the git-p4\n      interface to Perforce.\n\n - Restricting ourselves to 2.6+ makes aiming for Python 3 compatibility\n   significantly easier [4].\n\n - Following Pete's comment [5] I tested Python 2.6.0 and it does\n   support bytes literals, as suggested by [4] but contradicted by [6].\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 [7].\n\nI chose to recommend `from __future__ import unicode_literals` since it\nprovides the widest range of compatibility (2.6+ and 3.0+) while\nallowing us to be explicit about bytes vs. Unicode.  The alternative\nwould be to advocate using the 'u' prefix on Unicode strings but this\nisn't available in versions 3.0 - 3.2 (it is reintroduced in version 3.3\nas a no-op in order to make it easier to write scripts targeting a wide\nrange of Python versions without needing to use 2to3 [1]).  In reality I\ndoubt we will ever need to worry about this since ASCII strings will\njust work in both Python 2 and Python 3.\n\n[1] http://www.python.org/dev/peps/pep-0414/\n[2] http://thread.gmane.org/gmane.comp.version-control.git/210329\n[3] http://article.gmane.org/gmane.comp.version-control.git/210429\n[4] http://docs.python.org/3.3/howto/pyporting.html#try-to-support-python-2-6-and-newer-only\n[5] http://article.gmane.org/gmane.comp.version-control.git/213830\n[6] http://docs.python.org/2.6/reference/lexical_analysis.html#literals\n[7] http://www.python.org/dev/peps/pep-0404/\n---\n Documentation/CodingGuidelines | 16 ++++++++++++++++\n 1 file changed, 16 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 69f7e9b..baf3b41 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -179,6 +179,22 @@ 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.  In this case we use\n+   `from __future__ import unicode_literals` if we need to differentiate\n+   Unicode string literals, rather than prefixing Unicode strings with\n+   'u' since the latter is not supported in Python versions 3.0 - 3.2.\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\n"},{"id":"207214","messageId":"7vvcauqpn4.fsf@alter.siamese.dyndns.org","threadId":"32663","inReplyTo":"20130118180639.GD31172@serenity.lan","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-18T19:04:15Z","receivedAt":"2013-01-18T19:04:15Z","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> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 69f7e9b..baf3b41 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -179,6 +179,22 @@ 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.  In this case we use\n> +   `from __future__ import unicode_literals` if we need to differentiate\n> +   Unicode string literals, rather than prefixing Unicode strings with\n> +   'u' since the latter is not supported in Python versions 3.0 - 3.2.\n\n\"In this case\"?  In what case?  This document will stay effective\nlong after you settle one particular backward incompatibility Python\n3 introduced, namely, the unicode literal issues.  It is just one\n\"example\".\n\nThat example somehow tells me that early versions of Python 3.x\nseries may be too buggy and not worth worrying about, and we may\nwant to set a floor for Python 3.x series, too, with something\nlike:\n\n    - The code should be compatible with 2.6 and newer versions of\n      Python 2.x series; 2.5 and older are not supported anymore.\n\n    - The code should also be comptabile with 3.2 and newer versions\n      of Python 3.x series; 3.1 and older are not mature enough and\n      have too many problems to write scripts that work on it and\n      solid 2.x at the same time.\n\nI am not actively advocating to disqualify early 3.x; I am just\nsuggesting that doing so may be a viable escape hatch for us that\ndoes not harm real users.  If you and others who know Python better\nthink there isn't any problem that makes it too cumbersome to\nsupport both late 2.x and 3.0/3.1, there is no reason to set the\nfloor at 3.2.\n\nI just have this feeling that we might be better off treating them\nas 0.x releases of a new software called Python3, that happens to be\nsimilar to the Python we know.\n"},{"id":"207219","messageId":"20130118193501.GE31172@serenity.lan","threadId":"32663","inReplyTo":"7vvcauqpn4.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-18T19:35:01Z","receivedAt":"2013-01-18T19:35:01Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Fri, Jan 18, 2013 at 11:04:15AM -0800, Junio C Hamano wrote:\n> John Keeping <john@keeping.me.uk> writes:\n> \n>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n>> index 69f7e9b..baf3b41 100644\n>> --- a/Documentation/CodingGuidelines\n>> +++ b/Documentation/CodingGuidelines\n>> @@ -179,6 +179,22 @@ 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.  In this case we use\n>> +   `from __future__ import unicode_literals` if we need to differentiate\n>> +   Unicode string literals, rather than prefixing Unicode strings with\n>> +   'u' since the latter is not supported in Python versions 3.0 - 3.2.\n> \n> \"In this case\"?  In what case?  This document will stay effective\n> long after you settle one particular backward incompatibility Python\n> 3 introduced, namely, the unicode literal issues.  It is just one\n> \"example\".\n\nI meant \"in the case where you are supporting Python 3\" but I suspect it\nwould be better to move the unicode_literals sentence to a new bullet.\nOr maybe we should just remove it - I haven't seen a case in the current\nGit source where we need Unicode literals.\n\n> That example somehow tells me that early versions of Python 3.x\n> series may be too buggy and not worth worrying about, and we may\n> want to set a floor for Python 3.x series, too, with something\n> like:\n[snip]\n> I am not actively advocating to disqualify early 3.x; I am just\n> suggesting that doing so may be a viable escape hatch for us that\n> does not harm real users.  If you and others who know Python better\n> think there isn't any problem that makes it too cumbersome to\n> support both late 2.x and 3.0/3.1, there is no reason to set the\n> floor at 3.2.\n> \n> I just have this feeling that we might be better off treating them\n> as 0.x releases of a new software called Python3, that happens to be\n> similar to the Python we know.\n\nI originally thought about putting a floor of 3.3 (which is where\nUnicode literals were reintroduced) but that was only released in\nSeptember and as far as I'm aware Unicode literals are the only reason\nto have a restriction on Python 3 versions, given that we support Python\n2.6 - standard library features should be equivalent.\n\nI don't think Python 3.0 is any less stable than any other 3.x release,\nit's just that it was the first release which attempted a clean break\nfrom backwards compatibility.  From the point of view of features\nsupported, Python 2.6 and 3.0 should be roughly equivalent - they were\nreleased together with the intent that 2.6 should make it possible to\nwrite code that ports to 3.0 easily, using 2to3.\n\nAs more people have started trying to support Python 3 in the wild, it\nhas become clear that it is often easier to have a single codebase that\nworks with both Python 2 and Python 3, and not use 2to3.\n\nIt is for this reason that the Unicode literal prefix was reintroduced.\nFrom the specification reintroducing it [1]:\n\n   Complaint: Python 3 shouldn't be made worse just to support porting\n   from Python 2\n\n   This is indeed one of the key design principles of Python 3. However,\n   one of the key design principles of Python as a whole is that\n   \"practicality beats purity\".\n\n\n[1] http://www.python.org/dev/peps/pep-0414/#complaint-python-3-shouldn-t-be-made-worse-just-to-support-porting-from-python-2\n\n\nJohn\n"},{"id":"207221","messageId":"7vip6uqlvl.fsf@alter.siamese.dyndns.org","threadId":"32663","inReplyTo":"20130118193501.GE31172@serenity.lan","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-18T20:25:34Z","receivedAt":"2013-01-18T20:25:34Z","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>>> + - Where required libraries do not restrict us to Python 2, we try to\n>>> +   also be compatible with Python 3.  In this case we use\n>>> +   `from __future__ import unicode_literals` if we need to differentiate\n>>> +   Unicode string literals, rather than prefixing Unicode strings with\n>>> +   'u' since the latter is not supported in Python versions 3.0 - 3.2.\n>> \n>> \"In this case\"?  In what case?  This document will stay effective\n>> long after you settle one particular backward incompatibility Python\n>> 3 introduced, namely, the unicode literal issues.  It is just one\n>> \"example\".\n>\n> I meant \"in the case where you are supporting Python 3\" but I suspect it\n> would be better to move the unicode_literals sentence to a new bullet.\n> Or maybe we should just remove it - I haven't seen a case in the current\n> Git source where we need Unicode literals.\n\nYeah, \"we support 2.x\" and \"we suport 3.x\" may want to be combined,\nbut listing individual specifics as separate points to watch out for\nwould make it much more readable.\n\n> As more people have started trying to support Python 3 in the wild, it\n> has become clear that it is often easier to have a single codebase that\n> works with both Python 2 and Python 3, and not use 2to3.\n>\n> It is for this reason that the Unicode literal prefix was reintroduced.\n\nYes, and from that perspective, placing floor on earlier 3.x makes\ntons of sense, no?\n\nThese early versions may not be unstable in the \"this does not\nbehave as specified in the language specification for 3.x\" sense,\nbut for the purpose of running scripts meant to be executable by\nboth 2.x and 3.x series, the early 3.x versions are not as good as\nlater versions where Python folks started making deliberate effort\nto support them.\n"},{"id":"207229","messageId":"20130118220552.GF31172@serenity.lan","threadId":"32663","inReplyTo":"7vip6uqlvl.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-18T22:05:52Z","receivedAt":"2013-01-18T22:05:52Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Fri, Jan 18, 2013 at 12:25:34PM -0800, Junio C Hamano wrote:\n> John Keeping <john@keeping.me.uk> writes:\n>> As more people have started trying to support Python 3 in the wild, it\n>> has become clear that it is often easier to have a single codebase that\n>> works with both Python 2 and Python 3, and not use 2to3.\n>>\n>> It is for this reason that the Unicode literal prefix was reintroduced.\n> \n> Yes, and from that perspective, placing floor on earlier 3.x makes\n> tons of sense, no?\n> \n> These early versions may not be unstable in the \"this does not\n> behave as specified in the language specification for 3.x\" sense,\n> but for the purpose of running scripts meant to be executable by\n> both 2.x and 3.x series, the early 3.x versions are not as good as\n> later versions where Python folks started making deliberate effort\n> to support them.\n\nAs far as I'm aware (and having reviewed the release notes for 3.1, 3.2\nand 3.3 as well as the planned features for 3.4), Unicode literals are\nthe only feature to have been added that was intended to make it easier\nto support Python 2 and 3 in the same codebase.\n\nGiven that no code currently on pu uses Unicode literals, I don't see a\nreason to specify a minimum version of Python 3 since we're already\nrestricting ourselves to features in 2.6.\n\n\nJohn\n"},{"id":"207231","messageId":"7vwqvap1q9.fsf@alter.siamese.dyndns.org","threadId":"32663","inReplyTo":"20130118220552.GF31172@serenity.lan","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-18T22:26:06Z","receivedAt":"2013-01-18T22:26:06Z","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> On Fri, Jan 18, 2013 at 12:25:34PM -0800, Junio C Hamano wrote:\n>> John Keeping <john@keeping.me.uk> writes:\n>>> As more people have started trying to support Python 3 in the wild, it\n>>> has become clear that it is often easier to have a single codebase that\n>>> works with both Python 2 and Python 3, and not use 2to3.\n>>>\n>>> It is for this reason that the Unicode literal prefix was reintroduced.\n>> \n>> Yes, and from that perspective, placing floor on earlier 3.x makes\n>> tons of sense, no?\n>> \n>> These early versions may not be unstable in the \"this does not\n>> behave as specified in the language specification for 3.x\" sense,\n>> but for the purpose of running scripts meant to be executable by\n>> both 2.x and 3.x series, the early 3.x versions are not as good as\n>> later versions where Python folks started making deliberate effort\n>> to support them.\n>\n> As far as I'm aware (and having reviewed the release notes for 3.1, 3.2\n> and 3.3 as well as the planned features for 3.4), Unicode literals are\n> the only feature to have been added that was intended to make it easier\n> to support Python 2 and 3 in the same codebase.\n\nSo there may be some other incompatibility lurking that we may run\ninto later?\n\n> Given that no code currently on pu uses Unicode literals, I don't see a\n> reason to specify a minimum version of Python 3 since we're already\n> restricting ourselves to features in 2.6.\n\nOK, at least that reasoning need to be kept somewhere, either in the\ndocumentation of in the log message.\n\nThanks.\n"},{"id":"207234","messageId":"20130118230557.GG31172@serenity.lan","threadId":"32663","inReplyTo":"7vwqvap1q9.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] CodingGuidelines: add Python code guidelines","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-18T23:05:57Z","receivedAt":"2013-01-18T23:05:57Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Fri, Jan 18, 2013 at 02:26:06PM -0800, Junio C Hamano wrote:\n> John Keeping <john@keeping.me.uk> writes:\n>> On Fri, Jan 18, 2013 at 12:25:34PM -0800, Junio C Hamano wrote:\n>>> These early versions may not be unstable in the \"this does not\n>>> behave as specified in the language specification for 3.x\" sense,\n>>> but for the purpose of running scripts meant to be executable by\n>>> both 2.x and 3.x series, the early 3.x versions are not as good as\n>>> later versions where Python folks started making deliberate effort\n>>> to support them.\n>>\n>> As far as I'm aware (and having reviewed the release notes for 3.1, 3.2\n>> and 3.3 as well as the planned features for 3.4), Unicode literals are\n>> the only feature to have been added that was intended to make it easier\n>> to support Python 2 and 3 in the same codebase.\n> \n> So there may be some other incompatibility lurking that we may run\n> into later?\n\nI doubt it - enough projects are running on Python 2 and 3 now that I\ndoubt there's anything unexpected left to hit.\n\n>> Given that no code currently on pu uses Unicode literals, I don't see a\n>> reason to specify a minimum version of Python 3 since we're already\n>> restricting ourselves to features in 2.6.\n> \n> OK, at least that reasoning need to be kept somewhere, either in the\n> documentation of in the log message.\n\nI'll put it in the log message when I send this as a proper patch.\n\n\nJohn\n"}]}