Re: [Python-Dev] PEP 257 and __init__

2016-01-04 Thread Facundo Batista 
On Mon, Jan 4, 2016 at 4:49 AM, Nick Coghlan  wrote:

> When some of the default settings for the pep8 utility became a
> problem, I was able to talk to the developers and persuade them to
> tune their defaults to be more in line with the actual PEP text, and
> keep their extensions to optional settings.

In that spirit, I opened an issue [0] in the pep257 project to be able
to configure that and bypass the default behaviour, so the tool can be
used in a wider set of projects.

Thanks everybody for all the info.

Regards,

[0] https://github.com/GreenSteam/pep257/issues/171

-- 
.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
Twitter: @facundobatista
___
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 257 and __init__

2016-01-04 Thread Guido van Rossum 
On Sun, Jan 3, 2016 at 11:49 PM, Nick Coghlan  wrote:

> On 4 January 2016 at 17:01, Terry Reedy  wrote:
> > Ask the PSF/pypi people to either prohibit such names or require a
> > disclaimer of some sort.  They are inherently confusing: "I took a look
> at
> > pep008" does not mean that one even looked at the PEP.  Even when the
> > context makes clear that the referent is the module, there is confusion
> as
> > to its authoritativeness.  That Facudo would post here about the module's
> > output illustrates that. To me, the name copying violates our informal
> > trademark within Pythonland on 'PEP'.
>
> I don't think that's the right answer, as opinionated tools do serve a
> useful purpose in preventing bikeshedding during code review (people
> *expect* computers to be annoyingly pedantic, which frees up the human
> reviewers to focus on higher level concerns). As projects evolve over
> time, they may develop their own tweaks and customisations in their
> style guide and switch to a more configurable tool, or they may not.
>
> When some of the default settings for the pep8 utility became a
> problem, I was able to talk to the developers and persuade them to
> tune their defaults to be more in line with the actual PEP text, and
> keep their extensions to optional settings.
>
> A similar approach may work for PEP 257, by clarifying which aspects
> tools should be leaving to human judgement (beyond the question of
> whether or not to opt in to following PEP 257 at all - it's far less
> universal than PEP 8).
>

Hm. I don't want the PSF to flex its muscles about trademarks, but I still
don't like that there are tools named after PEPs (especially since the
tools are not written by the same people that wrote the PEPs). I still
recall the first time someone emailed me about a "pep8" issue (I had never
heard of the tool by that name) and I was thoroughly confused for a long
time.

That said I expect it's too late to try and get the pep8 authors to rename
it; but I filed an issue with the pep257 project and they are going to
change the name: https://github.com/GreenSteam/pep257/issues/172 .

FWIW I am happy that the tools exist! They can be very useful and I use
pep8 myself. But I always let it know who's boss. :-)

-- 
--Guido van Rossum (python.org/~guido)
___
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 257 and __init__

2016-01-03 Thread Guido van Rossum 
On Tue, Dec 29, 2015 at 1:03 PM, Facundo Batista 
wrote:

> On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert 
> wrote:
>
> > Isn't the same thing true for every special method? There are lots of
> classes where __add___ just says "a.__add__(b) = a + b" or (better
> following the PEP) "Return self + value." But, in the rare case where the
> semantics of "a + b" are a little tricky (think of "a / b" for
> pathlib.Path), where else could you put it but __add__?
> >
> > Similarly, for most classes, there's only one of __init__ or __new__,
> and the construction/initialization semantics are simple enough to describe
> in one line of the class docstring--but when things are more complicated
> and need to be documented, where else would you put it?
>
> Yeap. Note that I'm ok to include a docstring when the actual
> behaviour would deviate from the expected one as per Reference Docs.
> My point is to not make it mandatory.
>
>
> > I usually just don't bother. You can violate PEP 257 when it makes
> sense, just like PEP 8. They're just guidelines, not iron-clad rules.
>
> Yeap, but pep257 (the tool [0]) complains for __init__, and wanted to
> know how serious was it.
>
>
> [0] https://pypi.python.org/pypi/pep257


That is the tool's fault. I personally hate with a vengeance that there are
tools named after style guide PEPs that claim to enforce the guidelines
from those PEPs. The tools' rigidity and simplicity reflects badly on the
PEPs, which try hard not to be rigid or simplistic.

-- 
--Guido van Rossum (python.org/~guido)
___
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 257 and __init__

2016-01-03 Thread Nick Coghlan 
On 4 January 2016 at 17:01, Terry Reedy  wrote:
> Ask the PSF/pypi people to either prohibit such names or require a
> disclaimer of some sort.  They are inherently confusing: "I took a look at
> pep008" does not mean that one even looked at the PEP.  Even when the
> context makes clear that the referent is the module, there is confusion as
> to its authoritativeness.  That Facudo would post here about the module's
> output illustrates that. To me, the name copying violates our informal
> trademark within Pythonland on 'PEP'.

