Re: [Python-Dev] Best practice for documentation for std lib
Am 23.09.2013 00:03, schrieb Guido van Rossum: > AFAIU, the proposal is to embed parts of the concise docstring into the > more > verbose .rst documentation. > > > I still think that's a bad idea. Someone editing the docstring may introduce a > terminology change or some other style/grammar/flow change that makes > perfectly > sense by itself but doesn't when taken in the context of the larger .rst doc > (e.g. it could introducing duplication or cause dissonance between the two > parts). Yes, this style is better suited for smaller documentations where there isn't that much more info in the .rst than in the docstring -- the .rst giving maybe an introduction and then just a logical order in which docstrings are pulled. Since we have the policy (now reconfirmed) of small docstrings and more verbose prose on docs.python.org, this would not be feasible there. > Also, someone who wants to improve the docs would have to figure out how > to edit the source code if they wanted to change some part of the docs. I agree that is another good point. And should the "suggest a change on docs.python.org" feature ever be shipped, it will be much harder, if not impossible, to generate a patch and let developers submit it automatically. > I write .rst docs quite a lot, and as such I do notice the annoying amount > of duplication between docstrings and .rst docs. Without doubt, all the > free-flow text and examples in .rst have to be written manually and are > very > important. But for dry method references, it's certainly interesting to > explore the idea of writing them once in the code and then having Sphinx > automatically insert the relevant parts into the .rst before generating > HTML > from it. For end users (those who read the docs online) the result is > indistinguishable from what we have now. For us devs it means writing the > same text only once and maintaining it in a single place. > > > You seem to have caught the DRY bug. But it doesn't always make sense to > factor > things so that everything is said in exactly one place. (For an example of > abstraction gone wild, ironically, see docutils and sphinx. I challenge you to > find out the actual code that translates e.g. :meth:`foobar` into href="(what > goes here?)">foobar. :-) PSA: I can only recommend to everyone not to take up Guido's dare... (and I'm not terribly proud of that). cheers, Georg ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
Am 24.09.2013 00:11, schrieb Greg Ewing: > Antoine Pitrou wrote: >> Yes, but I agree with Greg that "unraisable" is wrong. After all, it >> was raised, and it can even be caught by the programmer (inside >> __del__). > > How about something like "Uncaught exception in __del__ > method ignored"? It explains fairly clearly what has > happened, and also indicates what do do about it -- > catch it in the __del__ method. "Exception in __del__ caught and not propagated:" Georg ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 9/24/2013 5:51 AM, Nick Coghlan wrote: > Why not just say something like "Cannot propagate exception..."; it's > simpler than "Unpropagatable exception...". That would definitely be an improvement on the status quo and avoids Antoine's concern about an adjective being interpreted as an inherent property of the exception rather than the circumstances where the exception was encountered. First one I've heard that accurately and unambiguously and briefly describes the issue. +1 ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
24.09.2013 10:16, Antoine Pitrou wrote: On Tue, 24 Sep 2013 18:06:15 +1000 Nick Coghlan wrote: How is it wrong? At the point where the interpreter says "This exception is now unraisable", what, precisely, is it saying that is wrong? It isn't saying "this has never been raised". It is saying, "where it is currently being processed, this exception cannot be raised". Well, it is saying it. If it's conceptually unraisable, it can't be raised. I know your point is that it is only unraisable *now*, but that's not the intuitive interpretation. And what about: Exception not propagated from > ... Or: Exception that cannot be propagated from > ... Cheers. *j ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24 Sep 2013 20:06, "MRAB" wrote: > > On 24/09/2013 09:06, Nick Coghlan wrote: >> >> On 24 September 2013 17:34, Antoine Pitrou wrote: >>> >>> On Tue, 24 Sep 2013 17:25:10 +1000 >>> Nick Coghlan wrote: You are setting the bar unreasonably high for an error message that has to convey a complex concept in as few words as possible. There is *NO* wording that can concisely express the concepts involved without resorting to jargon, because the concepts behind it are *complex and unintuitive*. The current wording is flat out wrong, because the exception isn't being ignored, it's being printed to stderr. If it was genuinely being ignored, people wouldn't complain about it. Jargon that can be easily looked up with a search engine is greatly superior to a message that is simply wrong, as the former provides a gateway to understanding, just like coming across a word you don't understand when reading a novel. >>> >>> >>> "Unraisable" is not a word I don't understand, it's a word that I >>> understand and which conveys the wrong meaning. >> >> >> How is it wrong? At the point where the interpreter says "This >> exception is now unraisable", what, precisely, is it saying that is >> wrong? >> >> It isn't saying "this has never been raised". It is saying, "where it >> is currently being processed, this exception cannot be raised". >> >>> If you want something that people won't understand, you can use >>> something like "asynchronous exception". >> >> >> Asynchronous exception is *even more* wrong, because that's the >> terminology used for an exception injected into the current thread by >> a different thread. >> Preferring the status quo because you're holding out a forlorn hope for a concise wording that explains: >>> >>> >>> I've proposed other options. >> >> >> "Automatically caught" says nothing about why the exception is being >> printed to stderr instead of propagating normally. Exceptions are >> automatically caught by any matching except clause all the time, but >> most of those don't result in errors printed to stderr. >> > Why not just say something like "Cannot propagate exception..."; it's > simpler than "Unpropagatable exception...". That would definitely be an improvement on the status quo and avoids Antoine's concern about an adjective being interpreted as an inherent property of the exception rather than the circumstances where the exception was encountered. Cheers, Nick. > > ___ > Python-Dev mailing list > Python-Dev@python.org > https://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Best practice for documentation for std lib
On 23.09.13 17:18, Skip Montanaro wrote: It would be great if the docstring contained a link to the online documentation. That would have to be a feature of help(), not hardcoded in each docstring. That *is* a feature of the help function: Help on built-in module sys: help(sys) NAME sys FILE (built-in) MODULE DOCS http://docs.python.org/library/sys ... (pydoc too, though I'm 99.9% sure they use the same underlying facility Ping originally implemented.) Hmm, but it doesn't work for functions: >>> import sys >>> help(sys.settracee) Help on built-in function settrace in module sys: settrace(...) settrace(function) Set the global debug tracing function. It will be called on each function call. See the debugger chapter in the library manual. Servus, Walter ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24/09/2013 09:06, Nick Coghlan wrote: On 24 September 2013 17:34, Antoine Pitrou wrote: On Tue, 24 Sep 2013 17:25:10 +1000 Nick Coghlan wrote: You are setting the bar unreasonably high for an error message that has to convey a complex concept in as few words as possible. There is *NO* wording that can concisely express the concepts involved without resorting to jargon, because the concepts behind it are *complex and unintuitive*. The current wording is flat out wrong, because the exception isn't being ignored, it's being printed to stderr. If it was genuinely being ignored, people wouldn't complain about it. Jargon that can be easily looked up with a search engine is greatly superior to a message that is simply wrong, as the former provides a gateway to understanding, just like coming across a word you don't understand when reading a novel. "Unraisable" is not a word I don't understand, it's a word that I understand and which conveys the wrong meaning. How is it wrong? At the point where the interpreter says "This exception is now unraisable", what, precisely, is it saying that is wrong? It isn't saying "this has never been raised". It is saying, "where it is currently being processed, this exception cannot be raised". If you want something that people won't understand, you can use something like "asynchronous exception". Asynchronous exception is *even more* wrong, because that's the terminology used for an exception injected into the current thread by a different thread. Preferring the status quo because you're holding out a forlorn hope for a concise wording that explains: I've proposed other options. "Automatically caught" says nothing about why the exception is being printed to stderr instead of propagating normally. Exceptions are automatically caught by any matching except clause all the time, but most of those don't result in errors printed to stderr. Why not just say something like "Cannot propagate exception..."; it's simpler than "Unpropagatable exception...". ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On Tue, 24 Sep 2013 18:06:15 +1000 Nick Coghlan wrote: > > How is it wrong? At the point where the interpreter says "This > exception is now unraisable", what, precisely, is it saying that is > wrong? > It isn't saying "this has never been raised". It is saying, "where it > is currently being processed, this exception cannot be raised". Well, it is saying it. If it's conceptually unraisable, it can't be raised. I know your point is that it is only unraisable *now*, but that's not the intuitive interpretation. > >> Preferring the status quo because > >> you're holding out a forlorn hope for a concise wording that explains: > > > > I've proposed other options. > > "Automatically caught" says nothing about why the exception is being > printed to stderr instead of propagating normally. Exceptions are > automatically caught by any matching except clause all the time, but > most of those don't result in errors printed to stderr. I would say they are manually caught by except clauses (user code == manual intervention), and automatically caught when "silenced" or "unraised" by the interpreter. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24 September 2013 17:34, Antoine Pitrou wrote: > On Tue, 24 Sep 2013 17:25:10 +1000 > Nick Coghlan wrote: >> >> You are setting the bar unreasonably high for an error message that >> has to convey a complex concept in as few words as possible. There is >> *NO* wording that can concisely express the concepts involved without >> resorting to jargon, because the concepts behind it are *complex and >> unintuitive*. The current wording is flat out wrong, because the >> exception isn't being ignored, it's being printed to stderr. If it was >> genuinely being ignored, people wouldn't complain about it. >> >> Jargon that can be easily looked up with a search engine is greatly >> superior to a message that is simply wrong, as the former provides a >> gateway to understanding, just like coming across a word you don't >> understand when reading a novel. > > "Unraisable" is not a word I don't understand, it's a word that I > understand and which conveys the wrong meaning. How is it wrong? At the point where the interpreter says "This exception is now unraisable", what, precisely, is it saying that is wrong? It isn't saying "this has never been raised". It is saying, "where it is currently being processed, this exception cannot be raised". > If you want something that people won't understand, you can use > something like "asynchronous exception". Asynchronous exception is *even more* wrong, because that's the terminology used for an exception injected into the current thread by a different thread. >> Preferring the status quo because >> you're holding out a forlorn hope for a concise wording that explains: > > I've proposed other options. "Automatically caught" says nothing about why the exception is being printed to stderr instead of propagating normally. Exceptions are automatically caught by any matching except clause all the time, but most of those don't result in errors printed to stderr. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?
On 24 September 2013 09:34, Ned Deily wrote: > In general, I think this is a very important usability feature and I > am in favor of the general approach. Good work, all! I do have some > comments, primarily about items that are not currently addressed. Your reply and Barry's suggest that Betteridge's law [1] applies to email subject lines, too ;) As far as easy_install goes, my current plan was actually to tackle that on the upstream side. If pip still depends on setuptools by the time of the Python 3.4 release, then it will depend on the *real* setuptools, easy_install and all. From my perspective, one golden rule of this integration is that we do *not* mess with the contents of the wheel files for pip and its dependencies - they're pristine upstream releases. This is mostly for technical reasons, but it also draws a sharp line of demarcation for any "aggregation or derivation?" questions, too. If pip has been updated by the time of its inclusion to depend on a cut down setuptools derivative that omits easy_install (or pip has switched to its own internal replacements instead), so much the better, but I consider that to be essentially independent of the CPython bundling situation, since it isn't something we have direct control over, and I consider the slight downside of potentially installing easy_install alongside pip to be dwarfed by the benefits of installing pip. As far as I am aware, the licensing on setuptools is currently limited to the "ZPL or PSF" declaration in the distribution metadata. Cheers, Nick. [1] https://en.wikipedia.org/wiki/Betteridge%27s_law_of_headlines -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On Tue, 24 Sep 2013 17:25:10 +1000 Nick Coghlan wrote: > > You are setting the bar unreasonably high for an error message that > has to convey a complex concept in as few words as possible. There is > *NO* wording that can concisely express the concepts involved without > resorting to jargon, because the concepts behind it are *complex and > unintuitive*. The current wording is flat out wrong, because the > exception isn't being ignored, it's being printed to stderr. If it was > genuinely being ignored, people wouldn't complain about it. > > Jargon that can be easily looked up with a search engine is greatly > superior to a message that is simply wrong, as the former provides a > gateway to understanding, just like coming across a word you don't > understand when reading a novel. "Unraisable" is not a word I don't understand, it's a word that I understand and which conveys the wrong meaning. If you want something that people won't understand, you can use something like "asynchronous exception". > Preferring the status quo because > you're holding out a forlorn hope for a concise wording that explains: I've proposed other options. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24 September 2013 17:25, Nick Coghlan wrote: > Preferring the status quo because > you're holding out a forlorn hope for a concise wording that explains: > > - there are places where exceptions may occur but the interpreter > can't reraise them > - this is one of those cases, so we're printing it to stderr instead > > *without users needing to do any research*. Oops, reworded the second part of that sentence without fixing the first part. It should have said: == It doesn't make sense to prefer the status quo because you're holding out a forlorn hope for a concise wording that explains: - there are places where exceptions may occur but the interpreter can't reraise them - this is one of those cases, so we're printing it to stderr instead *without users needing to do any research*. == Regards, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24 September 2013 10:50, Stephen J. Turnbull wrote: > MRAB writes: > > > > The word doesn't literally mean the exception itself was unraisable. It > > > means it was raised, we caught it and we're writing it to stderr because > > > we *can't raise it again*. > > > Ah, you mean "unreraisable". :-) > > +1 > > Ugly as sin, but satisfies all other criteria (except for Antoine's "easily > understandable" which simply can't be satisfied). If you're drawing a distinction between the first time an exception hits the eval loop and the second and subsequent times, then neither "Unraisable" nor "Unreraisable" is 100% correct. I just think it's a meaningless distinction, which is why I favour "Unraisable" - at the point in time where that message is displayed, that exception cannot be raised any further, whether it was created directly from C or was received from an underlying call back into Python code.. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message
On 24 September 2013 08:29, Antoine Pitrou wrote: > On Mon, 23 Sep 2013 14:38:48 -0700 > Ethan Furman wrote: >> > But that's because you already know what it's supposed to convey. The >> > average user doesn't, and only sees "unraisable". >> >> All the more reason to have text in the error message that is easily >> searchable. > > Then I propose "CA6yuaYV6dygPfJRxUrhtg". It should be easily > searchable ;-) > > Seriously, "easily searchable" is a rather weak criterion for an > error message. It should be easily understandable and non-misleading > first. You are setting the bar unreasonably high for an error message that has to convey a complex concept in as few words as possible. There is *NO* wording that can concisely express the concepts involved without resorting to jargon, because the concepts behind it are *complex and unintuitive*. The current wording is flat out wrong, because the exception isn't being ignored, it's being printed to stderr. If it was genuinely being ignored, people wouldn't complain about it. Jargon that can be easily looked up with a search engine is greatly superior to a message that is simply wrong, as the former provides a gateway to understanding, just like coming across a word you don't understand when reading a novel. Preferring the status quo because you're holding out a forlorn hope for a concise wording that explains: - there are places where exceptions may occur but the interpreter can't reraise them - this is one of those cases, so we're printing it to stderr instead *without users needing to do any research*. A verbose wording is no good either, as that degenerates into a wall of text that people will *still* have to extract pieces from to plug into a search engine to figure out what they mean. Regards, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
