Re: [Python-Dev] Convention on functions that shadow existing stdlib functions
Am 29.07.2011 11:26, schrieb Barry Warsaw: So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). Also don't forget that this is open-source: we shouldn't do questionable decisions (-1 from me on moving test.support docs to the devguide) just because the tool is lacking. I can probably hack up a small addition to Doc/tools/sphinxext in five minutes that ignores the whole of test.* when building the index. 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] Convention on functions that shadow existing stdlib functions
Am 27.07.2011 19:44, schrieb Terry Reedy: On 7/27/2011 9:24 AM, Antoine Pitrou wrote: Docstrings are sufficient for own our purposes. import test.support as t help(t.rmtree) Help on function rmtree in module test.support: rmtree(path) Well, what are you waiting for... just add the docstring! 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] Convention on functions that shadow existing stdlib functions
Am 27.07.2011 19:47, schrieb Terry Reedy: On 7/27/2011 1:27 PM, Brett Cannon wrote: Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, We already do. 25.6. test.support — Utility functions for tests FWIW, this heading could give wrong impressions. I just changed it to :mod:`test.support` --- Utilities for the Python test suite and also added another note under it that the API is subject to change at any time. is about half of the page that also contains 25.5. test — Regression tests package for Python The latter contains 25.5.1. Writing Unit Tests for the test package which should also be moved to the dev guide if 25.6 is. 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 6:54 PM, Antoine Pitrou wrote: On Fri, 29 Jul 2011 18:47:07 -0400 Terry Reedytjre...@udel.edu wrote: And test.support *is* for internal use. No, the stuff in there is *not* for internal use within the module but for external use is possiby every test module. I meant internal use for us. Really, whether or not it's used cross-module is irrelevant. It is not at all irrelevant to me as a newer developer. I see uses of test.support.x quite often in checkins and I apparently should know about the contents of test.support for writing tests so I can use things as appropriate. Ditto for everyone else. On the other hand, the private support functions in trace.py are irrelevant to everyone except for the occasional person doing occasion maintenance work on that module. 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 7:27 PM, Antoine Pitrou wrote: On Fri, 29 Jul 2011 19:02:32 -0400 Terry Reedytjre...@udel.edu wrote: On 7/29/2011 5:32 PM, Antoine Pitrou wrote: On Fri, 29 Jul 2011 11:51:18 -0400 Barry Warsawba...@python.org wrote: The solution then is to rename test.support to test._support to make it clear it's an internal implementation detail. Then you can remove the entire section from the stdlib docs and just document it in the code. Ideally so. The effect of this will be to discourage new people (including myself in the category) from writing or reviewing patches. I'm sorry, can you be more precise. The effect of what? Your proposal to remove the current formatted documentation of test.support instead of completing it and force all developers to only have reference to the docstrings scattered through the code. And why would that be so? Because not everyone is like you. Because the condensed formatted docs make learning and using a module significantly easier for some people. 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] Convention on functions that shadow existing stdlib functions
On Sat, 30 Jul 2011 09:25:27 -0400 Terry Reedy tjre...@udel.edu wrote: I'm sorry, can you be more precise. The effect of what? Your proposal to remove the current formatted documentation of test.support instead of completing it and force all developers to only have reference to the docstrings scattered through the code. And why would that be so? Because not everyone is like you. Because the condensed formatted docs make learning and using a module significantly easier for some people. Ok, I understand. I just hope the notice at the top of the module doc is prominent enough that nobody will think there's any API guarantee there. 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] Convention on functions that shadow existing stdlib functions
On Sat, Jul 30, 2011 at 1:49 AM, Barry Warsaw ba...@python.org wrote: On Jul 30, 2011, at 01:02 AM, Nick Coghlan wrote: If test.support is truly and only an internal implementation detail, then it should adhere to Pythonic convention for such things, and be renamed test._support. Then you won't need to document it at all except in the module. Aside from test.regrtest and test.support, the entirety of the rest of the test package is completely undocumented. test.support is unique, as it is the only component other than the main executable that is documented *at all*, solely for the benefits of people writing new tests. We don't even document the resources that can be enabled from the command line, instead telling people to look at the command line help output. The entire test package is an implementation detail, underscore or no underscore - we will never, ever, offer any kind of backwards compatibility guarantee for code in that part of the package hierarchy. Here's another problem with moving the documentation for test.support to the devguide. They will invariably get out of sync. It's hard enough to keep stdlib code and stdlib docs in sync, but I think it will be even harder to keep stdlib code in sync with devguide documentation. It will also be harder to know what version of the devguide corresponds to what version of the code repository. By that reasoning, we should just give up and delete the test.support docs entirely (since they're *already* treated with disrespect by contrast to the real stdlib docs). It sounds to me like you're really objecting to the devguide living in a separate clone. This doesn't bode well for the prospects of ever splitting the stdlib out from the CPython interpreter core... 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] Convention on functions that shadow existing stdlib functions
On Jul 31, 2011, at 01:23 AM, Nick Coghlan wrote: It sounds to me like you're really objecting to the devguide living in a separate clone. This doesn't bode well for the prospects of ever splitting the stdlib out from the CPython interpreter core... Actually, no. I'm objecting to moving documentation for code to a different repo than the code. If/when the stdlib is split out (which I support), then the documentation should go with it. Cheers, -Barry signature.asc Description: 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] Convention on functions that shadow existing stdlib functions
On Sun, Jul 31, 2011 at 1:38 AM, Barry Warsaw ba...@python.org wrote: On Jul 31, 2011, at 01:23 AM, Nick Coghlan wrote: It sounds to me like you're really objecting to the devguide living in a separate clone. This doesn't bode well for the prospects of ever splitting the stdlib out from the CPython interpreter core... Actually, no. I'm objecting to moving documentation for code to a different repo than the code. If/when the stdlib is split out (which I support), then the documentation should go with it. That's a rather valid point that I can definitely agree with. OK, you've convinced me that the right thing to do is leave the test.support docs where they are and just apply the appropriate markup to keep them out of the various indices. 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 08:48, Nick Coghlan ncogh...@gmail.com wrote: On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky eli...@gmail.com wrote: I propose to just move 3K's docs to the devguide, and make both doc pages (in 3K and 2.7) point to it. Is this acceptable? Yeah, just include a note in the devguide version saying that anything added in 3.2 or later may not be available when writing tests for the 2.7 maintenance branch. Alright, and what should stay in the docs then? I guess only 25.5.2 (usage of regrtest). The rest is either documentation of support, or advice for people writing new tests, both of which belong to the devguide. Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 4:52 PM, Eli Bendersky eli...@gmail.com wrote: On Fri, Jul 29, 2011 at 08:48, Nick Coghlan ncogh...@gmail.com wrote: On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky eli...@gmail.com wrote: I propose to just move 3K's docs to the devguide, and make both doc pages (in 3K and 2.7) point to it. Is this acceptable? Yeah, just include a note in the devguide version saying that anything added in 3.2 or later may not be available when writing tests for the 2.7 maintenance branch. Alright, and what should stay in the docs then? I guess only 25.5.2 (usage of regrtest). The rest is either documentation of support, or advice for people writing new tests, both of which belong to the devguide. How to run the test suite should stay, along with a pointer to the additional information in the devguide. 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] Convention on functions that shadow existing stdlib functions
On Jul 29, 2011, at 08:24 AM, Eli Bendersky wrote: Alright, I think there's now a sufficiently wide consensus to move the documentation of Lib/test and Lib/test/support in particular to the devguide, which raises a question: I haven't been following this thread, so I caught up on Gmane. I'm somewhat uncomfortable with this decision. I understand why you want to do this, but I still think it might not be the right thing. For better or worse, test.support is part of the standard library, so moving its documentation elsewhere sets a bad precedent to me. Many times I work on Python while completely off-line. If I've had the foresight to build the docs before I go off-line, all the better, but even if not, I have the .rst files to consult. Now I'll have to remember to *also* grab the devguide so that I have the complete documentation of the stdlib. I also think this underestimates how blurry the line is between users and developers. Think about yourself: when did you suddenly graduate from user of Python to developer of Python? I know that I often talk to people who would consider themselves just users of Python, but feel comfortable with their occasional spelunking into the Python tree looking for whatever nugget of code or documentation will help them understand their problem. The devguide, as useful and cool as it is, is still immature and hard to discover. I think more time will improve its organization, and it's not even linked to from docs.python.org. So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). Cheers, -Barry signature.asc Description: 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] Convention on functions that shadow existing stdlib functions
Alright, I think there's now a sufficiently wide consensus to move the documentation of Lib/test and Lib/test/support in particular to the devguide, which raises a question: I haven't been following this thread, so I caught up on Gmane. I'm somewhat uncomfortable with this decision. I understand why you want to do this, but I still think it might not be the right thing. For better or worse, test.support is part of the standard library, so moving Why is it part of stdlib though? Isn't the stdlib something that's exposed to all Python programmers? How should an ordinary programmer (not a core dev) know some parts of stdlib are out of limits, if they are even documented and appear in the index - should he read the note at the top of the documentation page? Imagine a desperate programmer behind schedule who is looking for some particular functionality in stdlib and finds it in test.support - will he not use it and later complain we don't keep backwards-compatibility. Sure, he's at fault, but I think we can make such cases much rarer by making the distinction between user-exposed modules and core-dev-exposed modules more explicit. its documentation elsewhere sets a bad precedent to me. Many times I work on Python while completely off-line. If I've had the foresight to build the docs before I go off-line, all the better, but even if not, I have the .rst files to consult. Now I'll have to remember to *also* grab the devguide so that I have the complete documentation of the stdlib. I think this is because you're experienced and probably know all the contents of the devguide anyway. Junior core-devs need the devguide handy for other reasons as well. I also think this underestimates how blurry the line is between users and developers. Think about yourself: when did you suddenly graduate from user of Python to developer of Python? I know that I often talk to people who would consider themselves just users of Python, but feel comfortable with their occasional spelunking into the Python tree looking for whatever nugget of code or documentation will help them understand their problem. Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working *on Python*. The devguide, as useful and cool as it is, is still immature and hard to discover. I think more time will improve its organization, and it's not even linked to from docs.python.org. Maybe this is the main point here - what makes it immature? What makes it hard to discover? Maybe these issues can be fixed. So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). I think the unlinkrmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself. Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 7:26 PM, Barry Warsaw ba...@python.org wrote: The devguide, as useful and cool as it is, is still immature and hard to discover. I think more time will improve its organization, and it's not even linked to from docs.python.org. So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). It's worthwhile because it is what the devguide is for: documenting how to *change* Python, rather than just using it as it is delivered to you. There's a clear transition from user of Python to developer of Python: you stop treating the standard library (and perhaps even the interpreter core) as sacrosanct, and will actually change the code in those files if its wrong (and is affecting your own application). Agreed that docs.python.org front page should have a link to docs.python.org/devguide, though. 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] Convention on functions that shadow existing stdlib functions
On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote: Why is it part of stdlib though? Isn't the stdlib something that's exposed to all Python programmers? How should an ordinary programmer (not a core dev) know some parts of stdlib are out of limits, if they are even documented and appear in the index - should he read the note at the top of the documentation page? Imagine a desperate programmer behind schedule who is looking for some particular functionality in stdlib and finds it in test.support - will he not use it and later complain we don't keep backwards-compatibility. Sure, he's at fault, but I think we can make such cases much rarer by making the distinction between user-exposed modules and core-dev-exposed modules more explicit. How common are those mistakes right now? I get way more complaints about squishy APIs in third party libraries and actual *supported* parts of the stdlib than I do about test.support APIs. What's the real problem we're trying to solve anyway? Is it protect the harried user from some future breakage or eliminate complaints we Python developers get from harried users? I'd much rather solve this problem by adding markup to functions that explicitly disclaim our normal backward compatibility guarantees. Squirreling away documentation for some parts of the stdlib seems similar to security-by-obscurity arguments. test.support *is* part of the stdlib. If you want to propose moving it out of the stdlib, that's a different argument to make. Maybe Python's entire test suite should be in some Cheeseshop package instead of in the core source tree. (I wouldn't agree with that either, but I'm just saying.) So once again, is this a real actual problem you've witnessed in enough cases to go through all the trouble of moving the documentation, and making it more difficult to find? its documentation elsewhere sets a bad precedent to me. Many times I work on Python while completely off-line. If I've had the foresight to build the docs before I go off-line, all the better, but even if not, I have the .rst files to consult. Now I'll have to remember to *also* grab the devguide so that I have the complete documentation of the stdlib. I think this is because you're experienced and probably know all the contents of the devguide anyway. Junior core-devs need the devguide handy for other reasons as well. I'm not saying the devguide isn't handy - in fact it's incredibly handy! I love that it explains the nuances of how we structure our Mercurial branches, and define our workflow for example. I readily admit those are not things I know by heart. (But actually, those instructions are not always easy to find, which is why I think the organization is immature. I'm not faulting the devguide authors, I just think it needs more time to bake.) I also think this underestimates how blurry the line is between users and developers. Think about yourself: when did you suddenly graduate from user of Python to developer of Python? I know that I often talk to people who would consider themselves just users of Python, but feel comfortable with their occasional spelunking into the Python tree looking for whatever nugget of code or documentation will help them understand their problem. Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working *on Python*. Again, I think that line is blurred here. Let's say you're working on some off-beat or new hardware and you want to know if your basic tool chain works for it. You build Python, run the test suite, and something fails. You probably don't consider yourself a Python developer, but now you're digging through the test.support to figure out your problem. Yes, I've seen this happen. The devguide, as useful and cool as it is, is still immature and hard to discover. I think more time will improve its organization, and it's not even linked to from docs.python.org. Maybe this is the main point here - what makes it immature? What makes it hard to discover? Maybe these issues can be fixed. Sure, there are issues that can be fixed, but they're unrelated to documenting test.support. So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). I think the unlinkrmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself. Let's see! I think the devguide should
Re: [Python-Dev] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 11:18:37 -0400 Barry Warsaw ba...@python.org wrote: I'd much rather solve this problem by adding markup to functions that explicitly disclaim our normal backward compatibility guarantees. Squirreling away documentation for some parts of the stdlib seems similar to security-by-obscurity arguments. Well, here the whole module should not be called by the user. I'm not sure we want to flag each function individually. test.support *is* part of the stdlib. We have lots of internal APIs which are not documented, though. And test.support *is* for internal use. 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] Convention on functions that shadow existing stdlib functions
Barry Warsaw wrote: On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote: I think the unlinkrmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself. Let's see! I think the devguide should document things like how to submit bugs, how to use Mercurial, how to propose changes to Python, how to ensure code works across all existing interpreter implementations, where to find continuous integration results and how to interpret them, what's the right forum to discuss Python, etc. I.e. processes, workflows, and conventions that are important cultural artifacts we've built up over 20 years. I don't think the devguide should document the actual code we ship. +1 ~Ethan~ ___ 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] Convention on functions that shadow existing stdlib functions
On Sat, Jul 30, 2011 at 1:18 AM, Barry Warsaw ba...@python.org wrote: On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote: I think the unlinkrmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself. Let's see! I think the devguide should document things like how to submit bugs, how to use Mercurial, how to propose changes to Python, how to ensure code works across all existing interpreter implementations, where to find continuous integration results and how to interpret them, what's the right forum to discuss Python, etc. I.e. processes, workflows, and conventions that are important cultural artifacts we've built up over 20 years. I don't think the devguide should document the actual code we ship. I think everything related to *changing* Python should be in the devguide, not the standard library docs. So the documentation on how to *run* the test suite belongs in the devguide, but the details of how the test suite works internally, including the APIs that are used to write new tests, belong in the dev guide. Now, perhaps a copy of the dev guide should be bundled with all future releases rather than relying on the availability of a net connection to access wart, but finally getting rid of the dodgy test.support sort-of-docs out of the standard library docs is an excellent change. As far as improving the arrangement goes, the checkin privileges are the same as those for the main source tree - patches welcome :) 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] Convention on functions that shadow existing stdlib functions
On Sat, Jul 30, 2011 at 1:32 AM, Nick Coghlan ncogh...@gmail.com wrote: So the documentation on how to *run* the test suite belongs in the devguide, but the details of how the test suite works internally, including the APIs that are used to write new tests, belong in the dev guide. Gah, that first instance of 'the devguide' should read 'the standard library docs'. 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 8:18 AM, Barry Warsaw wrote: I think the devguide should document things like ... how to ensure code works across all existing interpreter implementations, where to find continuous integration results and how to interpret them ... I don't think the devguide should document the actual code we ship. Seems to me that test.support documentation helps explain the above items. ___ 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] Convention on functions that shadow existing stdlib functions
On Jul 30, 2011, at 01:02 AM, Nick Coghlan wrote: It's worthwhile because it is what the devguide is for: documenting how to *change* Python, rather than just using it as it is delivered to you. There's a clear transition from user of Python to developer of Python: you stop treating the standard library (and perhaps even the interpreter core) as sacrosanct, and will actually change the code in those files if its wrong (and is affecting your own application). I'm not so sure the line's that bright. But anyway... Using the criteria in your first sentence, test.support is clearly what's delivered to you not changing Python. IOW, we ship test.support in the tarball, so *if* it's to be documented, then the stdlib is the right place to document it, IMO. If test.support is truly and only an internal implementation detail, then it should adhere to Pythonic convention for such things, and be renamed test._support. Then you won't need to document it at all except in the module. Here's another problem with moving the documentation for test.support to the devguide. They will invariably get out of sync. It's hard enough to keep stdlib code and stdlib docs in sync, but I think it will be even harder to keep stdlib code in sync with devguide documentation. It will also be harder to know what version of the devguide corresponds to what version of the code repository. -Barry signature.asc Description: 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] Convention on functions that shadow existing stdlib functions
On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote: test.support *is* part of the stdlib. We have lots of internal APIs which are not documented, though. And test.support *is* for internal use. The solution then is to rename test.support to test._support to make it clear it's an internal implementation detail. Then you can remove the entire section from the stdlib docs and just document it in the code. -Barry signature.asc Description: 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] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 11:18:37 -0400, Barry Warsaw ba...@python.org wrote: On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote: Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working *on Python*. Again, I think that line is blurred here. Let's say you're working on some off-beat or new hardware and you want to know if your basic tool chain works for it. You build Python, run the test suite, and something fails. You probably don't consider yourself a Python developer, but now you're digging through the test.support to figure out your problem. Yes, I've seen this happen. In that case, you are working *on Python*. Not using Python. Personally, I'd expect such information to be in a devguide, although really I'd not expect it to be documented at all, for most projects. Making the devguide a more prominent part of the documentation would be good: it would invite more people to cross that line and help us improve Python. As someone else pointed out, there is lots of stuff in the stdlib that is not public API, and therefore not documented. The problem with test.support is that it is not a public API, but *is* documented. So logically either we should remove the documentation, or we should not only do as you suggested by marking each function as not-a-stable-API, but also document as many of the other internal APIs as we care to in the same way. That would doubtless help our users, but more care than just marking functions as unstable would be required, I think. Personally, I always thought the devguide should be part of Docs anyway. It isn't because people didn't want it versioned along side Python, but I still don't see why that would be a problem. -- R. David Murray http://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] Convention on functions that shadow existing stdlib functions
On Jul 29, 2011, at 12:13 PM, R. David Murray wrote: In that case, you are working *on Python*. Not using Python. My point was, it's a fine line between the two. Personally, I always thought the devguide should be part of Docs anyway. It isn't because people didn't want it versioned along side Python, but I still don't see why that would be a problem. +1 -Barry signature.asc Description: 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] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 11:49:01 -0400, Barry Warsaw ba...@python.org wrote: If test.support is truly and only an internal implementation detail, then it should adhere to Pythonic convention for such things, and be renamed test._support. Then you won't need to document it at all except in the module. I'd be fine with renaming it and not documenting it, myself. Other developers prefer to have as much as practical documented in html form. Here's another problem with moving the documentation for test.support to the devguide. They will invariably get out of sync. It's hard enough to keep stdlib code and stdlib docs in sync, but I think it will be even harder to keep stdlib code in sync with devguide documentation. It will also be harder to know what version of the devguide corresponds to what version of the code repository. Which wouldn't be any more of a problem than the regular python docs if the devguide were in the normal doc tree. Just saying :) -- R. David Murray http://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] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 11:51:18 -0400 Barry Warsaw ba...@python.org wrote: On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote: test.support *is* part of the stdlib. We have lots of internal APIs which are not documented, though. And test.support *is* for internal use. The solution then is to rename test.support to test._support to make it clear it's an internal implementation detail. Then you can remove the entire section from the stdlib docs and just document it in the code. Ideally so. Practically, it's a lot of churn and additional pain merging 3.2 bugfixes into default. The lack of an underscore doesn't always mean the API is public, because it hasn't always worked like this (we have many private APIs without an underscore). 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 11:18 AM, Barry Warsaw wrote: I'd much rather solve this problem by adding markup to functions that explicitly disclaim our normal backward compatibility guarantees. I suggested adding a footnote marker (1) to each one. test.support *is* part of the stdlib. So once again, is this a real actual problem you've witnessed in enough cases to go through all the trouble of moving the documentation, and making it more difficult to find? I agree with this. When working on tests, I would prefer to have test.support doc in the same offine doc set as unittest docs. I only supported *moving* as an alternative to *deleting*. Terry J. 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 11:25 AM, Antoine Pitrou wrote: t We have lots of internal APIs which are not documented, though. They are generally used only within the module itself as helper functions. So one only needs to even know about them when looking at the module code. And test.support *is* for internal use. No, the stuff in there is *not* for internal use within the module but for external use is possiby every test module. Terry J. 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] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 18:47:07 -0400 Terry Reedy tjre...@udel.edu wrote: And test.support *is* for internal use. No, the stuff in there is *not* for internal use within the module but for external use is possiby every test module. I meant internal use for us. Really, whether or not it's used cross-module is irrelevant. 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] Convention on functions that shadow existing stdlib functions
On 7/29/2011 5:32 PM, Antoine Pitrou wrote: On Fri, 29 Jul 2011 11:51:18 -0400 Barry Warsawba...@python.org wrote: On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote: test.support *is* part of the stdlib. We have lots of internal APIs which are not documented, though. And test.support *is* for internal use. The solution then is to rename test.support to test._support to make it clear it's an internal implementation detail. Then you can remove the entire section from the stdlib docs and just document it in the code. Ideally so. The effect of this will be to discourage new people (including myself in the category) from writing or reviewing patches. 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] Convention on functions that shadow existing stdlib functions
On Fri, 29 Jul 2011 19:02:32 -0400 Terry Reedy tjre...@udel.edu wrote: On 7/29/2011 5:32 PM, Antoine Pitrou wrote: On Fri, 29 Jul 2011 11:51:18 -0400 Barry Warsawba...@python.org wrote: On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote: test.support *is* part of the stdlib. We have lots of internal APIs which are not documented, though. And test.support *is* for internal use. The solution then is to rename test.support to test._support to make it clear it's an internal implementation detail. Then you can remove the entire section from the stdlib docs and just document it in the code. Ideally so. The effect of this will be to discourage new people (including myself in the category) from writing or reviewing patches. I'm sorry, can you be more precise. The effect of what? And why would that be so? ___ 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] Convention on functions that shadow existing stdlib functions
On Wed, Jul 27, 2011 at 16:53, Steven D'Aprano st...@pearwood.info wrote: Eli Bendersky wrote: Sure, but I'm still leery of two functions with the same name doing acting slightly differently. and then in a later post: As I mentioned elsewhere, it's not good practice to have two functions with the same name doing something slightly different, in different modules in the code-base. artist.draw() and gunslinger.draw() do not necessarily need to do the same thing, and I don't agree that a (futile) preference for globally unique names is good practice: it can lead to unnecessarily long names (artist.draw_with_pencil_on_**paper) or redundant characters prefixing the name (itertools.imap -- what does the i in imap tell you that the itertools didn't already?). Solving this problem is what namespaces are for. Renaming test.support.ulink to something else doesn't fix the problem of unsupported support functions being used in third-party code. It may even *encourage* it, by making the extra functionality more explicit. However, is there any reason why test.support itself shouldn't be renamed test._support, or possibly _test.support, so that the *entire* suite is marked as a private implementation detail? Technically no for the _test idea, although it would promote the idea of not shipping Python with its tests, which would be a shame as it's hard enough to get people to run them. Renaming test.support is much more acceptable, just more work considering how many times that module is used in the test suite. ___ 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 7:33 AM, Brett Cannon br...@python.org wrote: However, is there any reason why test.support itself shouldn't be renamed test._support, or possibly _test.support, so that the *entire* suite is marked as a private implementation detail? Technically no for the _test idea, although it would promote the idea of not shipping Python with its tests, which would be a shame as it's hard enough to get people to run them. Renaming test.support is much more acceptable, just more work considering how many times that module is used in the test suite. Moving the docs should deal with the module and name indexing issue, so -1 one to expending any developer effort on unnecessary name changes in the test suite. 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 03:39, Nick Coghlan ncogh...@gmail.com wrote: On Fri, Jul 29, 2011 at 7:33 AM, Brett Cannon br...@python.org wrote: However, is there any reason why test.support itself shouldn't be renamed test._support, or possibly _test.support, so that the *entire* suite is marked as a private implementation detail? Technically no for the _test idea, although it would promote the idea of not shipping Python with its tests, which would be a shame as it's hard enough to get people to run them. Renaming test.support is much more acceptable, just more work considering how many times that module is used in the test suite. Moving the docs should deal with the module and name indexing issue, so -1 one to expending any developer effort on unnecessary name changes in the test suite. Alright, I think there's now a sufficiently wide consensus to move the documentation of Lib/test and Lib/test/support in particular to the devguide, which raises a question: Currently test.support is documented both for Python 3K and 2.7, while the devguide (AFAIK) comes in a single version. I propose to just move 3K's docs to the devguide, and make both doc pages (in 3K and 2.7) point to it. Is this acceptable? Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky eli...@gmail.com wrote: I propose to just move 3K's docs to the devguide, and make both doc pages (in 3K and 2.7) point to it. Is this acceptable? Yeah, just include a note in the devguide version saying that anything added in 3.2 or later may not be available when writing tests for the 2.7 maintenance branch. 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] Convention on functions that shadow existing stdlib functions
The mere fact that these functions exist in a different module suggests different semantics from those found in other places in the stdlib. I don't think they should be renamed simply because some code imports the functions directly instead of the module itself (suggesting they should be doing the latter over the former). Now if the functions are redundant that's something else entirely and removal should be fine. I will try to clarify my concern. Documented functions from test.support currently appear in the global index of the Sphinx-generated documentation. Suppose we document test.support's unlink. Now the index entry for unlink will contain two unlink references (*), with slightly different semantics - one in os and another in test.support Will it take long for newbie code to appear with the test.support version? Not to mention that grepping code that imports the unlink function directly doesn't reveal which one is being used. I think this is troublesome. I think at least two separate actions are required here: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. Eli (*) Actually, three, since there's also xml.dom.minidom.Node, but that's obviously unrelated). ___ 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] Convention on functions that shadow existing stdlib functions
On Wed, 27 Jul 2011 16:14:40 +0300 Eli Bendersky eli...@gmail.com wrote: Will it take long for newbie code to appear with the test.support version? Not to mention that grepping code that imports the unlink function directly doesn't reveal which one is being used. I think this is troublesome. I think at least two separate actions are required here: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. There is a top-level note at http://docs.python.org/dev/library/test.html, but it won't be visible by people who arrive at an anchor point. I think officially documenting test.support is a mistake. There is no guarantee that APIs are stable or will even continue to exist. Docstrings are sufficient for own our purposes. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. They are not redundant, since they provide slightly different semantics (for example, they silence errors that happen when the path doesn't exist). 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] Convention on functions that shadow existing stdlib functions
1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. There is a top-level note at http://docs.python.org/dev/library/test.html, but it won't be visible by people who arrive at an anchor point. I think officially documenting test.support is a mistake. There is no guarantee that APIs are stable or will even continue to exist. Docstrings are sufficient for own our purposes. Initially I was *for* documenting, but this thing with showing up in the index is a compelling counter-point. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. They are not redundant, since they provide slightly different semantics (for example, they silence errors that happen when the path doesn't exist). Sure, but I'm still leery of two functions with the same name doing acting slightly differently. Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Wed, 27 Jul 2011 16:14:40 +0300, Eli Bendersky eli...@gmail.com wrote: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. This was already done. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. But they aren't redundant, since the test.support versions ignore errors. Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. -- R. David Murray http://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] Convention on functions that shadow existing stdlib functions
2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. But they aren't redundant, since the test.support versions ignore errors. As I mentioned elsewhere, it's not good practice to have two functions with the same name doing something slightly different, in different modules in the code-base. Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. Moving the documentation to the devguide is a good compromise between not documenting them at all and placing the documentation in a user-visible location. What do you mean by vetting the test suite so that unlink is always taken from test.support? I suppose some tests would specifically want the original unlink's functionality. In fact, at least a few tests use os.unlink exlicitly. Eli ___ 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] Convention on functions that shadow existing stdlib functions
Hi, On 27/07/2011 16.35, Eli Bendersky wrote: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. There is a top-level note at http://docs.python.org/dev/library/test.html, but it won't be visible by people who arrive at an anchor point. I think officially documenting test.support is a mistake. There is no guarantee that APIs are stable or will even continue to exist. Docstrings are sufficient for own our purposes. Initially I was *for* documenting, but this thing with showing up in the index is a compelling counter-point. "The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:." (http://docs.python.org/documenting/markup.html#information-units) Best Regards, Ezio Melotti 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. They are not redundant, since they provide slightly different semantics (for example, they silence errors that happen when the path doesn't exist). Sure, but I'm still leery of two functions with the same name doing acting slightly differently. Eli ___ 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] Convention on functions that shadow existing stdlib functions
Initially I was *for* documenting, but this thing with showing up in the index is a compelling counter-point. The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:. ( http://docs.python.org/documenting/markup.html#information-units) Ezio, this is also a good idea, but currently I really think placing this documentation in the devguide is probably the best approach. Now we have a very nice Devguide, and this documentation simply belongs there, and not in the user-visible portion of the official Python documentation. Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Wed, 27 Jul 2011 16:58:53 +0300, Eli Bendersky eli...@gmail.com wrote:
R. David Murray wrote:
But they aren't redundant, since the test.support versions ignore
errors.
As I mentioned elsewhere, it's not good practice to have two functions with
the same name doing something slightly different, in different modules in
the code-base.
Well, that would seem to be a matter of opinion. I see your point, but
I'm not sure that I agree. But see below.
What do you mean by vetting the test suite so that unlink is always taken
from test.support? I suppose some tests would specifically want the original
unlink's functionality. In fact, at least a few tests use os.unlink
exlicitly.
What I mean is that if the test code always did:
import support
[...]
support.unlink('testtempfile')
then there would be no confusion when someone grepped the code for
'unlink' or was reading the code without having noticed the import.
That is, give the functions a unique name by using the 'support'
name space explicitly, rather than by renaming them within the
module.
--
R. David Murray http://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] Convention on functions that shadow existing stdlib functions
On 7/27/2011 9:24 AM, Antoine Pitrou wrote: On Wed, 27 Jul 2011 16:14:40 +0300 Eli Benderskyeli...@gmail.com wrote: Will it take long for newbie code to appear with the test.support version? Not to mention that grepping code that imports the unlink function directly doesn't reveal which one is being used. I think this is troublesome. I think at least two separate actions are required here: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. There is a top-level note at http://docs.python.org/dev/library/test.html, but it won't be visible by people who arrive at an anchor point. I think the 'Note' (gray box), not a 'Warning' (red box) should be repeated at the top of the test.support section. Or, or in addition, footnote each entry (with same number jumping to same footnote, if this can be done): test.support.verbose(1). Seeing every entry decorated with the same footnote number should indicate there there is something unusual, and that we really mean it. I think officially documenting test.support is a mistake. There is no guarantee that APIs are stable or will even continue to exist. Docstrings are sufficient for own our purposes. Maybe sufficient for you, but if I am to learn and use this stuff, I need a proper listing. Individual docstrings require that you know the object exists and its name. Any help(module) listing is harder for me to use than the doc chapter. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. They are not redundant, since they provide slightly different semantics (for example, they silence errors that happen when the path doesn't exist). rmtree has an ignore_errors=False parameter ignore_errors is true, errors resulting from failed removals will be ignored; . If that does not ignore enough errors, then perhaps it should be changed. os.unlink is an alias for os.remove. The doc for the latter says error if path is a directory or a file in use on Windows (but not *nix). Neither should be case in test uses. Doc does not specify errors if file not exist or other conditions (inadequate permission. Being thin wrappers, a quiet param is not allowed in os.remove/unlink, though I can imagine others wanting a quieted version for removal of files whose creation might have failed. In anycase, naming the quieted version in test.support unlink_quiet or q_remove or something would make its reason-for-being and use clearer. --- Side note: test.support.import_fresh_module typo. /is/if/ in This function will raise unittest.SkipTest is the named module cannot be imported. -- 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] Convention on functions that shadow existing stdlib functions
On 7/27/2011 10:27 AM, Eli Bendersky wrote: Initially I was *for* documenting, but this thing with showing up in the index is a compelling counter-point. The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:. (http://docs.python.org/documenting/markup.html#information-units) Ezio, this is also a good idea, but currently I really think placing this documentation in the devguide is probably the best approach. Now we have a very nice Devguide, and this documentation simply belongs there, and not in the user-visible portion of the official Python documentation. You mean the dev guide only accessible online? It could be included in HowTos (Help develop Python). If you are going to un-index the section, whereever it is, please put the entries in alpha order instead of the current jumble. Or is the current order somehow makes sense, an alphabetical index at the top. -- 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] Convention on functions that shadow existing stdlib functions
On Wed, Jul 27, 2011 at 06:36, R. David Murray rdmur...@bitdance.comwrote: On Wed, 27 Jul 2011 16:14:40 +0300, Eli Bendersky eli...@gmail.com wrote: 1. In the documentation of test.support mention explicitly that it's code for CPython's internal use only, and these APIs aren't guaranteed to be stable. This was already done. 2. Some functions like unlink and rmtree are obviously redundant, and shadow frequently used Python stdlib functions, so I would either kill them completely or at least rename them appropriately. But they aren't redundant, since the test.support versions ignore errors. Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, but then we need to do a pass through the module to make sure that the docstrings are properly updated and we start deprecating some of the stuff in there that is just pure cruft. ___ 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] Convention on functions that shadow existing stdlib functions
Ezio, this is also a good idea, but currently I really think placing this documentation in the devguide is probably the best approach. Now we have a very nice Devguide, and this documentation simply belongs there, and not in the user-visible portion of the official Python documentation. You mean the dev guide only accessible online? Yes. You can also pull it from http://hg.python.org/devguide/ for a local copy (hg.python.org also allows to download a ZIP). My point being - isn't the official Python documentation targeted at *users* of Python, and wasn't the devguide specifically created for *developers* of Python? If so, then test.support clearly being the domain of developers rather than users, belongs in the devguide. Eli ___ 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] Convention on functions that shadow existing stdlib functions
--- Side note: test.support.import_fresh_**module typo. /is/if/ in This function will raise unittest.SkipTest is the named module cannot be imported. Fixed in 8989aa5b357c Eli ___ 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] Convention on functions that shadow existing stdlib functions
On 7/27/2011 9:24 AM, Antoine Pitrou wrote: Docstrings are sufficient for own our purposes. import test.support as t help(t.rmtree) Help on function rmtree in module test.support: rmtree(path) ;-) -- 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] Convention on functions that shadow existing stdlib functions
On 7/27/2011 1:27 PM, Brett Cannon wrote: Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, We already do. 25.6. test.support — Utility functions for tests is about half of the page that also contains 25.5. test — Regression tests package for Python The latter contains 25.5.1. Writing Unit Tests for the test package which should also be moved to the dev guide if 25.6 is. That would leave 25.5 as a short page explaining what lib/test is and how to run the tests, which is something user sometimes need to do. but then we need to do a pass through the module to make sure that the docstrings are properly updated and we start deprecating some of the stuff in there that is just pure cruft. I believe that is what Eli is doing and hence the suggestion to dump .rmtree. Agreed that missing doc strings should be 'updated' from ''. -- 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] Convention on functions that shadow existing stdlib functions
I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, We already do. 25.6. test.support — Utility functions for tests is about half of the page that also contains 25.5. test — Regression tests package for Python The latter contains 25.5.1. Writing Unit Tests for the test package which should also be moved to the dev guide if 25.6 is. +1 That would leave 25.5 as a short page explaining what lib/test is and how to run the tests, which is something user sometimes need to do. Out of curiosity, why would a user need to run Python's tests? Eli ___ 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] Convention on functions that shadow existing stdlib functions
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 07/27/2011 01:57 PM, Eli Bendersky wrote: Out of curiosity, why would a user need to run Python's tests? A couple of cases occur to me: - - To verify that they got a corrrect build with all expected modules included. - - To test the build after updating an underlying system library. 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/ iEYEARECAAYFAk4wVB4ACgkQ+gerLs4ltQ5NSACfXg7QoZAFNHWehT81oPTUwzoo +m4AnRMQFcGod1/3XxEk/T6CDVpE7i7c =/VoI -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] Convention on functions that shadow existing stdlib functions
On 7/27/2011 1:57 PM, Eli Bendersky wrote: Out of curiosity, why would a user need to run Python's tests? If one compiles Python, running the tests is essential. Some people like to run a test suite to verify an installation. Sometimes people have problems that might arise from an installation getting messed up. Whatever is left of 25.5 in the public doc, I think *all* the info should be in the dev guide. -- 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] Convention on functions that shadow existing stdlib functions
Eli Bendersky wrote: I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, We already do. 25.6. test.support — Utility functions for tests is about half of the page that also contains 25.5. test — Regression tests package for Python The latter contains 25.5.1. Writing Unit Tests for the test package which should also be moved to the dev guide if 25.6 is. +1 That would leave 25.5 as a short page explaining what lib/test is and how to run the tests, which is something user sometimes need to do. Out of curiosity, why would a user need to run Python's tests? Curiosity. ;) ~Ethan~ ___ 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] Convention on functions that shadow existing stdlib functions
On Wed, 27 Jul 2011 10:27:16 -0700 Brett Cannon br...@python.org wrote: Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, but then we need to do a pass through the module to make sure that the docstrings are properly updated and we start deprecating some of the stuff in there that is just pure cruft. We don't need to deprecate that cruft, we can just remove it (and all uses of it, of course). 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] Convention on functions that shadow existing stdlib functions
On Thu, Jul 28, 2011 at 3:27 AM, Brett Cannon br...@python.org wrote: On Wed, Jul 27, 2011 at 06:36, R. David Murray rdmur...@bitdance.com wrote: Perhaps what we could do is move the documentation for test.support to the devguide, and then vet the test suite so that unlink and friends are always called as 'support.unlink', etc. I like this solution since this issue of documenting test.support keeps coming up. Otherwise we can not document test.support, but then we need to do a pass through the module to make sure that the docstrings are properly updated and we start deprecating some of the stuff in there that is just pure cruft. +1 for relocating this to the devguide. The only reason this is in the main docs now is that it used to be the only way to easily get pretty documentation for it. 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] Convention on functions that shadow existing stdlib functions
Eli Bendersky wrote: Sure, but I'm still leery of two functions with the same name doing acting slightly differently. and then in a later post: As I mentioned elsewhere, it's not good practice to have two functions with the same name doing something slightly different, in different modules in the code-base. artist.draw() and gunslinger.draw() do not necessarily need to do the same thing, and I don't agree that a (futile) preference for globally unique names is good practice: it can lead to unnecessarily long names (artist.draw_with_pencil_on_paper) or redundant characters prefixing the name (itertools.imap -- what does the i in imap tell you that the itertools didn't already?). Solving this problem is what namespaces are for. Renaming test.support.ulink to something else doesn't fix the problem of unsupported support functions being used in third-party code. It may even *encourage* it, by making the extra functionality more explicit. However, is there any reason why test.support itself shouldn't be renamed test._support, or possibly _test.support, so that the *entire* suite is marked as a private 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] Convention on functions that shadow existing stdlib functions
On Thu, Jul 28, 2011 at 02:53, Steven D'Aprano st...@pearwood.info wrote: Eli Bendersky wrote: Sure, but I'm still leery of two functions with the same name doing acting slightly differently. and then in a later post: As I mentioned elsewhere, it's not good practice to have two functions with the same name doing something slightly different, in different modules in the code-base. artist.draw() and gunslinger.draw() do not necessarily need to do the same thing, Of course, but why do you ignore the slightly different. Had support.rmtree been something completely different from shutil.rmtree, I wouldn't have a problem with it. But it just calls rmtree and ignores some errors. This is the part I have the problem with. Eli ___ 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] Convention on functions that shadow existing stdlib functions
On Sat, Jul 23, 2011 at 20:35, Eli Bendersky eli...@gmail.com wrote: Some background: I'm working (on and off) on issue 11015 - documenting the public functions in test.support Some of the functions in test.support (for example unlink, rmtree) simply shadow existing popular stdlib functions, with the aim of swallowing the exceptions these may throw. This is confusing, IMHO. For example, grepping 'unlink' on Lib/test/test_*.py files doesn't say much about which unlink is being used. A couple of options to handle this are: 1. Remove these functions altogether, trying to use existing constructs (such as the ignore_errors parameter in rmtree). 2. Adapt a naming convention for such functions, for instance rmtree_silent and unlink_silent (or a similar convention, if one exists) Opinions? The mere fact that these functions exist in a different module suggests different semantics from those found in other places in the stdlib. I don't think they should be renamed simply because some code imports the functions directly instead of the module itself (suggesting they should be doing the latter over the former). Now if the functions are redundant that's something else entirely and removal should be fine. ___ 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] Convention on functions that shadow existing stdlib functions
Some background: I'm working (on and off) on issue 11015 - documenting the public functions in test.support Some of the functions in test.support (for example unlink, rmtree) simply shadow existing popular stdlib functions, with the aim of swallowing the exceptions these may throw. This is confusing, IMHO. For example, grepping 'unlink' on Lib/test/test_*.py files doesn't say much about which unlink is being used. A couple of options to handle this are: 1. Remove these functions altogether, trying to use existing constructs (such as the ignore_errors parameter in rmtree). 2. Adapt a naming convention for such functions, for instance rmtree_silent and unlink_silent (or a similar convention, if one exists) Opinions? Eli ___ 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
