Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Antoine Pitrou 
Le Wed, 26 Jun 2013 18:56:10 -0700,
Guido van Rossum  a écrit :
> PEP 257 says this on the formatting of multi-line docstrings:
> 
> """
> Multi-line docstrings consist of a summary line just like a one-line
> docstring, followed by a blank line, followed by a more elaborate
> description. The summary line may be used by automatic indexing tools;
> it is important that it fits on one line and is separated from the
> rest of the docstring by a blank line. [...]
> """
> 
> I still like this rule, but it is violated frequently, in the stdlib
> and elsewhere. I'd like to urge stdlib contributors and core devs to
> heed it -- or explain why you can't.

I don't always find it easy to summarize a function in one line.

Regards

Antoine.


___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Nick Coghlan 
On 27 June 2013 16:03, Eric Snow  wrote:
> There are two relevant class namespaces in this proposal: definition
> namespace and __dict__.  Currently both are dicts.
>
> For class definition namespaces, I'd like to make the default an
> OrderedDict.  With the implementation in issue16991, the change is
> trivial (basically 1-liners in 2 spots).  This change would make it
> unnecessary to write a custom metaclass just for a __prepare__().  PEP
> 422 alleviates that problem somewhat.  However, I expect OrderedDict
> is by far the most common type returned by __prepare__(), so having it
> be the default would proportionately reduce the need for people to
> write metaclasses or learn about the PEP 422 API.  You may ask what is
> the point if they aren't using a metaclass.

I'd be tempted to kill PEP 422 as not worth the hassle if we did this.
Yes, I count that as a point in favour of the idea :)

> That leads to the other
> half of the proposal.
>
> Once I have a class, I'd like to know the definition order without
> needing a metaclass.  Unfortunately it's not as simple as using the C
> OrderedDict (issue16991 again) for tp_dict, etc.  That change is
> actually pretty trivial.  However, it causes problems because the
> concrete C API (PyDict_*) doesn't play nice with subclasses and the
> concrete API is used on class __dict__ all over the place.  The
> alternative I propose is to add __definition_order__ or similar to
> classes.  It would be a list of the names from the definition
> namespace, in definition order (making use of the new default there).
> Having a class's __dict__ be ordered isn't important if the definition
> order is available somewhere.  Again, using the C OrderedDict, the
> change to add __definition_order__ is pretty trivial.

I think the main concern I would have is whether other implementations
are happy they can provide a suitable ordered dictionary for class
namespace execution.

It's also worth considering what would have to happen for dynamically
created types where the namespace passed in *wasn't* ordered.

It's a plausible way forward, though.

Cheers,
Nick.

--
Nick Coghlan   |   [email protected]   |   Brisbane, Australia
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Python-checkins] peps: Reject PEP 315.

2013-06-27 Thread Łukasz Langa 
On 27 cze 2013, at 00:51, Nick Coghlan  wrote:
> On 27 Jun 2013 03:12, "Łukasz Langa"  wrote:
> > This was a mention of an alternative possible syntax. I don't feel it was 
> > worth keeping this particular one while not discussing any other 
> > alternatives at all. If you'd rather keep this information, it would be 
> > better off to have it to an "Alternative approaches" section.
> 
> It was relevant because it was the most acceptable alternative found, and we 
> *still* didn't think it was an improvement over the status quo.
> 
> We don't generally significantly edit PEPs when accepting or rejecting them.
> 


Comment restored, point taken. Thanks for clearing this up.


-- 
Best regards,
Łukasz Langa

WWW: http://lukasz.langa.pl/
Twitter: @llanga
IRC: ambv on #python-dev

___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Guido van Rossum 
On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou  wrote:
> I don't always find it easy to summarize a function in one line.

Neither do I. But I always manage to do it anyway. My reasoning is,
you can always leave out more detail and add it to the subsequent
paragraph.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Eric Snow 
On Thu, Jun 27, 2013 at 2:48 AM, Nick Coghlan  wrote:
> I think the main concern I would have is whether other implementations
> are happy they can provide a suitable ordered dictionary for class
> namespace execution.
>
> It's also worth considering what would have to happen for dynamically
> created types where the namespace passed in *wasn't* ordered.

Good points.  In either case there is no definition order available.
I'm okay with that.  Would it be better to represent that as None (and
the attribute is always defined) or by having the attribute undefined?
 I'd rather always have the attribute, but I expect the significantly