I don't think that's the right answer, as opinionated tools do serve a
useful purpose in preventing bikeshedding during code review (people
*expect* computers to be annoyingly pedantic, which frees up the human
reviewers to focus on higher level concerns). As projects evolve over
time, they may develop their own tweaks and customisations in their
style guide and switch to a more configurable tool, or they may not.

When some of the default settings for the pep8 utility became a
problem, I was able to talk to the developers and persuade them to
tune their defaults to be more in line with the actual PEP text, and
keep their extensions to optional settings.

A similar approach may work for PEP 257, by clarifying which aspects
tools should be leaving to human judgement (beyond the question of
whether or not to opt in to following PEP 257 at all - it's far less
universal than PEP 8).

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 257 and __init__

2016-01-03 Thread Terry Reedy 

On 1/3/2016 6:21 PM, Guido van Rossum wrote:

On Tue, Dec 29, 2015 at 1:03 PM, Facundo Batista
> wrote:

On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert > wrote:

> Isn't the same thing true for every special method? There are lots of classes where __add___ just says 
"a.__add__(b) = a + b" or (better following the PEP) "Return self + value." But, in the rare case 
where the semantics of "a + b" are a little tricky (think of "a / b" for pathlib.Path), where else 
could you put it but __add__?
>
> Similarly, for most classes, there's only one of __init__ or __new__, and 
the construction/initialization semantics are simple enough to describe in one 
line of the class docstring--but when things are more complicated and need to be 
documented, where else would you put it?

Yeap. Note that I'm ok to include a docstring when the actual
behaviour would deviate from the expected one as per Reference Docs.
My point is to not make it mandatory.


> I usually just don't bother. You can violate PEP 257 when it makes sense, 
just like PEP 8. They're just guidelines, not iron-clad rules.

Yeap, but pep257 (the tool [0]) complains for __init__, and wanted to
know how serious was it.


[0] https://pypi.python.org/pypi/pep257


That is the tool's fault. I personally hate with a vengeance that there
are tools named after style guide PEPs that claim to enforce the
guidelines from those PEPs. The tools' rigidity and simplicity reflects
badly on the PEPs, which try hard not to be rigid or simplistic.


Ask the PSF/pypi people to either prohibit such names or require a 
disclaimer of some sort.  They are inherently confusing: "I took a look 
at pep008" does not mean that one even looked at the PEP.  Even when the 
context makes clear that the referent is the module, there is confusion 
as to its authoritativeness.  That Facudo would post here about the 
module's output illustrates that. To me, the name copying violates our 
informal trademark within Pythonland on 'PEP'.


--
Terry Jan Reedy


___
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

[Python-Dev] PEP 257 and __init__

2015-12-29 Thread Facundo Batista 
Hola!

(I was doubting in sending this mail to this list or to the normal
one, but as it affects a "style recommendation" we propose for the
whole community, I finally sent it here)

I was reading PEP 257 and it says that all public methods from a class
(including __init__) should have a docstring.

Why __init__?

It's behaviour is well defined (inits the instance), and the
initialization parameters should be described in the class' docstring
itself, right?

Or I am missing something?

Should we remove "__init__" (the class method, *not* the package file)
as to require docstrings in the PEP?

Thanks!

-- 
.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
Twitter: @facundobatista
___
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 257 and __init__

2015-12-29 Thread Andrew Barnert via Python-Dev 
On Dec 29, 2015, at 13:03, Facundo Batista  wrote:
> 
>> On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert  wrote:

>> I usually just don't bother. You can violate PEP 257 when it makes sense, 
>> just like PEP 8. They're just guidelines, not iron-clad rules.
> 
> Yeap, but pep257 (the tool [0]) complains for __init__, and wanted to
> know how serious was it.

Of course. It's telling you that you're not following the standard, which is 
correct. It's also expected in this case, and if you think you have a good 
reason for breaking from the standard, that's perfectly fine. You probably want 
to configure the tool to meet your own standards. (I've worked on multiple 
projects that used custom pep8 configurations. I haven't used pep257 as much, 
but I believe I've seen configurations for the slightly different conventions 
of scientific/numerical programming and Django programming, so presumably 
coming up with your own configuration shouldn't be too hard--don't require 
docstrings on __init__, or on all special methods, or only when there no 
__new__, or whatever.)
___
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 257 and __init__

2015-12-29 Thread Ben Finney 
Facundo Batista  writes:

> Note that I'm ok to include a docstring when the actual behaviour
> would deviate from the expected one as per Reference Docs. My point is
> to not make it mandatory.

I disagree with the exception you're making for ‘__init__’. The
parameters to that function (and how the function behaves in response)
should be documented in the docstring, just as for any other function.

