Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 2:34 AM, exar...@twistedmatrix.com wrote: I don't think it belongs only in PEP 8 (that's a style guide you're referring to, correct?). It needs to be front and center. This is information that every single user of the stdlib needs in order to use the stdlib correctly. Imagine trying to use a dictionary without knowing about alphabetical ordering. Or driving a car without knowing what lane markers indicate. The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. A similar note could be placed in the C API documentation (with a reference to the detailed policy in PEP 7, perhaps REsTify'ing that PEP in the process in order to link directly to the naming convention section). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 17/11/2010 11:45, Nick Coghlan wrote: On Wed, Nov 17, 2010 at 2:34 AM,exar...@twistedmatrix.com wrote: I don't think it belongs only in PEP 8 (that's a style guide you're referring to, correct?). It needs to be front and center. This is information that every single user of the stdlib needs in order to use the stdlib correctly. Imagine trying to use a dictionary without knowing about alphabetical ordering. Or driving a car without knowing what lane markers indicate. The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. +1 Have we agreed the policy though? The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. +1 This sounds like the right approach to me. All the best, Michael A similar note could be placed in the C API documentation (with a reference to the detailed policy in PEP 7, perhaps REsTify'ing that PEP in the process in order to link directly to the naming convention section). Cheers, Nick. -- http://www.voidspace.org.uk/ READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Am 17.11.2010 12:57, schrieb Michael Foord: On 17/11/2010 11:45, Nick Coghlan wrote: The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. +1 Guido did not said that, though. I'm with Fred and other people that agree that PEPs should be more-less immutable. Let's make a new document (PEP 88?). The reasoning was well laid out here: http://mail.python.org/pipermail/python-dev/2010-November/105641.html http://mail.python.org/pipermail/python-dev/2010-November/105642.html Have we agreed the policy though? Everybody has their own opinion on the matter. This discussion thread is getting too fractured to actually get us far enough with the conclusions. Let's make a PEP and discuss concrete wording on a concrete proposal. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. +1 Yes, point to PEP 88. Best regards, Łukasz Langa ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Mercurial Schedule
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 17/11/10 08:18, Georg Brandl wrote: Am 16.11.2010 19:38, schrieb Jesus Cea: Is there any updated mercurial schedule?. Any impact related with the new 3.2 schedule (three weeks offset)? I've been trying to contact Dirkjan and ask; generally, I don't see much connection to the 3.2 schedule (with the exception that the final migration day should not be a release day.) I can't find the mail now, but I remember that months ago the Mercurial migration schedule was mid-december. I wonder if there is any update. - -- Jesus Cea Avion _/_/ _/_/_/_/_/_/ j...@jcea.es - http://www.jcea.es/ _/_/_/_/ _/_/_/_/ _/_/ jabber / xmpp:j...@jabber.org _/_/_/_/ _/_/_/_/_/ . _/_/ _/_/_/_/ _/_/ _/_/ Things are not so easy _/_/ _/_/_/_/ _/_/_/_/ _/_/ My name is Dump, Core Dump _/_/_/_/_/_/ _/_/ _/_/ El amor es poner tu felicidad en la felicidad de otro - Leibniz -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQCVAwUBTOPP5Zlgi5GaxT1NAQLpSgP/e31LxthlSKgrVYbVhmHKfpdRvQKS2KGb kd0wpIYHhYs/TF0Jwm+Z1r4ylNTaOq0bSL8mJAFqZDnf2IA/jSn9Db/JUk338z7B FIcP0jYLSG0wS+pITRL+f6ifCK5s9SgdbSlPVTdyA6R5G9BDw0T72ZI4WDbnbTEy zqPfvWULiqY= =kPIk -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] python3k vs _ast
hello everybody, migrating Pylint to python3.x, we encounter a little problem : in the tree generated by _ast, if we consider a args node (representing an argument of a function), the lineno (and the col_offset) information disappeared from those nodes. Is there a particular reason for that ? In python2.x, the args nodes were just Name nodes, and as for now we keep them as AssName nodes in astng/pylint and would like to know where it was defined. thx for any information -- Emile Anclin emile.anc...@logilab.fr http://www.logilab.fr/ http://www.logilab.org/ Informatique scientifique et gestion de connaissances ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 17/11/2010 12:37, Łukasz Langa wrote: Am 17.11.2010 12:57, schrieb Michael Foord: On 17/11/2010 11:45, Nick Coghlan wrote: The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. +1 Guido did not said that, though. I think that is a reasonable interpretation, and the suggestion that by in a style guide means create a new style guide is more of a stretch. I'm with Fred and other people that agree that PEPs should be more-less immutable. Let's make a new document (PEP 88?). The reasoning was well laid out here: http://mail.python.org/pipermail/python-dev/2010-November/105641.html http://mail.python.org/pipermail/python-dev/2010-November/105642.html In those emails Fred provides a solution to his most substantial difficulty, that other people base their own documents off pep8, by recommending that extension documents should refer to a specific revision. I don't think those reasons are compelling and the cost of splitting the Python development style guide into multiple documents are higher. (They run the risk of contradicting each other, if you want to find a particular rule you have multiple places to check, there is no single authoritative place to send people, people *wanting* to base documents off the Python style rules now have to refer to multiple places, etc.) So -1 on splitting Python development style guide into multiple documents. Michael Have we agreed the policy though? Everybody has their own opinion on the matter. This discussion thread is getting too fractured to actually get us far enough with the conclusions. Let's make a PEP and discuss concrete wording on a concrete proposal. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. +1 Yes, point to PEP 88. Best regards, Łukasz Langa ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk -- http://www.voidspace.org.uk/ READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
2010/11/17 Michael Foord fuzzy...@voidspace.org.uk: So -1 on splitting Python development style guide into multiple documents. I don't think that the publicness or API stability promises of the standard library are part of a style guide. They're an essential part of the library documentation. They aren't a guide for 3rd-party code, and are specific to the standard library. If we can't come up with something reasonable for the standard library, we *certainly* shouldn't be making recommendations on the matter for 3rd party code. If we do come up with something reasonable, we can recommend it to others later (once field-proven), and without duplication. (Possibly by referring to the standard library documentation, and possibly by refactoring. That's not important until we have something, though.) -Fred -- Fred L. Drake, Jr. fdrake at acm.org A storm broke loose in my mind. --Albert Einstein ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
2010/11/17 Michael Foord fuzzy...@voidspace.org.uk: I don't think those reasons are compelling and the cost of splitting the Python development style guide into multiple documents are higher. (They run the risk of contradicting each other, if you want to find a particular rule you have multiple places to check, there is no single authoritative place to send people, people *wanting* to base documents off the Python style rules now have to refer to multiple places, etc.) So -1 on splitting Python development style guide into multiple documents. Indeed. We don't need to clarify things very often, but the idea of creating a new PEP every time we want to make something explicit that was historically implicit (or otherwise underspecified) is a silly idea. Allowing traceable revisions is what version control is for, and hence why the PEP archive is part of the SVN repository. As far as notifiying current developers of any changes, they will generally be following python-dev anyway, or else will get pulled up on python-checkins if the policy change is significant (and this one really *isn't* all that significant - the only people it will affect are those deciding whether to document or deprecate implicitly public APIs and that almost never happens, since the vast majority of our APIs are explicitly public or private). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 17/11/2010 13:21, Fred Drake wrote: 2010/11/17 Michael Foordfuzzy...@voidspace.org.uk: So -1 on splitting Python development style guide into multiple documents. I don't think that the publicness or API stability promises of the standard library are part of a style guide. They're an essential part of the library documentation. They aren't a guide for 3rd-party code, and are specific to the standard library. PEP 8 *isn't* targeted at third party code - is the development style guide for the Python standard library. This document gives coding conventions for the Python code comprising the standard library in the main Python distribution. The ideal place for informing the Python core developers the naming conventions we should use for our public APIs... (Which is why Guido said that a style guide *is* the right place for this information.) It doesn't mean it shouldn't be information provided to library users as well. (As discussed.) All the best, Michael Foord If we can't come up with something reasonable for the standard library, we *certainly* shouldn't be making recommendations on the matter for 3rd party code. If we do come up with something reasonable, we can recommend it to others later (once field-proven), and without duplication. (Possibly by referring to the standard library documentation, and possibly by refactoring. That's not important until we have something, though.) -Fred -- Fred L. Drake, Jr.fdrake at acm.org A storm broke loose in my mind. --Albert Einstein -- http://www.voidspace.org.uk/ READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Mercurial Schedule
On Wed, Nov 17, 2010 at 13:51, Jesus Cea j...@jcea.es wrote: I can't find the mail now, but I remember that months ago the Mercurial migration schedule was mid-december. I wonder if there is any update. I'm still aiming for that date. I've had some problems getting the test repository together. It's almost done, but I'm on holiday in Boston and NYC this week, so I don't have much time to spend on it. The delay shouldn't be much more than a week, and we'll just compress the testing period such that the migration date should still be about the same, release schedules willing. Georg, if you have any further questions, mail is better than IRC while I'm here. Cheers, Dirkjan ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python3k vs _ast
Seems to be rather a usage question, not a development question (python-dev is about *developing* python, not *using* it). On Wed, Nov 17, 2010 at 01:48:06PM +0100, Emile Anclin wrote: hello everybody, migrating Pylint to python3.x, we encounter a little problem : in the tree generated by _ast, if we consider a args node (representing an argument of a function), the lineno (and the col_offset) information disappeared from those nodes. Is there a particular reason for that ? In python2.x, the args nodes were just Name nodes, and as for now we keep them as AssName nodes in astng/pylint and would like to know where it was defined. thx for any information -- Emile Anclin emile.anc...@logilab.fr http://www.logilab.fr/ http://www.logilab.org/ Informatique scientifique et gestion de connaissances Oleg. -- Oleg Broytmanhttp://phd.pp.ru/p...@phd.pp.ru Programmers don't die, they just GOSUB without RETURN. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 11:21 PM, Fred Drake fdr...@acm.org wrote: 2010/11/17 Michael Foord fuzzy...@voidspace.org.uk: So -1 on splitting Python development style guide into multiple documents. I don't think that the publicness or API stability promises of the standard library are part of a style guide. They're an essential part of the library documentation. They aren't a guide for 3rd-party code, and are specific to the standard library. If we can't come up with something reasonable for the standard library, we *certainly* shouldn't be making recommendations on the matter for 3rd party code. If we do come up with something reasonable, we can recommend it to others later (once field-proven), and without duplication. (Possibly by referring to the standard library documentation, and possibly by refactoring. That's not important until we have something, though.) Would it make people happier if we left PEP 7 and PEP 8 alone, and put the clarification of what constitutes a public API into PEP 5 instead? PEP 5 currently the deprecation policy for language constructs, it would be easy enough to extend it to all public APIs. The library documentation is *not* the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Am 17.11.2010 14:11, schrieb Michael Foord: I don't think those reasons are compelling and the cost of splitting the Python development style guide into multiple documents are higher. (They run the risk of contradicting each other, if you want to find a particular rule you have multiple places to check, there is no single authoritative place to send people, people *wanting* to base documents off the Python style rules now have to refer to multiple places, etc.) So -1 on splitting Python development style guide into multiple documents. Bah, again my English skills failed me in a critical moment ;) I was proposing creation of PEP 88 to supersede PEP 8. This would be better IMO for the following reasons: 1. Existing projects wouldn't have to explain afterwards why they differ from PEP 8, e.g. in terms of public/private API declaration. Your project claims PEP8 conformance! Why don't you use __all__? Ah, that was before they've added this part to PEP8. 2. All other projects (new and old) would have a much more explicit (better than implicit) sign that *something significant has changed* in the recommended style. 3. As someone already said, PEP8 is not visible enough. Transition from PEP 8 to PEP 88 could help to make some hype that would help raise the awareness within the community. Mutating PEP8 is bad form. We fight mercilessly over source code backwards compatibility so I think PEPs should be taken just as seriously in that regard. Łukasz ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python3k vs _ast
2010/11/17 Oleg Broytman p...@phd.pp.ru: Seems to be rather a usage question, not a development question (python-dev is about *developing* python, not *using* it). Well, technically I think it's a feature request. On Wed, Nov 17, 2010 at 01:48:06PM +0100, Emile Anclin wrote: hello everybody, migrating Pylint to python3.x, we encounter a little problem : in the tree generated by _ast, if we consider a args node (representing an argument of a function), the lineno (and the col_offset) information disappeared from those nodes. Is there a particular reason for that ? In python2.x, the args nodes were just Name nodes, and as for now we keep them as AssName nodes in astng/pylint and would like to know where it was defined. I wouldn't object to adding them back if you want to file a bug report. -- Regards, Benjamin ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan ncogh...@gmail.com wrote: The library documentation is *not* the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call. Quibbling can happen on the mailing list, where it can be ignored by those who aren't interested. But the documentation is the right place to document what we come up with for the standard library. I expect what the tools do will inform any decisions, and the tools (those in the stdlib) will henceforth be maintained with that in mind. I *am* suggesting that the scope of this be restricted to what's appropriate for the standard library, rather than a general recommendation for others. Third-party projects are free to use what we come up with, or provide their own policies. That's theirs to decide, and I see no value in interfering with that. -Fred -- Fred L. Drake, Jr. fdrake at acm.org A storm broke loose in my mind. --Albert Einstein ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 17/11/2010 13:31, Łukasz Langa wrote: Am 17.11.2010 14:11, schrieb Michael Foord: I don't think those reasons are compelling and the cost of splitting the Python development style guide into multiple documents are higher. (They run the risk of contradicting each other, if you want to find a particular rule you have multiple places to check, there is no single authoritative place to send people, people *wanting* to base documents off the Python style rules now have to refer to multiple places, etc.) So -1 on splitting Python development style guide into multiple documents. Bah, again my English skills failed me in a critical moment ;) I was proposing creation of PEP 88 to supersede PEP 8. This would be better IMO for the following reasons: 1. Existing projects wouldn't have to explain afterwards why they differ from PEP 8, e.g. in terms of public/private API declaration. Your project claims PEP8 conformance! Why don't you use __all__? Ah, that was before they've added this part to PEP8. 2. All other projects (new and old) would have a much more explicit (better than implicit) sign that *something significant has changed* in the recommended style. 3. As someone already said, PEP8 is not visible enough. Transition from PEP 8 to PEP 88 could help to make some hype that would help raise the awareness within the community. Mutating PEP8 is bad form. We fight mercilessly over source code backwards compatibility so I think PEPs should be taken just as seriously in that regard. Given the following: http://code.python.org/hg/peps/log/6b223d6b8b24/pep-0008.txt Anyone who thinks that PEP 8 is immutable (and should remain so) is already wrong... As discussed, the goal is to codify what is already considered best practise within the wider community and the standard library *anyway*. So in practise this won't be a great surprise or change. As to the publicity, PEP 8 is both the most widely known PEP and the most widely known Python style guide. This isn't an argument for letting it rot, nor for deprecating it and invalidating all those tutorials / developers / links / books that consider it authoritative. Better to carefully and slowly evolve it as practise and the language change. For those wanting immutable versions we provide that in the form of specific revisions. All the best, Michael Łukasz -- http://www.voidspace.org.uk/ READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Ben Finney wrote: I don't know about Guido, but I'd be −1 on suggestions to add more normative information to PEP 7, PEP 8, PEP 257, or any other established style guide PEP. I certainly don't want to have to keep going back to the same documents frequently just to see if the set of recommendations I already know has changed recently. This is not a problem unique to any specific PEP. How do we learn about any changes that might interest us? What are the alternatives? - our knowledge is fixed to what we knew at some particular date, and gets further and further obsolete as time goes by; - we actively search out new knowledge; - we wait for somebody to tell us that something we knew has changed. (E.g. I was rather surprised to learn that, sometime over the last few years, the number of extra-solar planets known to astronomers have increased from the one or two I was aware of to multiple dozens.) All three strategies have advantages and disadvantages. Regardless of whether future versions of the style-guide are called PEP 8 or whether they are given new names (PEP 8 - PEP 88 - ...), we have the identical problem -- how do we know whether or not there is a new version of the style guide to look for? In twelve months time, how sure will we be that PEP 88 is the most recent version to look for? Perhaps we missed the release of PEP 95. The one advantage of giving each revision of the document an updated name is that, under some circumstances, we *might* be able to detect a new revision easily. If I think that PEP 88 is the most recent version, and somebody says that the recommended style guide is PEP 89, I might: - think that he merely made a mistake, and meant to say 88; or - think that there is a new document for me to look at. Rather, I took Guido's mention of “this belongs in a style guide” as suggesting a *new* style guide. Perhaps one that explicitly obsoletes an existing one or perhaps not; either way, the updated normative recommendations are in a new document with a new name, so that one knows whether one has already read it. How do you know which is the most recent version of the style guide to look at? Instead of doing a O(1) lookup of PEP 8, you have to follow a potentially O(N) search: PEP 8 is obsoleted by PEP 88... go and look at PEP 88. PEP 88 is obsoleted by PEP 93... go at look at PEP 93. PEP 93 is obsoleted by PEP 123... go and look at PEP 123. PEP 123 doesn't contain an obsoleted by notice, so: (1) either it is the current document, or (2) it has been obsoleted, but the link to the new version was missed, and it is now very hard to discover what the current document is called. Personally, I don't think the current PEP arrangement is broken enough to change it. Each PEP is already tracked in VCS and history is available for it. There's insufficient advantage, and some disadvantage, to splitting each revision of the PEPs into new documents with new names. -1 on the idea. -- Steven ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python3k vs _ast
On Wednesday 17 November 2010 14:36:37 Benjamin Peterson wrote: I wouldn't object to adding them back if you want to file a bug report. Ok, thank you for quick reply. here is the issue : http://bugs.python.org/issue10445 -- Emile Anclin emile.anc...@logilab.fr http://www.logilab.fr/ http://www.logilab.org/ Informatique scientifique et gestion de connaissances ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Łukasz Langa wrote: Mutating PEP8 is bad form. We fight mercilessly over source code backwards compatibility so I think PEPs should be taken just as seriously in that regard. There's no comparison between the two. If you change your library's API -- not source code, it doesn't matter if the source code changes so long as the interface remains backwards compatible -- then you will break other people's code. If we change PEP 8, then all that will happen is that some people's coding style will no longer be exactly compatible with PEP 8. Their code will continue to work. -- Steven ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 11:45 PM, Fred Drake fdr...@acm.org wrote: On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan ncogh...@gmail.com wrote: The library documentation is *not* the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call. Quibbling can happen on the mailing list, where it can be ignored by those who aren't interested. But the documentation is the right place to document what we come up with for the standard library. I expect what the tools do will inform any decisions, and the tools (those in the stdlib) will henceforth be maintained with that in mind. I *am* suggesting that the scope of this be restricted to what's appropriate for the standard library, rather than a general recommendation for others. Third-party projects are free to use what we come up with, or provide their own policies. That's theirs to decide, and I see no value in interfering with that. The standard library documentation should say that the public API is what the documentation says it is. Officially, anyone going outside those documented APIs should not be surprised if things get removed or changed arbitrarily without warning. That has long been the python-dev policy and I, for one, don't think it should change. What we're talking about in this thread is what to do in the grey area of APIs which are not included in the official documentation, but also don't have names starting with an underscore so they look public when reading the source code or exploring the API in the interactive interpreter. It *may* be appropriate for the standard library documentation to acknowledge that this grey area exists (I'm not yet convinced on that point), but it definitely should *not* be encouraging anyone to rely on it or on our policies for dealing with it. The policy we're aiming to clarify here is what we should do when we come across standard library APIs that land in the grey area, with there being two appropriate ways to deal with them: 1. Document them and make them officially public 2. Deprecate the public names and make them officially private (with the public names later removed in accordance with normal deprecation procedures) The actual approach taken will vary on a case-by-case basis (and is a little trickier in the case of module level globals, since those can't be deprecated properly), but is always aimed at bringing the standard library more into line with the official position (i.e. APIs are either public-and-documented or private). So the official policy from a language *user* point of view would remain unchanged (i.e. if it isn't documented, you're on your own). As a *pragmatic* policy, however, we would explicitly acknowledge that developers may inadvertently use an undocumented API without realising that it isn't technically public, and hence apply the normal deprecation process even though the official policy says we don't have to. Regards, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python3k vs _ast
On Wed, 17 Nov 2010 07:36:37 -0600, Benjamin Peterson benja...@python.org wrote: 2010/11/17 Oleg Broytman p...@phd.pp.ru: Seems to be rather a usage question, not a development question (python-dev is about *developing* python, not *using* it). Well, technically I think it's a feature request. On Wed, Nov 17, 2010 at 01:48:06PM +0100, Emile Anclin wrote: hello everybody, migrating Pylint to python3.x, we encounter a little problem : in the tree generated by _ast, if we consider a args node (representing an argument of a function), the lineno (and the col_offset) information disappeared from those nodes. Is there a particular reason for that ? In python2.x, the args nodes were just Name nodes, and as for now we keep them as AssName nodes in astng/pylint and would like to know where it was defined. I wouldn't object to adding them back if you want to file a bug report. It also seems to me that it was a perfectly appropriate question for this list. The question was why did you developers drop this (obscure) feature that we depend on in Python3? I don't think that question would make sense on python-list. Granted, there's a fuzzy line there, but pylint is really development infrastructure :) The python-porting list would have been a good alternate choice. -- R. David Murray www.bitdance.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 17/11/2010 14:19, Nick Coghlan wrote: On Wed, Nov 17, 2010 at 11:45 PM, Fred Drakefdr...@acm.org wrote: On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlanncogh...@gmail.com wrote: The library documentation is *not* the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call. Quibbling can happen on the mailing list, where it can be ignored by those who aren't interested. But the documentation is the right place to document what we come up with for the standard library. I expect what the tools do will inform any decisions, and the tools (those in the stdlib) will henceforth be maintained with that in mind. I *am* suggesting that the scope of this be restricted to what's appropriate for the standard library, rather than a general recommendation for others. Third-party projects are free to use what we come up with, or provide their own policies. That's theirs to decide, and I see no value in interfering with that. The standard library documentation should say that the public API is what the documentation says it is. Officially, anyone going outside those documented APIs should not be surprised if things get removed or changed arbitrarily without warning. That has long been the python-dev policy and I, for one, don't think it should change. What we're talking about in this thread is what to do in the grey area of APIs which are not included in the official documentation, but also don't have names starting with an underscore so they look public We're *also* discussing codifying the naming conventions (or using __all__) within the standard library, so it isn't just about deprecations (which is why I think PEP 8 rather than PEP 5). This is so that in the future if a name looks public users can have more confidence that it actually is... Obviously what to do about modules that don't follow these rules currently is a big part of it (and how the discussion started). All the best, Michael when reading the source code or exploring the API in the interactive interpreter. It *may* be appropriate for the standard library documentation to acknowledge that this grey area exists (I'm not yet convinced on that point), but it definitely should *not* be encouraging anyone to rely on it or on our policies for dealing with it. The policy we're aiming to clarify here is what we should do when we come across standard library APIs that land in the grey area, with there being two appropriate ways to deal with them: 1. Document them and make them officially public 2. Deprecate the public names and make them officially private (with the public names later removed in accordance with normal deprecation procedures) The actual approach taken will vary on a case-by-case basis (and is a little trickier in the case of module level globals, since those can't be deprecated properly), but is always aimed at bringing the standard library more into line with the official position (i.e. APIs are either public-and-documented or private). So the official policy from a language *user* point of view would remain unchanged (i.e. if it isn't documented, you're on your own). As a *pragmatic* policy, however, we would explicitly acknowledge that developers may inadvertently use an undocumented API without realising that it isn't technically public, and hence apply the normal deprecation process even though the official policy says we don't have to. Regards, Nick. -- http://www.voidspace.org.uk/ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] I need help with IO testuite
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi all. I am modifying IO module for Python 3.2, and I am unable to understand the mechanism used in IO testsuite to test both the C and the Python implementation. In particular I need to test that the implementation passes some parameters to the OS. The module uses Mock classes, but I think Mock is something else, and I don't see how it interpose between the C/Python code and the OS. If somebody could explain the mechanism a bit... Thanks for your time and attention. Some background: http://bugs.python.org/issue10142 - -- Jesus Cea Avion _/_/ _/_/_/_/_/_/ j...@jcea.es - http://www.jcea.es/ _/_/_/_/ _/_/_/_/ _/_/ jabber / xmpp:j...@jabber.org _/_/_/_/ _/_/_/_/_/ . _/_/ _/_/_/_/ _/_/ _/_/ Things are not so easy _/_/ _/_/_/_/ _/_/_/_/ _/_/ My name is Dump, Core Dump _/_/_/_/_/_/ _/_/ _/_/ El amor es poner tu felicidad en la felicidad de otro - Leibniz -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQCVAwUBTOPnJplgi5GaxT1NAQLVqQP/cf9+hdLdoSMzY+cSquq7YZMiQOQ0aMEH ZRn+su4F3qg5e8MgEQOXFj9uGEjVDLwonE4nBZ+T3ovBcPCyGaLB/K/YttZGVM5/ O3gpzZss9bkMvuWQCblyEJp8uzJC831AwPDMg1Q0nbMiTnJlW5dY1CX9BD0gYPBW oIVBt2oBfCI= =hq7M -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Proposed adjustments to PEP 0 generation
The lists of Meta-PEPs and Other Informational PEPs at the beginning of PEP 0 are starting to get a little long, and contain some outdated information that doesn't really deserve pride of place at the top of the PEP index. If I don't hear any objections in this thread, I plan to make the following tweaks to the PEP 0 generator soonish: - make these two lists respect the Withdrawn and Rejected flags (i.e. taking the relevant PEPs out of this list and dropping them into later categories) - adding a new Historical category for PEPs that have served their purpose and are no longer of immediate interest (primarily old release PEPs, but also the old SVN migration PEP, the DVCS study and PEP 42) Regards, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] I need help with IO testuite
On Wed, 17 Nov 2010 15:31:02 +0100 Jesus Cea j...@jcea.es wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi all. I am modifying IO module for Python 3.2, and I am unable to understand the mechanism used in IO testsuite to test both the C and the Python implementation. In particular I need to test that the implementation passes some parameters to the OS. The module uses Mock classes, but I think Mock is something else, and I don't see how it interpose between the C/Python code and the OS. It doesn't interpose between Python and the OS: it mocks the OS. It is, therefore, a mock (!). Consequently, if you want to test that parameters are passed to the OS, you shouldn't use a mock, but an actual file. There are several tests which already do that, it shouldn't be too hard to write your own. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Thu, Nov 18, 2010 at 12:25 AM, Michael Foord fuzzy...@voidspace.org.uk wrote: We're *also* discussing codifying the naming conventions (or using __all__) within the standard library, so it isn't just about deprecations (which is why I think PEP 8 rather than PEP 5). This is so that in the future if a name looks public users can have more confidence that it actually is... I deliberately glossed over that, since my stance on the naming conventions is don't change them (i.e. PEP 8 already says that a leading underscore is an internal use indicator, and I think that's how we should guide the clarification of our deprecation policy - just carving out an exception for imported modules). My original question related to dealing with the grey area in the deprecation policy (i.e. wanting to remove an API that was undocumented, but had a public name) and I'm happy that the existing style guide does answer my question (even though the implications aren't necessarily obvious). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python3k vs _ast
On Wed, Nov 17, 2010 at 09:19:35AM -0500, R. David Murray wrote: On Wed, 17 Nov 2010 07:36:37 -0600, Benjamin Peterson benja...@python.org wrote: 2010/11/17 Oleg Broytman p...@phd.pp.ru: Seems to be rather a usage question, not a development question (python-dev is about *developing* python, not *using* it). Well, technically I think it's a feature request. On Wed, Nov 17, 2010 at 01:48:06PM +0100, Emile Anclin wrote: hello everybody, migrating Pylint to python3.x, we encounter a little problem : in the tree generated by _ast, if we consider a args node (representing an argument of a function), the lineno (and the col_offset) information disappeared from those nodes. Is there a particular reason for that ? In python2.x, the args nodes were just Name nodes, and as for now we keep them as AssName nodes in astng/pylint and would like to know where it was defined. I wouldn't object to adding them back if you want to file a bug report. It also seems to me that it was a perfectly appropriate question for this list. The question was why did you developers drop this (obscure) feature that we depend on in Python3? The problem for me is the wording. A question like why did you developers drop a feature? is certainly a development question, while like to know where it was defined seems more like a usage question. I apologize for misunderstanding. I don't think that question would make sense on python-list. Granted, there's a fuzzy line there, but pylint is really development infrastructure :) The python-porting list would have been a good alternate choice. -- R. David Murray www.bitdance.com Oleg. -- Oleg Broytmanhttp://phd.pp.ru/p...@phd.pp.ru Programmers don't die, they just GOSUB without RETURN. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] I need help with IO testuite
On Thu, Nov 18, 2010 at 12:31 AM, Jesus Cea j...@jcea.es wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi all. I am modifying IO module for Python 3.2, and I am unable to understand the mechanism used in IO testsuite to test both the C and the Python implementation. In particular I need to test that the implementation passes some parameters to the OS. The module uses Mock classes, but I think Mock is something else, and I don't see how it interpose between the C/Python code and the OS. The Mock refers to stubbing out or substituting various layers of the IO stack with the Python implementations in the test file. It isn't related specifically to the C/Python switching. If somebody could explain the mechanism a bit... The actual C/Python switching happens later in the file. It is best to start from the bottom of the file (with the list of test cases that are actually executed) and work your way up from there. For what Amaury is talking about, what you can test is that the higher layers of the IO stack (e.g. BufferedReader) correctly pass the new flags down to the RawIO layer. You're correct that you can't really test that RawIO is actually passing the flags down to the OS. However, if you have a way to check whether the filesystem in use is ZFS, you may be able to create a conditionally executed test, such that correct behaviour can be verified just by running on a machine that uses ZFS for its temp directory. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 11/17/2010 09:16 AM, Steven D'Aprano wrote: Ben Finney wrote: I don't know about Guido, but I'd be −1 on suggestions to add more normative information to PEP 7, PEP 8, PEP 257, or any other established style guide PEP. I certainly don't want to have to keep going back to the same documents frequently just to see if the set of recommendations I already know has changed recently. This is not a problem unique to any specific PEP. How do we learn about any changes that might interest us? What are the alternatives? - our knowledge is fixed to what we knew at some particular date, and gets further and further obsolete as time goes by; - we actively search out new knowledge; - we wait for somebody to tell us that something we knew has changed. (E.g. I was rather surprised to learn that, sometime over the last few years, the number of extra-solar planets known to astronomers have increased from the one or two I was aware of to multiple dozens.) All three strategies have advantages and disadvantages. Regardless of whether future versions of the style-guide are called PEP 8 or whether they are given new names (PEP 8 - PEP 88 - ...), we have the identical problem -- how do we know whether or not there is a new version of the style guide to look for? In twelve months time, how sure will we be that PEP 88 is the most recent version to look for? Perhaps we missed the release of PEP 95. The one advantage of giving each revision of the document an updated name is that, under some circumstances, we *might* be able to detect a new revision easily. If I think that PEP 88 is the most recent version, and somebody says that the recommended style guide is PEP 89, I might: - think that he merely made a mistake, and meant to say 88; or - think that there is a new document for me to look at. Rather, I took Guido's mention of “this belongs in a style guide” as suggesting a *new* style guide. Perhaps one that explicitly obsoletes an existing one or perhaps not; either way, the updated normative recommendations are in a new document with a new name, so that one knows whether one has already read it. How do you know which is the most recent version of the style guide to look at? Instead of doing a O(1) lookup of PEP 8, you have to follow a potentially O(N) search: PEP 8 is obsoleted by PEP 88... go and look at PEP 88. PEP 88 is obsoleted by PEP 93... go at look at PEP 93. PEP 93 is obsoleted by PEP 123... go and look at PEP 123. PEP 123 doesn't contain an obsoleted by notice, so: (1) either it is the current document, or (2) it has been obsoleted, but the link to the new version was missed, and it is now very hard to discover what the current document is called. Personally, I don't think the current PEP arrangement is broken enough to change it. Each PEP is already tracked in VCS and history is available for it. There's insufficient advantage, and some disadvantage, to splitting each revision of the PEPs into new documents with new names. -1 on the idea. FWIW, Guido recently ruled that updating PEP 333 to indicate how WSGI would work in Python3 was not appropriate, and suggested instead a new PEP (), stating[1]: Of those, IMO only textual clarifications ought to be made to an existing, accepted, widely implemented standards-track PEP. Note that the BDFL ruled this way even though the changes to PEP 333 were essentially clarifications which applied only to Python 3: the existing Python 2 semantics would have rmeained the same.[2] [1] http://permalink.gmane.org/gmane.comp.python.devel/117269 [2] http://permalink.gmane.org/gmane.comp.python.devel/117249 Tres. - -- === Tres Seaver +1 540-429-0999 tsea...@palladion.com Palladion Software Excellence by Designhttp://palladion.com -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAkzj7ZwACgkQ+gerLs4ltQ7mPgCg1TpA+rF0WigLGB1xeuUTyRF7 MLQAnjGUgWZUqQBLfbwl6RanA+ME4Hth =zuiQ -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] I need help with IO testuite
On Thu, Nov 18, 2010 at 12:58 AM, Nick Coghlan ncogh...@gmail.com wrote: For what Amaury is talking about, what you can test is that the higher layers of the IO stack (e.g. BufferedReader) correctly pass the new flags down to the RawIO layer. You're correct that you can't really test that RawIO is actually passing the flags down to the OS. However, if you have a way to check whether the filesystem in use is ZFS, you may be able to create a conditionally executed test, such that correct behaviour can be verified just by running on a machine that uses ZFS for its temp directory. On further thought, the test should probably be unconditional - just allow a ValueError as an acceptable result that indicates the underlying filesystem isn't ZFS. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 9:19 AM, Nick Coghlan ncogh...@gmail.com wrote: .. The standard library documentation should say that the public API is what the documentation says it is. Officially, anyone going outside those documented APIs should not be surprised if things get removed or changed arbitrarily without warning. That has long been the python-dev policy and I, for one, don't think it should change. +1 That's another reason why it is appropriate to document this in both Library Reference and the Developers Guide (whatever it is). In the Library Reference we can say point-blank: This is the authoritative documentation of what Python Library provides. Anything not mentioned here is subject to change between releases without notice. In the Developers Guide, guide, however we can take a more nuanced approach that would start with a general policy that changing existing APIs public or not is costly and should not be done without significant offsetting benefit. More on this below. What we're talking about in this thread is what to do in the grey area of APIs which are not included in the official documentation, but also don't have names starting with an underscore so they look public when reading the source code or exploring the API in the interactive interpreter. It *may* be appropriate for the standard library documentation to acknowledge that this grey area exists (I'm not yet convinced on that point), but it definitely should *not* be encouraging anyone to rely on it or on our policies for dealing with it. Users will venture into grey area regardless of whether its existence is acknowledged or not. Developers Guide should take this into consideration, but there is no need to encourage this practice in the Library Reference. In the Developers Guide, we can list a set of factors that need to be considered when changing or removing an undocumented API. For example: 1. Does it start with an underscore? 2. Is __all__ defined for the module? Id so, is the name in __all__? 3. Is API name well chosen for what it does? 4. How old is the module? Was is written before modern policies have been adopted? 5. Is API used in the standard library outside of the module? 6. Is API broken? Can it be fixed? (If it was broken in several releases and nobody complained - it is ok to remove.) 7. Is API used? General google search or google code search can give an insight. The decision to remove an API should be always done on a case by case basis. Purely style compliance changes such as let's add __all__ and rename all names not in all by prepending an underscore should always add old names back as deprecated aliases. (Breaking from xyz import * by adding __all__ to xyz is probably ok because code using from xyz import * may be broken by any addition to xyz and users have been warned.) .. So the official policy from a language *user* point of view would remain unchanged (i.e. if it isn't documented, you're on your own). As a *pragmatic* policy, however, we would explicitly acknowledge that developers may inadvertently use an undocumented API without realising that it isn't technically public, and hence apply the normal deprecation process even though the official policy says we don't have to. +1 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Nov 17, 2010, at 9:19 AM, Nick Coghlan wrote: (and is a little trickier in the case of module level globals, since those can't be deprecated properly) People keep saying this, but there have already been examples shown of how to do it. I actually think that python should include a way to do so standard -- it's a reasonable enough desire, as shown by how many times in this thread the inability to do so has been mentioned. If the existing working 3rd-party mechanisms aren't good enough for python-dev standards, come up with a new way... James ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 7:24 AM, James Y Knight f...@fuhm.net wrote: On Nov 17, 2010, at 9:19 AM, Nick Coghlan wrote: (and is a little trickier in the case of module level globals, since those can't be deprecated properly) People keep saying this, but there have already been examples shown of how to do it. I actually think that python should include a way to do so standard -- it's a reasonable enough desire, as shown by how many times in this thread the inability to do so has been mentioned. If the existing working 3rd-party mechanisms aren't good enough for python-dev standards, come up with a new way... That's quite the distraction from the current thread though. Start discussing it on python-ideas, or submit a code fix, or something in between. But the hackish way that some 3rd party frameworks use (replacing the module object with a class instance in sys.modules) is clearly not right for the standard library (I'll explain on python-ideas if you insist). -- --Guido van Rossum (python.org/~guido) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Tue, Nov 16, 2010 at 1:31 PM, Ben Finney ben+pyt...@benfinney.id.au wrote: I don't know about Guido, but I'd be -1 on suggestions to add more normative information to PEP 7, PEP 8, PEP 257, or any other established style guide PEP. I certainly don't want to have to keep going back to the same documents frequently just to see if the set of recommendations I already know has changed recently. Rather, I took Guido's mention of this belongs in a style guide as suggesting a *new* style guide. Perhaps one that explicitly obsoletes an existing one or perhaps not; either way, the updated normative recommendations are in a new document with a new name, so that one knows whether one has already read it. That's not what I meant. In the case of style guides I think it is totally appropriate to update the PEP as new rules are developed or existing ones are clarified (or even changed). I certainly don't want to get into the situation where the style guide is spread over multiple documents that need to be taken together to make sense. It's not like PEP 8 specifies an API that is going to break code in the future -- it is a set of conventions. You could create a new PEP or move the style guide out of the PEP system (a not unreasonable option) but the effect of changes to the style guide is the same: some fraction of old code will become non-compliant. So what? A style guide is just that -- a guide for coding style. Every good style guide contains an escape clause: in PEP 8 it is the section named A Foolish Consistency is the Hobgoblin of Little Minds. I've seen many unreasonable uses of style guides. This is a recurring theme with Google's internal style guides too. For example, some people get in an argument with a code reviewer about what's the best way to do something, and they can't agree -- so now they want a resolution in the style guide, no matter how specific their argument is to one particular context. Other people claim you cannot change a style guide because it would make existing code unnecessarily non-compliant. There are the people who insist that the style guide be followed mindlessly, even in situations where using a different style would be clearly better. Then there are the people who want to update the entire code base to become compliant after each style change. Etc., etc. All I want to say is, people lighten up. The style guide can't solve all your problems. You are never going to have all code compliant. Use the style guide when it helps, ignore it when it's in the way. Finally, there's the issue of the scope of PEP 8. Its heading says that it applies to the stdlib. The reason I put this in was so that 3rd party developers who disagreed with (part of) PEP 8 would not feel obligated to follow it. At the same time I would hope that most people see its value and follow (most of) it for their own code, accepting that a more universal set of conventions helps readability of all code. I would not be against changes to the style guide that emphasize that some rules apply specifically to the stdlib (the rules about mostly not using non-ASCII characters come to mind) and even to include some normative rules for stdlib developers (e.g. exactly how to use __all__ and private names). But we cannot hope that all stdlib modules will all look exactly alike. It is the work of many contributors, over many years, with different backgrounds and intentions. That's fine. Let's try to make new stdlib modules use the best style we can think of, but limit the time spent fretting over code that's already there. -- --Guido van Rossum (python.org/~guido) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi, everybody. I am glad to say I am installing an OpenIndiana zone (Openindiana is a fork of Indiana, a distribution of OpenSolaris) with the aim to be a buildbot for python development. This machine has plenty of disk (even SSD!), CPU and memory for the task. I am reading http://wiki.python.org/moin/BuildBot . I have installed buildbotslave already, but I need passwords, etc., to link to python buildbot infraestructure. The machine is behind a NAT system, so any incoming connection will need to be documented and a port mapping request to be done. So, after installing buildbotslave, what is the next step?. Thanks to OpenIndiana staff, specially Alasdair Lumsden, for providing the physical resources for this attempt. - -- Jesus Cea Avion _/_/ _/_/_/_/_/_/ j...@jcea.es - http://www.jcea.es/ _/_/_/_/ _/_/_/_/ _/_/ jabber / xmpp:j...@jabber.org _/_/_/_/ _/_/_/_/_/ . _/_/ _/_/_/_/ _/_/ _/_/ Things are not so easy _/_/ _/_/_/_/ _/_/_/_/ _/_/ My name is Dump, Core Dump _/_/_/_/_/_/ _/_/ _/_/ El amor es poner tu felicidad en la felicidad de otro - Leibniz -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQCVAwUBTOP9pplgi5GaxT1NAQLmWQP6AqEGqEX3b50qKTP2MrkJwYQ8pXCOJm+6 fGB4jpH+i47mzgSOtANvrp1N5qOmHXzjbdWlVrL2/7ZOeLiGWSnq/ZvpTrYaysU3 o2zG4rhk48jsSYE7u0EoSKk272LmAiTU6WBSt6ZMzOGWIQxdjMhs/OVanpFybBc0 rCbATfdJ3hQ= =rIqM -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
On Wed, 17 Nov 2010 17:07:02 +0100 Jesus Cea j...@jcea.es wrote: I am reading http://wiki.python.org/moin/BuildBot . I have installed buildbotslave already, but I need passwords, etc., to link to python buildbot infraestructure. The machine is behind a NAT system, so any incoming connection will need to be documented and a port mapping request to be done. There is no incoming connection; however, a bunch of outgoing connections are made to various hosts by various tests, so it's better if there's no overzealous firewall in-between. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Nov 17, 2010, at 10:30 AM, Guido van Rossum wrote: On Wed, Nov 17, 2010 at 7:24 AM, James Y Knight f...@fuhm.net wrote: On Nov 17, 2010, at 9:19 AM, Nick Coghlan wrote: (and is a little trickier in the case of module level globals, since those can't be deprecated properly) People keep saying this, but there have already been examples shown of how to do it. I actually think that python should include a way to do so standard -- it's a reasonable enough desire, as shown by how many times in this thread the inability to do so has been mentioned. If the existing working 3rd-party mechanisms aren't good enough for python-dev standards, come up with a new way... That's quite the distraction from the current thread though. Start discussing it on python-ideas, or submit a code fix, or something in between. But the hackish way that some 3rd party frameworks use (replacing the module object with a class instance in sys.modules) is clearly not right for the standard library (I'll explain on python-ideas if you insist). I just don't want people to use the current lack as an excuse to simply remove module attributes without prior deprecation (or make a compatibility policy which recommends doing such a thing). I'll leave it up to the experts on this list (or python-ideas...) to determine how to implement a module-level deprecation in a way that isn't considered hackish. (Or, if there is no such way, there's also the alternative of simply never removing module-level names.) James ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 8:23 AM, James Y Knight f...@fuhm.net wrote: On Nov 17, 2010, at 10:30 AM, Guido van Rossum wrote: On Wed, Nov 17, 2010 at 7:24 AM, James Y Knight f...@fuhm.net wrote: On Nov 17, 2010, at 9:19 AM, Nick Coghlan wrote: (and is a little trickier in the case of module level globals, since those can't be deprecated properly) People keep saying this, but there have already been examples shown of how to do it. I actually think that python should include a way to do so standard -- it's a reasonable enough desire, as shown by how many times in this thread the inability to do so has been mentioned. If the existing working 3rd-party mechanisms aren't good enough for python-dev standards, come up with a new way... That's quite the distraction from the current thread though. Start discussing it on python-ideas, or submit a code fix, or something in between. But the hackish way that some 3rd party frameworks use (replacing the module object with a class instance in sys.modules) is clearly not right for the standard library (I'll explain on python-ideas if you insist). I just don't want people to use the current lack as an excuse to simply remove module attributes without prior deprecation (or make a compatibility policy which recommends doing such a thing). I'll leave it up to the experts on this list (or python-ideas...) to determine how to implement a module-level deprecation in a way that isn't considered hackish. (Or, if there is no such way, there's also the alternative of simply never removing module-level names.) Deprecation doesn't *require* logging a warning or raising an exception. You can also add a note to the docs, or if it is undocumented, just add a comment to the code. (Though if it is in widespread use despite being undocumented, a better way would be to document it first -- as immediately deprecated if necessary.) Deprecation is in the end a way to give people advance warning about future changes. The mechanism of the warning doesn't always have to be implemented by the interpreter/compiler/parser or whatever other tool. -- --Guido van Rossum (python.org/~guido) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 17/11/10 17:23, Antoine Pitrou wrote: There is no incoming connection; however, a bunch of outgoing connections are made to various hosts by various tests, so it's better if there's no overzealous firewall in-between. I know that, just confirming. You'll need to get someone to create the slavename/slavepasswd on dinsdale.python.org before doing this. Talk to someone like Antoine Pitrou, Martin von Löwis, Anthony or Neal Norwitz to do this. #python-dev on freenode is a good place to ask. ¿Could you provide the connection credential?. I rather prefer to skip the IRC (I am a XMPP guy), but I can connect to freenode if you need it. - -- Jesus Cea Avion _/_/ _/_/_/_/_/_/ j...@jcea.es - http://www.jcea.es/ _/_/_/_/ _/_/_/_/ _/_/ jabber / xmpp:j...@jabber.org _/_/_/_/ _/_/_/_/_/ . _/_/ _/_/_/_/ _/_/ _/_/ Things are not so easy _/_/ _/_/_/_/ _/_/_/_/ _/_/ My name is Dump, Core Dump _/_/_/_/_/_/ _/_/ _/_/ El amor es poner tu felicidad en la felicidad de otro - Leibniz -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQCVAwUBTOQIPplgi5GaxT1NAQJJggP7B+kMnhEpZQlxCy8E95Qs3Q70zJmQJXjj aodjURYlIW9PJLXUMH0dhiK3Oggsl0k/iq44pL1fu+LRpgD7bo9Snxi4IBgYlArj IMGThrpdEHKVh0r2TkVsmkCA6pAwV3crM3170ItzSDqXZPmGQgqdqFuD5fk8xQl2 caqC+sTcJjw= =zbQs -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Nov 17, 2010, at 11:38 AM, Guido van Rossum wrote: Deprecation doesn't *require* logging a warning or raising an exception. You can also add a note to the docs, or if it is undocumented, just add a comment to the code. (Though if it is in widespread use despite being undocumented, a better way would be to document it first -- as immediately deprecated if necessary.) Deprecation is in the end a way to give people advance warning about future changes. The mechanism of the warning doesn't always have to be implemented by the interpreter/compiler/parser or whatever other tool. Well, that's certainly a possible policy. I'd suggest that adding notes to the docs after-the-fact is a singularly ineffective way of giving people advance warning of feature removal compared to having the interpreter/compiler/parser or whatever other tool warn you. And if that's to be python's policy, when it's possible to do better, I'm disappointed. (But won't respond further, my point is made.) James ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
¿Could you provide the connection credential?. I rather prefer to skip the IRC (I am a XMPP guy), but I can connect to freenode if you need it. I've already sent you a private e-mail. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 17/11/10 18:10, Antoine Pitrou wrote: ¿Could you provide the connection credential?. I rather prefer to skip the IRC (I am a XMPP guy), but I can connect to freenode if you need it. I've already sent you a private e-mail. OK. Sorry. My mail greylist is probably involved. Lets wait for another hour... Thanks for your time, Antoine. - -- Jesus Cea Avion _/_/ _/_/_/_/_/_/ j...@jcea.es - http://www.jcea.es/ _/_/_/_/ _/_/_/_/ _/_/ jabber / xmpp:j...@jabber.org _/_/_/_/ _/_/_/_/_/ . _/_/ _/_/_/_/ _/_/ _/_/ Things are not so easy _/_/ _/_/_/_/ _/_/_/_/ _/_/ My name is Dump, Core Dump _/_/_/_/_/_/ _/_/ _/_/ El amor es poner tu felicidad en la felicidad de otro - Leibniz -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQCVAwUBTOQNNJlgi5GaxT1NAQJVLAP9ElT0GGLWBZsGBMAHbzZCn1b0SC18Ki8o jp5eQgxDGRFo8ZPWVz3Q+/TGoIIs8UHLKjpYskfEae9Vm789lMlY/OZFerTn1Eus D9ldaVMKwpsLgSIgQr3AdAm3d5fXKvT6SXhGVwCOnuVi/iDiIGJl54UXoSqtLqo8 7PVP3LDaK8c= =8poZ -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Help deploying a new buildbot running OpenIndiana/x86
Jesus Cea j...@jcea.es wrote: On 17/11/10 17:23, Antoine Pitrou wrote: There is no incoming connection; however, a bunch of outgoing connections are made to various hosts by various tests, so it's better if there's no overzealous firewall in-between. For those of us who can't do that, there's a list of what machines the testing framework needs to be able to reach at http://wiki.python.org/moin/BuildBot. If you modify the tests, please keep that list up-to-date. Bill ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan ncogh...@gmail.com wrote: .. The library documentation is *not* the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call. +1 People who bother to read the Library Reference most likely already know that it is the authoritative source. People who read the sources or use deep introspection most likely know that they are walking on thin ice. The only grey area is help() and dir(). Unfortunately may novice guides recommend using these tools for learning as follows: L = [] dir(L) ['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort'] help(L.append) Help on built-in function append: ... See http://docs.python.org/faq/general.html#is-python-a-good-language-for-beginning-programmers Given the quirkiness of dir(), this is probably not the best practice. For the standard library however, help('module') or $ pydoc module already refer users to the official manual. Unfortunately this feature is slightly broken in 3.x (the link takes you to 2.x documentation instead of 3.x). I have opened a bug report about this, http://bugs.python.org/issue10446, and would like to add a sentence or two to the MODULE DOC section explaining the differences between the auto-generated docs and the official manual. We may also revisit the rules used by help() to decide what to include on the auto-generated module implementation. Note that currently help() output excludes names not in __all__ is the module has __all__ defined. While I advocated this rule earlier in this thread, I now realize that it may not be quite practical. Consider the recent addition of open() to the tokenize module. It was documented in the manual, but (wisely) excluded from tokenize.__all__. It appears that this discussion is converging to the conclusion that public API = documented in the reST manual. An unfortunate consequence is that it is not easy to discover public API programmatically. However, not easy does not mean impossible. ReST documentation is highly structured and Sphinx already generates various indices that can be easily queried. Maybe some of these indices should be distilled into something compact and made available to pydoc by the build process. This would allow help(anyobject) display a deep link to the official documentation or a warning that anyobject is undocumented. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On 11/17/2010 10:52 AM, Guido van Rossum wrote: That's not what I meant. In the case of style guides I think it is totally appropriate to update the PEP as new rules are developed or existing ones are clarified (or even changed). Revising style guides is standard practice. The Chicago Manual of Style, which is practically the 'Bible' of American publishing, is now in its 16th edition after 104 years. http://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206/ref=sr_1_2?s=booksie=UTF8qid=1290022712sr=1-2 Idea: include the 'current' version of PEP8 in the doc set for each Python version as the frozen Python Stdlib Style Guide for that version. Then people could specifically refer to the 3.2 version of the style guide. PEP8 would then be the trunk version subject to further revision. Include with the frozen version the repository id info needed to do a diff between it and future revisions so people can discover what has changed since whenever. -- Terry Jan Reedy ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
We may also revisit the rules used by help() to decide what to include on the auto-generated module implementation. Note that currently help() output excludes names not in __all__ is the module has __all__ defined. While I advocated this rule earlier in this thread, I now Consider the recent addition of open() to the tokenize module. It was documented in the manual, but (wisely) excluded from tokenize.__all__. I’m not sure this was on purpose. Victor? ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Thu, Nov 18, 2010 at 7:08 AM, Éric Araujo mer...@netwok.org wrote: We may also revisit the rules used by help() to decide what to include on the auto-generated module implementation. Note that currently help() output excludes names not in __all__ is the module has __all__ defined. While I advocated this rule earlier in this thread, I now Consider the recent addition of open() to the tokenize module. It was documented in the manual, but (wisely) excluded from tokenize.__all__. I’m not sure this was on purpose. Victor? Excluding a builtin name from __all__ sounds like a perfectly sensible idea, so even if it wasn't deliberate, I'd say it qualifies as fortuitous :) Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] new LRU cache API in Py3.2
I see now that my previous reply went only to Stefan, so I'm re-submitting, this time to the list. -Original Message- From: Stefan Behnel Sent: Saturday, 04 September, 2010 04:29 What about adding an intermediate namespace called cache, so that the new operations are available like this: print get_phone_number.cache.hits get_phone_number.cache.clear() I agree. While the function-based implementation is highly efficient, the pure use of functions has the counter-Pythonic effect of obfuscating the internal state (the same way the 'private' keyword does in Java). A class-based implementation would be capable of having its state introspected and could easily be extended. While the functional implementation is a powerful construct, it fails to generalize well. IMHO, a stdlib implementation should err on the side of transparency and extensibility over performance. That said, I've adapted Hettinger's Python 2.5 implementation to a class-based implementation. I've tried to keep the performance optimizations in place, but instead of instrumenting the wrapped method with lots of cache_* functions, I simply attach the cache object itself, which then provides the interface suggested by Stefan. This technique allows access to the cache object and all of its internal state, so it's also possible to do things like: get_phone_number.cache.maxsize += 100 or if get_phone_number.cache.store: do_something_interesting() These techniques are nearly impossible in the functional implementation, as the state is buried in the locals() of the nested functions. I'm most grateful to Raymond for contributing this to Python; On many occasions, I've used the ActiveState recipes for simple caches, but in almost every case, I've had to adapt the implementation to provide more transparency. I'd prefer to not have to do the same with the stdlib. Regards, Jason R. Coombs # modified from http://code.activestate.com/recipes/498245-lru-and-lfu-cache-decorators/ import collections import functools from itertools import ifilterfalse from heapq import nsmallest from operator import itemgetter class Counter(dict): 'Mapping where default values are zero' def __missing__(self, key): return 0 class LRUCache(object): ''' Least-recently-used cache decorator. Arguments to the cached function must be hashable. Cache performance statistics stored in .hits and .misses. Clear the cache with .clear(). Cache object can be accessed as f.cache, where f is the decorated function. http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used ''' def __init__(self, maxsize=100): self.maxsize = maxsize self.maxqueue = maxsize*10 self.store = dict() # mapping of args to results self.queue = collections.deque()# order that keys have been used self.refcount = Counter() # times each key is in the queue self.hits = self.misses = 0 def decorate(self, user_function, len=len, iter=iter, tuple=tuple, sorted=sorted, KeyError=KeyError): sentinel = object() # marker for looping around the queue kwd_mark = object() # separate positional and keyword # lookup optimizations (ugly but fast) store = self.store queue = self.queue refcount = self.refcount queue_append, queue_popleft = queue.append, queue.popleft queue_appendleft, queue_pop = queue.appendleft, queue.pop @functools.wraps(user_function) def wrapper(*args, **kwds): # cache key records both positional and keyword args key = args if kwds: key += (kwd_mark,) + tuple(sorted(kwds.items())) # record recent use of this key queue_append(key) refcount[key] += 1 # get cache entry or compute if not found try: result = store[key] self.hits += 1 except KeyError: result = user_function(*args, **kwds) store[key] = result self.misses += 1 # purge least recently used cache entry if len(store) self.maxsize: key = queue_popleft() refcount[key] -= 1 while refcount[key]:
Re: [Python-Dev] Breaking undocumented API
Excluding a builtin name from __all__ sounds like a perfectly sensible idea, so even if it wasn't deliberate, I'd say it qualifies as fortuitous :) But then, a tool that looks into __all__ to find for example what objects to document will miss open. I’d put open in __all__. Regards ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Am 17.11.2010 22:16, schrieb Éric Araujo: Excluding a builtin name from __all__ sounds like a perfectly sensible idea, so even if it wasn't deliberate, I'd say it qualifies as fortuitous :) But then, a tool that looks into __all__ to find for example what objects to document will miss open. I’d put open in __all__. So it comes down again to what we'd like __all__ to mean foremost: public API, or just a list for import *? Georg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 4:22 PM, Georg Brandl g.bra...@gmx.net wrote: So it comes down again to what we'd like __all__ to mean foremost: public API, or just a list for import *? It is and has been since its inception *the* list for import *. Any additional meaning will have to accommodate that usage as well. -Fred -- Fred L. Drake, Jr. fdrake at acm.org A storm broke loose in my mind. --Albert Einstein ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PEP 3151 dictator
Hello, I would like to announce that, following Guido's (private) suggestion that I find a temporary dictator for PEP 3151, Barry has accepted to fill in this role. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Am 17.11.2010 22:39, schrieb Fred Drake: On Wed, Nov 17, 2010 at 4:22 PM, Georg Brandl g.bra...@gmx.net wrote: So it comes down again to what we'd like __all__ to mean foremost: public API, or just a list for import *? It is and has been since its inception *the* list for import *. Any additional meaning will have to accommodate that usage as well. Seeing that import * is discouraged anywhere I look, it might just not be as important anymore. BTW, open is listed in __all__ for lots of modules: io, gzip, dbm... and even ancient ones like aifc. cheers, Georg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Nick Coghlan wrote: The policy we're aiming to clarify here is what we should do when we come across standard library APIs that land in the grey area, with there being two appropriate ways to deal with them: 1. Document them and make them officially public 2. Deprecate the public names and make them officially private (with the public names later removed in accordance with normal deprecation procedures) You missed at least two other options: 3. Treat documented and public as orthogonal, not synonymous: undocumented public API is not an oxymoron, and neither is documented private API. 4. Do nothing. Inertia wins. Is this problem we're trying to solve so serious that we need to solve it now except on a case-by-case basis? The approach that gives us the most flexibility is #3. Clearly one would not need to document private APIs for the use of the general public, but adding docstrings to private functions and classes for in-house use is a sensible thing to do. This applies equally to the standard library as to any other major project. Likewise, one might introduce a public function into some module, but for whatever reason, choose not to document it. (Perhaps it's a lack of hours in the day, perhaps it is a deliberate decision.) In this case, the mere lack of documentation shouldn't relieve us of the responsibility of treating the function as public. For emphasis: I strongly believe that public/private and documented/undocumented are orthogonal qualities, and should not be treated as, or forced to be, identical. The use of imported modules is possibly an exception. If a user is writing something like (say) getopt.os.getcwd() instead of importing os directly, then they're on shaky ground. We shouldn't expect module authors to write import os as _os just to avoid making os a part of their public API. I'd be prepared to make an exception to the rule no leading underscore means public: imported modules are implementation details unless explicitly documented otherwise. E.g. the os module explicitly makes path part of its public API, but os.sys is an implementation detail. -- Steven ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
Steven D'Aprano st...@pearwood.info writes: 3. Treat documented and public as orthogonal, not synonymous: undocumented public API is not an oxymoron, and neither is documented private API. +1 The use of imported modules is possibly an exception. If a user is writing something like (say) getopt.os.getcwd() instead of importing os directly, then they're on shaky ground. We shouldn't expect module authors to write import os as _os just to avoid making os a part of their public API. I'd be prepared to make an exception to the rule no leading underscore means public: imported modules are implementation details unless explicitly documented otherwise. E.g. the os module explicitly makes path part of its public API, but os.sys is an implementation detail. After reading the discussion for many days, I'm leaning to this position also. -- \ “I may disagree with what you say, but I will defend to the | `\death your right to mis-attribute this quote to Voltaire.” | _o__) —Avram Grumer, rec.arts.sf.written, 2000-05-30 | Ben Finney ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Breaking undocumented API
On Wed, Nov 17, 2010 at 5:08 PM, Ben Finney ben+pyt...@benfinney.id.au wrote: Steven D'Aprano st...@pearwood.info writes: 3. Treat documented and public as orthogonal, not synonymous: undocumented public API is not an oxymoron, and neither is documented private API. +1 The use of imported modules is possibly an exception. If a user is writing something like (say) getopt.os.getcwd() instead of importing os directly, then they're on shaky ground. We shouldn't expect module authors to write import os as _os just to avoid making os a part of their public API. I'd be prepared to make an exception to the rule no leading underscore means public: imported modules are implementation details unless explicitly documented otherwise. E.g. the os module explicitly makes path part of its public API, but os.sys is an implementation detail. After reading the discussion for many days, I'm leaning to this position also. Agreed on both counts. -- --Guido van Rossum (python.org/~guido) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com