Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

Guido van Rossum wrote: Somehow "unraisable" sounds too technical, It's not even really accurate. It's been raised, it just can't be propagated any further. But "unpropagatable exception" would be a bit of a mouthful. -- Greg ___ Python-Dev mailing

Re: [Python-Dev] Best practice for documentation for std lib

Guido van Rossum writes: > On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano wrote: >> My own preference is to err on the side of too much rather than >> too little, since I live by help() and only fall back on the web >> documentation when I really must. > I guess preferences differ. Indee

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 9/22/2013 9:29 PM, Guido van Rossum wrote: On Sunday, September 22, 2013, Nick Coghlan wrote: Brevity is still a virtue. The relevant C API function is called "PyErr_WriteUnraisable", so just starting the message as something like "Unraisable exception suppressed in..." might work

Re: [Python-Dev] Enum Eccentricities

On Sunday, September 22, 2013, Zero Piraeus wrote: > I may be misunderstanding the use case given in the issue, but it seems > to me that having to use > > Color.red.__class__.blue > > (what is being complained about in the issue), while not exactly pretty, > makes a lot more semantic sense th

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 09/22/2013 08:24 PM, Nick Coghlan wrote: On 23 Sep 2013 06:38, "Terry Reedy" mailto:tjre...@udel.edu>> wrote: On 9/22/2013 2:41 PM, Guido van Rossum wrote: On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy mailto:tjre...@udel.edu> >> wrote:

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On Sunday, September 22, 2013, Nick Coghlan wrote: > > Brevity is still a virtue. The relevant C API function is called > "PyErr_WriteUnraisable", so just starting the message as something like > "Unraisable exception suppressed in..." might work. > Somehow "unraisable" sounds too technical, and "

Re: [Python-Dev] Enum Eccentricities

: On Sun, Sep 22, 2013 at 04:52:36PM -0700, Ethan Furman wrote: > So, as anyone who has worked with Enum is probably aware by now, > Enum's are a strange duck -- you might even call them platypuses. Yes :-) > What I'm looking for feedback on is the question is #19011: should an > Enum member be

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 23 Sep 2013 06:38, "Terry Reedy" wrote: > > On 9/22/2013 2:41 PM, Guido van Rossum wrote: >> >> On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy > > wrote: >> >> On 9/21/2013 10:30 PM, Guido van Rossum wrote: >> >> Exceptions in __del__ point to bugs (sometimes

Re: [Python-Dev] Enum Eccentricities

Ethan Furman wrote: Also, if we change Enum so that members do act more like class attributes, then things like Color.red.blue.green.blue will result in Color.blue, I thought we already decided it was worth making that not happen? -- Greg ___ Python

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy wrote: > On 9/22/2013 10:04 PM, Guido van Rossum wrote: > > If I had the final word, I'd recommend using the current docstrings as >> the .rst contents and replacing the docstrings with the 1-2 line >> function descriptions from the PEP, e.g.: >> >>

Re: [Python-Dev] Enum Eccentricities

On Sun, Sep 22, 2013 at 4:52 PM, Ethan Furman wrote: > http://bugs.python.org/**issue19011 > > So, as anyone who has worked with Enum is probably aware by now, Enum's > are a strange duck -- you might even call them platypuses. > > For example, Enum members are

Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:04 PM, Guido van Rossum wrote: If I had the final word, I'd recommend using the current docstrings as the .rst contents and replacing the docstrings with the 1-2 line function descriptions from the PEP, e.g.: * median(data) -> median (middle value) of data, taking t

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano wrote: > On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote: > > > Authors writing 3rd party packages can do what they want. > > > > But for the stdlib it's been settled for ages: docstrings should be > concise > > (but not cryptic(*))

Re: [Python-Dev] PEP 455: TransformDict

On 09/14/2013 12:31 PM, Guido van Rossum wrote: On Fri, Sep 13, 2013 at 11:40 AM, Antoine Pitrou wrote: Following the python-dev discussion, I've written a PEP to recap the proposal and the various arguments. It's inlined below, and it will probably appear soon at http://www.python.org/dev/peps

[Python-Dev] Enum Eccentricities

http://bugs.python.org/issue19011 So, as anyone who has worked with Enum is probably aware by now, Enum's are a strange duck -- you might even call them platypuses. For example, Enum members are instances of the class, but they are defined inside the class structure, and new ones cannot be cr

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote: > Authors writing 3rd party packages can do what they want. > > But for the stdlib it's been settled for ages: docstrings should be concise > (but not cryptic(*)), longer documentation go into the separately written > text for docs

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 5:07 PM, Steven D'Aprano wrote: > If you're going to the source to read docstrings, you're doing it wrong > :-) > Be that as it may, when I'm reading the source I'm grateful for docstrings. *And* I'm grateful when they are short. -- --Guido van Rossum (python.org/~guido)

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 05:54:57AM -0700, Eli Bendersky wrote: > IMHO the right way to think about it is that the .rst files are by far the > more important documentation. Sometimes we forget that most Python > programmers are people who won't go into the source to read docstrings. Docstrings are

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote: > The points here are that there's a single source of truth (so we can't > have conflicting docstring and rst documentation), and documentation > becoming outdated can be noticed from both docstring and published > documentation. > Another case

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky wrote: > > On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum wrote: > >> On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: >> >>> >>> I think there's a general agreement in this thread that we don't intend >>> to change the status quo. Both .