> Yeap, but pep257 (the tool [0]) complains for __init__, and wanted to
> know how serious was it.

Omitting a docstring violates PEP 257, regardless which function we're
talking about. So the tool is correct to complain.

-- 
 \ “If we don't believe in freedom of expression for people we |
  `\   despise, we don't believe in it at all.” —Noam Chomsky, |
_o__)   1992-11-25 |
Ben Finney

___
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 257 and __init__

2015-12-29 Thread Fred Drake 
On Tue, Dec 29, 2015 at 1:27 PM, Facundo Batista
 wrote:
> I was reading PEP 257 and it says that all public methods from a class
> (including __init__) should have a docstring.
>
> Why __init__?
>
> It's behaviour is well defined (inits the instance), and the
> initialization parameters should be described in the class' docstring
> itself, right?

__init__ is not always the only constructor for a class; each
constructor's arguments should be documented as part of the
constructor.  The class docstring should provide summary information
for the class as a whole.

I can also imagine cases where the __init__ isn't considered public,
though I suspect that's exceedingly rare in practice.  (Can't think of
a case I've actually run across like that.)

> Should we remove "__init__" (the class method, *not* the package file)
> as to require docstrings in the PEP?

I don't think so.  The advice seems sound to me.


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
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 257 and __init__

2015-12-29 Thread Facundo Batista 
On Tue, Dec 29, 2015 at 4:38 PM, Andrew Barnert  wrote:

> Isn't the same thing true for every special method? There are lots of classes 
> where __add___ just says "a.__add__(b) = a + b" or (better following the PEP) 
> "Return self + value." But, in the rare case where the semantics of "a + b" 
> are a little tricky (think of "a / b" for pathlib.Path), where else could you 
> put it but __add__?
>
> Similarly, for most classes, there's only one of __init__ or __new__, and the 
> construction/initialization semantics are simple enough to describe in one 
> line of the class docstring--but when things are more complicated and need to 
> be documented, where else would you put it?

Yeap. Note that I'm ok to include a docstring when the actual
behaviour would deviate from the expected one as per Reference Docs.
My point is to not make it mandatory.


> I usually just don't bother. You can violate PEP 257 when it makes sense, 
> just like PEP 8. They're just guidelines, not iron-clad rules.

Yeap, but pep257 (the tool [0]) complains for __init__, and wanted to
know how serious was it.


[0] https://pypi.python.org/pypi/pep257

-- 
.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
Twitter: @facundobatista
___
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 257 and __init__

2015-12-29 Thread Andrew Barnert via Python-Dev 
On Dec 29, 2015, at 10:27, Facundo Batista  wrote:

> I was reading PEP 257 and it says that all public methods from a class
> (including __init__) should have a docstring.
> 
> Why __init__?
> 
> It's behaviour is well defined (inits the instance), and the
> initialization parameters should be described in the class' docstring
> itself, right?

Isn't the same thing true for every special method? There are lots of classes 
where __add___ just says "a.__add__(b) = a + b" or (better following the PEP) 
"Return self + value." But, in the rare case where the semantics of "a + b" are 
a little tricky (think of "a / b" for pathlib.Path), where else could you put 
it but __add__?

Similarly, for most classes, there's only one of __init__ or __new__, and the 
construction/initialization semantics are simple enough to describe in one line 
of the class docstring--but when things are more complicated and need to be 
documented, where else would you put it?

Meanwhile, the useless one-liner docstrings for these methods aren't usually a 
problem except in trivial classes--and in trivial classes, I usually just don't 
bother. You can violate PEP 257 when it makes sense, just like PEP 8. They're 
just guidelines, not iron-clad rules.

Unless you're working on a project that insists that we must follow those 
guidelines, usually for some good reason like having lots of devs who are more 
experienced in other languages and whose instinctive "taste" isn't sufficiently 
Pythonic. And for that use case, keeping the rules as simple as possible is 
probably helpful. Better to have one wasted line in every file than to have an 
extra rule that all those JS developers have to remember when they're working 
in Python.
___
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 257 and __init__

2015-12-29 Thread Terry Reedy 

On 12/29/2015 2:40 PM, Fred Drake wrote:

On Tue, Dec 29, 2015 at 1:27 PM, Facundo Batista
 wrote:

I was reading PEP 257 and it says that all public methods from a class
(including __init__) should have a docstring.

Why __init__?

It's behaviour is well defined (inits the instance), and the
initialization parameters should be described in the class' docstring
itself, right?


__init__ is not always the only constructor for a class; each
constructor's arguments should be documented as part of the
constructor.


I agree.  >>> help(Someclass) first gives the class docstring, which 
should explain what the class is about, and then each method, with 
signature and docstring.  The explanation of signatures for __new__, 
__init__, and any other constructor methods should follow the name and 
signature of the method.


--
Terry Jan Reedy

___
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