simpler solution is to leave the attribute undefined when definition
order is not available.  So I'd go with the latter.

-eric
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Larry Hastings 

On 06/26/2013 08:56 PM, Guido van Rossum wrote:

PEP 257 says this on the formatting of multi-line docstrings:

"""
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description. The summary line may be used by automatic indexing tools;
it is important that it fits on one line and is separated from the
rest of the docstring by a blank line. [...]
"""

I still like this rule, but it is violated frequently, in the stdlib
and elsewhere. I'd like to urge stdlib contributors and core devs to
heed it -- or explain why you can't.


Argument Clinic could conceivably enforce this.  It could mandate that 
the first paragraph of the function docstring contain exactly one 
sentence (must end in a period, all embedded periods cannot be followed by
whitespace).  This would make some things nicer; I could automatically 
insert the per-parameter docstrings in after the summary.


Should it?


//arry/
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Guido van Rossum 
Yes on one line, capitalized, period. No on single sentence.

--Guido van Rossum (sent from Android phone)
On Jun 27, 2013 8:17 AM, "Larry Hastings"  wrote:

>  On 06/26/2013 08:56 PM, Guido van Rossum wrote:
>
> PEP 257 says this on the formatting of multi-line docstrings:
>
> """
> Multi-line docstrings consist of a summary line just like a one-line
> docstring, followed by a blank line, followed by a more elaborate
> description. The summary line may be used by automatic indexing tools;
> it is important that it fits on one line and is separated from the
> rest of the docstring by a blank line. [...]
> """
>
> I still like this rule, but it is violated frequently, in the stdlib
> and elsewhere. I'd like to urge stdlib contributors and core devs to
> heed it -- or explain why you can't.
>
>
> Argument Clinic could conceivably enforce this.  It could mandate that the
> first paragraph of the function docstring contain exactly one sentence
> (must end in a period, all embedded periods cannot be followed by
> whitespace).  This would make some things nicer; I could automatically
> insert the per-parameter docstrings in after the summary.
>
> Should it?
>
>
> */arry*
>
> ___
> Python-Dev mailing list
> [email protected]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> http://mail.python.org/mailman/options/python-dev/guido%40python.org
>
>
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Ethan Furman 

On 06/27/2013 08:18 AM, Eric Snow wrote:

On Thu, Jun 27, 2013 at 2:48 AM, Nick Coghlan  wrote:

I think the main concern I would have is whether other implementations
are happy they can provide a suitable ordered dictionary for class
namespace execution.

It's also worth considering what would have to happen for dynamically
created types where the namespace passed in *wasn't* ordered.


Good points.  In either case there is no definition order available.
I'm okay with that.  Would it be better to represent that as None (and
the attribute is always defined) or by having the attribute undefined?
  I'd rather always have the attribute, but I expect the significantly
simpler solution is to leave the attribute undefined when definition
order is not available.  So I'd go with the latter.


So in Python space the options are either:

   if some_class.__definition_order__ is not None:

or

   if getattr(some_class, '__definition_order__', None) is not None:

?

Seems like always defined would be easier.

--
~Ethan~


___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Terry Reedy 

On 6/27/2013 11:57 AM, Guido van Rossum wrote:

Yes on one line, capitalized, period. No on single sentence.


Complete and correct docstrings are somewhat rare in idlelib.
About half are missing.
Single lines typically omit the period.
Multiple lines often omit the blank line after the first.

I will take your reminder as permission to make changes as I review the 
code. I wish there were more good summary lines already.


My understanding is that SubclassTests and test_methods should not have 
docstrings.


--
Terry Jan Reedy

___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Guido van Rossum 
It was never my intention to enforce that everything has a docstring.
Just that if it does, it looks good.

On Thu, Jun 27, 2013 at 9:40 AM, Terry Reedy  wrote:
> On 6/27/2013 11:57 AM, Guido van Rossum wrote:
>>
>> Yes on one line, capitalized, period. No on single sentence.
>
>
> Complete and correct docstrings are somewhat rare in idlelib.
> About half are missing.
> Single lines typically omit the period.
> Multiple lines often omit the blank line after the first.
>
> I will take your reminder as permission to make changes as I review the
> code. I wish there were more good summary lines already.
>
> My understanding is that SubclassTests and test_methods should not have
> docstrings.
>
> --
> Terry Jan Reedy
>
>
> ___
> Python-Dev mailing list
> [email protected]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> http://mail.python.org/mailman/options/python-dev/guido%40python.org