Re: [Python-Dev] Best practice for documentation for std lib

Well, I'm wholly confused now, so I'll leave this discussion to the devs. > -Original Message- > From: Python-Dev [mailto:python-dev-bounces+anikom15=gmail@python.org] On > Behalf Of Xavier Morel > Sent: Sunday, September 22, 2013 2:42 PM > To: python-dev > Subject: Re: [Python-Dev] Be

Re: [Python-Dev] Best practice for documentation for std lib

On 2013-09-22, at 21:24 , Westley Martínez wrote: >> From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido >> van Rossum >> Sent: Sunday, September 22, 2013 11:35 AM >> >> You seem to misunderstand the use of "autogeneration". It refers to >> generating >> the .rst docs fr

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 9/22/2013 2:41 PM, Guido van Rossum wrote: On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy mailto:tjre...@udel.edu>> wrote: On 9/21/2013 10:30 PM, Guido van Rossum wrote: Exceptions in __del__ point to bugs (sometimes in the stdlib) that should be fixed, period. The only re

Re: [Python-Dev] Best practice for documentation for std lib

> From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido > van Rossum > Sent: Sunday, September 22, 2013 11:35 AM > > You seem to misunderstand the use of "autogeneration". It refers to generating > the .rst docs from the docstrings in the source. And FWIW, I'm against that >

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum wrote: > On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: > >> >> I think there's a general agreement in this thread that we don't intend >> to change the status quo. Both .rst docs and docstrings are important. The >> remaining question i

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy wrote: > On 9/21/2013 10:30 PM, Guido van Rossum wrote: > >> Exceptions in __del__ point to bugs (sometimes in the stdlib) that >> should be fixed, period. The only reason they do not result in >> exceptions that are properly bubbled up and catchable

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: > > I think there's a general agreement in this thread that we don't intend to > change the status quo. Both .rst docs and docstrings are important. The > remaining question is - can we use some tool to generates parts of the > former from th

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:02 AM, Westley Martínez wrote: > Since help() is usually the first thing I use to remind myself of an > API, it's imperative that the doc strings are up to date and make sense > to end users. > > So, autogeneration of doc strings would be good for someone like me who > h

Re: [Python-Dev] Best practice for documentation for std lib

Since help() is usually the first thing I use to remind myself of an API, it's imperative that the doc strings are up to date and make sense to end users. So, autogeneration of doc strings would be good for someone like me who hardly uses the html docs. > -Original Message- > From: Python

Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:25 AM, Nick Coghlan wrote: As Georg noted, we'd have to do some fancy footwork to make sure autodoc didn't pick up the wrong module versions for the standard library docs, though. Is that a one-time nuisance, a per-module nuisance, a per-autodoc-use nuisance, or a per-build nu

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 9/21/2013 10:30 PM, Guido van Rossum wrote: Exceptions in __del__ point to bugs (sometimes in the stdlib) that should be fixed, period. The only reason they do not result in exceptions that are properly bubbled up and catchable is because __del__ is called from a DECREF macro which has no retu

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 08:49 AM, Barry Warsaw wrote: On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: The rule of thumb I go by is the docstring should be enough to answer the question "what args does this thing take and what does it do in general to know it's the function I want and another one in the

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum wrote: > On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull > wrote: > >> Eli Bendersky writes: >> >> > IMHO the right way to think about it is that the .rst files are by >> > far the more important documentation. Sometimes we forget that >

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull wrote: > Eli Bendersky writes: > > > IMHO the right way to think about it is that the .rst files are by > > far the more important documentation. Sometimes we forget that > > most Python programmers are people who won't go into the source >

Re: [Python-Dev] Best practice for documentation for std lib

