[Python-ideas] Conventions for Python code documentation (was: PEP 484 (Type Hints) -- first draft round)

Guido van Rossum guido at python.org
Tue Jan 20 18:25:05 CET 2015

On Tue, Jan 20, 2015 at 8:28 AM, Chris Barker <chris.barker at noaa.gov> wrote:

> On Mon, Jan 19, 2015 at 8:42 PM, Guido van Rossum <guido at python.org>
> wrote:
>> On Mon, Jan 19, 2015 at 5:04 PM, Chris Barker - NOAA Federal <
>> chris.barker at noaa.gov> wrote:
>>> I always teach that the @ syntax is a decoration, not a decorator,
>>> whereas a decorator is a function that takes a function and returns another
>>> function ( usually a customized version of the passed in function). This
>>> distinction between decorators and decoration syntax keeps the door open to
>>> do just about anything with decorations, but am I the only one that thinks
>>> it's a bad idea to have it be for "any old thing we want to hang off a
>>> function"?
>> I think you're the only one who makes this distinction.
> No, I'm not -- take a look at any number of tutorial sites, and answers
> for newbies on SO, etc. I used to teach decorators without making the
> distinction, and got a lot of confused students. maybe the distinction is
> only useful for pedagogical purposes, but I introduced it here 'cause it's
> a bit harder to talk about when a "decorator" can be either a function the
> behaves a certain way or the @something line in the code.

It's a fair cop.

> In common use "decorator" is used to describe both the syntax and the
>> function invoked by the syntax. "Decoration" is never (well, very rarely)
>> used. And calling any function that takes a function and returns one a
>> decorator feels overreaching -- I'd only call it a decorator if it is
>> intended to use with the decorator syntax.
> sure -- I'm having a hard time coming up with the word s to describe what
> I"m talking about as  "proper" decorator. The truth is, you can put any
> callable that takes at least one argument after that @. And I'm not
> suggesting that python should enforce anything in particular about that.
> What I am suggesting is that we should not officially suggest that you
> should use a decorator for any old thing that doesn't fit the usual sprit
> of decorators.

Agreed. The 99% case is that a decorator returns a function that (with some
qualifications) calls the decorated function.

> A decorator that simply adds stuff to the docstring feels pretty ugly to
> me, particular if it goes beyond docs to specifying something important
> about the typing, etc.

This sounds totally fine to me, honestly.

> Hard to draw a line there, but I  think we should keep the spirit of
> decorators in mind.
> But enough said.


--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/7919e9d5/attachment.html>

More information about the Python-ideas mailing list