-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Terry Reedy 

On 6/27/2013 12:57 PM, Guido van Rossum wrote:

It was never my intention to enforce that everything has a docstring.
Just that if it does, it looks good.


Ok, I won't add them when a function's name actually makes what it does 
obvious. But when I have to spend at least a few minutes reading the 
body to make sense of it, I will try to add the summary line that I wish 
had been there already.


--
Terry Jan Reedy

___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread PJ Eby 
On Thu, Jun 27, 2013 at 4:48 AM, Nick Coghlan  wrote:
> I'd be tempted to kill PEP 422 as not worth the hassle if we did this.

I assume you mean the "namespace" keyword part of PEP 422, since PEP
422's class initialization feature is entirely orthogonal to
definition order or namespace customization.  (Indeed, I cannot recall
a single instance of class initialization in my code that actually
*cared* about definition order.  Certainly I haven't had any
situations where a pre-existing definition order would've eliminated
the need for a class-level initialization.)
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Eric Snow 
On Thu, Jun 27, 2013 at 9:35 AM, Ethan Furman  wrote:
> On 06/27/2013 08:18 AM, Eric Snow wrote:
>> Good points.  In either case there is no definition order available.
>> I'm okay with that.  Would it be better to represent that as None (and
>> the attribute is always defined) or by having the attribute undefined?
>> I'd rather always have the attribute, but I expect the significantly
>> simpler solution is to leave the attribute undefined when definition
>> order is not available.  So I'd go with the latter.
>
>
> So in Python space the options are either:
>
>if some_class.__definition_order__ is not None:
>
> or
>
>if getattr(some_class, '__definition_order__', None) is not None:
>
> ?
>
> Seems like always defined would be easier.

Certainly it's easier to use if you need the definition order.
However, I expect it wouldn't be used often enough that that would
make a big difference.  Furthermore, if it's always there then it will
always show up when you dir(SomeClass) or look at SomeClass.__dict__.
People would see that on every class, whether it actually provided
definition order or not.  I'm not sure that is as helpful as only
having the attribute around when order is defined.

This got me thinking.  The attribute should be a class-only attribute
(i.e. a property on type) like __name__ is.  That would keep it from
showing up on instance lookups and on every vars(obj).

The big thing for me, though, is that optionally having the attribute
accommodates Python implementations that can't (or don't) preserve
definition order.  They don't have to worry about adding a dummy
attribute to every class just for the sake of complying with the spec.
 It also means the implementation for dynamic types like Nick
mentioned don't necesarily need to be touched.  The more I think about
it the more the optionally set attribute approach is the way to go.

-eric
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Alexander Belopolsky 
On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum  wrote:

> On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou 
> wrote:
> > I don't always find it easy to summarize a function in one line.
>
> Neither do I. But I always manage to do it anyway.


+1

If you cannot summarize what your function does in one line, chances are it
is time to split your function, not the summary line.  Ideally, the name of
the function should already give a good idea of what it does.  A summary
line can just rephrase the same in a complete sentence.

I took a quick look at the stdlib and in many cases a summary line is
already there.  It is just the issue of formatting.

 250
class _ErrorHolder(object):
251
"""
252
Placeholder
for a TestCase inside a result. As far as a TestResult
253
is
concerned, this looks exactly like a unit test. Used to insert
254
arbitrary
errors into a test suite run.
255
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250*

81 
class TestProgram(object):
82 
"""A
command-line program that runs a set of tests; this is primarily
83 
for
making test modules conveniently executable.
84 
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81*