Eli Bendersky writes: > IMHO the right way to think about it is that the .rst files are by > far the more important documentation. Sometimes we forget that > most Python programmers are people who won't go into the source Why "source"? The whole point of docstrings is that they are *not* com

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw wrote: > On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: > > >The rule of thumb I go by is the docstring should be enough to answer the > >question "what args does this thing take and what does it do in general to > >know it's the function I want an

Re: [Python-Dev] Best practice for documentation for std lib

On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: >The rule of thumb I go by is the docstring should be enough to answer the >question "what args does this thing take and what does it do in general to >know it's the function I want and another one in the same module?" quickly >and succinctly; i.e.

Re: [Python-Dev] Best practice for documentation for std lib

> On 22 Sep 2013, at 05:25, Benjamin Peterson wrote: > > There's not really much to do but maintain them separately. Truncate > the docstrings if it makes life easier. Autodoc could be enabled and allowed in a limited manner. ___ Python-Dev mailing lis

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano wrote: > On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: > > On Sun, 22 Sep 2013 13:13:04 +1000 > > Steven D'Aprano wrote: > > > Hi all, > > > > > > I have a question about how I should manage documentation for the > > > statistics

Re: [Python-Dev] Best practice for documentation for std lib

On 23 September 2013 00:16, Eli Bendersky wrote: > That's a good point. I would still posit that HTML documentation gets by far > the most use, but docstrings are definitely important too. One more point in > favor of either: > > 1. Maintaining both, as tiresome as it is (we try to do this, not al

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl wrote: > On 09/22/2013 02:54 PM, Eli Bendersky wrote: > > > > > > > > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano > > wrote: > > > > Hi all, > > > > I have a question about how I should manage documentation fo

Re: [Python-Dev] Best practice for documentation for std lib

On 22 September 2013 13:54, Eli Bendersky wrote: > IMHO the right way to think about it is that the .rst files are by far the > more important documentation. Sometimes we forget that most Python > programmers are people who won't go into the source to read docstrings. While I agree entirely with

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 02:54 PM, Eli Bendersky wrote: > > > > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano > wrote: > > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have ex

Re: [Python-Dev] Best practice for documentation for std lib

On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too much info

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: > On Sun, 22 Sep 2013 13:13:04 +1000 > Steven D'Aprano wrote: > > Hi all, > > > > I have a question about how I should manage documentation for the > > statistics module for Python 3.4. At the moment, I have extensive > > docstring

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 12:16 PM, Nick Coghlan wrote: > On 22 September 2013 18:54, Georg Brandl wrote: >> I don't really buy the argument "but then there is no complete documentation >> set in the checkout" -- who reads that in preference to docs.python.org? >> And if anybody does want plain-text docs, the

Re: [Python-Dev] Best practice for documentation for std lib

On 2013-09-22, at 12:16 , Nick Coghlan wrote: > > It's a bit of a pain, and we do occasionally get bug reports where the > docstrings get out of date, but it's the least bad of the currently > available options. Is it really less bad than allowing limited fine-grained use of autodoc? Not necessar

Re: [Python-Dev] Best practice for documentation for std lib

On 22 September 2013 18:54, Georg Brandl wrote: > I don't really buy the argument "but then there is no complete documentation > set in the checkout" -- who reads that in preference to docs.python.org? > And if anybody does want plain-text docs, they are already available for build > and for downl

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On Sun, 22 Sep 2013 10:48:33 +0200 Georg Brandl wrote: > On 09/22/2013 10:19 AM, Antoine Pitrou wrote: > > On Sat, 21 Sep 2013 19:55:05 -0400 > > Terry Reedy wrote: > >> > >> > In the general case it represents a bug in > >> > the code that should be fixed. Most such errors arise from the vaga

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 05:13 AM, Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too much informatio

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On 09/22/2013 10:19 AM, Antoine Pitrou wrote: > On Sat, 21 Sep 2013 19:55:05 -0400 > Terry Reedy wrote: >> >> > In the general case it represents a bug in >> > the code that should be fixed. Most such errors arise from the vagaries >> > of module finalization (such as your issue 19021), >> >> L

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, 22 Sep 2013 13:13:04 +1000 Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too muc

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

On Sat, 21 Sep 2013 19:55:05 -0400 Terry Reedy wrote: > > > In the general case it represents a bug in > > the code that should be fixed. Most such errors arise from the vagaries > > of module finalization (such as your issue 19021), > > Lets call that a buglet ;-). Not really harmful, but anno

Re: [Python-Dev] Best practice for documentation for std lib

I don't like having to browse the source code to read the documentation. I prefer short docstring and longer reST documentation. In ReST, you get a table of content and nice links to functions, modules, etc. When I read doc, I like having two levels: tutorial listing most important functions and p