109
@failfast
110
def addError(self, test, err):
111
"""Called
when an error has occurred. 'err' is a tuple of values as
112
returned
by sys.exc_info().
113
"""
114
self.errors.append((test, self._exc_info_to_string(err, test)))
115
self._mirrorOutput = True
116
117
@failfast
118
def addFailure(self, test, err):
119
"""Called
when an error has occurred. 'err' is a tuple of values as
120
returned
by sys.exc_info()."""
121
self.failures.append((test, self._exc_info_to_string(err, test)))
122
self._mirrorOutput = True
123
124
@failfast
125
def addSubTest(self, test, subtest, err):
126
"""Called
at the end of a subtest.
127
'err'
is None if the subtest ended successfully, otherwise it's a
128
tuple
of values as returned by sys.exc_info().
129
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109*
*
*
589  def
do_break(self, arg, temporary = 0):
590  """b(reak)
[ ([filename:]lineno | function) [, condition] ]
591  Without
argument, list all breaks.
*http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589*
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/arch

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Nick Coghlan 
On 28 Jun 2013 07:46, "PJ Eby"  wrote:
>
> On Thu, Jun 27, 2013 at 4:48 AM, Nick Coghlan  wrote:
> > I'd be tempted to kill PEP 422 as not worth the hassle if we did this.
>
> I assume you mean the "namespace" keyword part of PEP 422, since PEP
> 422's class initialization feature is entirely orthogonal to
> definition order or namespace customization.  (Indeed, I cannot recall
> a single instance of class initialization in my code that actually
> *cared* about definition order.  Certainly I haven't had any
> situations where a pre-existing definition order would've eliminated
> the need for a class-level initialization.)

That and the second argument to the new initialisation hook. So you're
right, the consequences for PEP 422 would be "greatly simplify" rather than
"kill".

Cheers,
Nick.
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Classes with ordered namespaces

2013-06-27 Thread Nick Coghlan 
On 28 Jun 2013 07:51, "Eric Snow"  wrote:
>
> On Thu, Jun 27, 2013 at 9:35 AM, Ethan Furman  wrote:
> > On 06/27/2013 08:18 AM, Eric Snow wrote:
> >> Good points.  In either case there is no definition order available.
> >> I'm okay with that.  Would it be better to represent that as None (and
> >> the attribute is always defined) or by having the attribute undefined?
> >> I'd rather always have the attribute, but I expect the significantly
> >> simpler solution is to leave the attribute undefined when definition
> >> order is not available.  So I'd go with the latter.
> >
> >
> > So in Python space the options are either:
> >
> >if some_class.__definition_order__ is not None:
> >
> > or
> >
> >if getattr(some_class, '__definition_order__', None) is not None:
> >
> > ?
> >
> > Seems like always defined would be easier.
>
> Certainly it's easier to use if you need the definition order.
> However, I expect it wouldn't be used often enough that that would
> make a big difference.  Furthermore, if it's always there then it will
> always show up when you dir(SomeClass) or look at SomeClass.__dict__.
> People would see that on every class, whether it actually provided
> definition order or not.  I'm not sure that is as helpful as only
> having the attribute around when order is defined.
>
> This got me thinking.  The attribute should be a class-only attribute
> (i.e. a property on type) like __name__ is.  That would keep it from
> showing up on instance lookups and on every vars(obj).
>
> The big thing for me, though, is that optionally having the attribute
> accommodates Python implementations that can't (or don't) preserve
> definition order.  They don't have to worry about adding a dummy
> attribute to every class just for the sake of complying with the spec.
>  It also means the implementation for dynamic types like Nick
> mentioned don't necesarily need to be touched.  The more I think about
> it the more the optionally set attribute approach is the way to go.

My experience with maybe set, maybe not attributes for modules is that
they're *always* a PITA to deal with and just not worth the hassle.

Better to just expose it as a read-only attribute on class objects (that
isn't accessible through instances) and set it to None on construction if
order info is not available. This will also block accidental inheritance of
the attribute from an ordered base class.

A new keyword-only argument for the dynamic type construction APIs in the
"types" module would also be appropriate, and would allow the creation of
ordered classes even if the implementation used unordered namespaces for
class syntax.

Cheers,
Nick.

>
> -eric
> ___
> Python-Dev mailing list
> [email protected]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

2013-06-27 Thread Ben Finney 
Antoine Pitrou  writes:

> I don't always find it easy to summarize a function in one line.

Difficulty in coming up with an accurate one-line summary of the intent
of a function is a code smell: the function probably needs to be
simplified so it is easier to describe accurately.

This is, IMO, one of the primary benefits of having a convention of
expecting a one-line summary for every function (and module and class).

-- 
 \  “Courage is not the absence of fear, but the decision that |
  `\ something else is more important than fear.” —Ambrose Redmoon |
_o__)  |
Ben Finney

___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com