[issue26576] Tweak wording of decorator docos

[Berker Peksag]

Berker Peksag added the comment:

Thanks for the patch, Chris. I've only changed `func` to ``func`` (we don't use 
single backtick in reST.)

--
nosy: +berker.peksag
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
type:  -> enhancement
versions: +Python 3.5, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Roundup Robot]

Roundup Robot added the comment:

New changeset e0f9f8be7963 by Berker Peksag in branch '3.5':
Issue #26576: Clarify that the @deco syntax is not always an equivalent of f = 
deco(f)
https://hg.python.org/cpython/rev/e0f9f8be7963

New changeset 08359651815e by Berker Peksag in branch 'default':
Issue #26576: Merge from 3.5
https://hg.python.org/cpython/rev/08359651815e

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Terry J. Reedy]

Terry J. Reedy added the comment:

Guido, the discrepancy between the decorator doc's 'equivalent code' and 
actual, optimized, behavior with regard to skipping an intermediate binding of 
the function to the name came up soon after decorators were added.  I cannot 
find the issue, but as I remember, you said at the time that the doc's 
'equivalent' code was good enough, and perhaps that you did not want to force 
the optimization on other implementations (not sure of this latter).

This issue has come up often enough on Python list and SO that many think that 
the actual behavior should be documented.  But should it be documented as a 
guaranteed language feature or as just an optional optimization?

--
nosy: +gvanrossum, terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Georg Brandl]

Georg Brandl added the comment:

(Also, toggled your "is committer" bit so you get the Python logo next to your 
name.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

Chris Angelico added the comment:

The remaining difference that's actually of use, perhaps. But the decoration 
itself happens before the name is bound. It's impossible to describe in Python 
code; but it can be probed - you can monkeypatch a class using a decorator:

def monkeypatch(cls):
orig = globals()[cls.__name__] # Undocumented magic
print("Monkeypatch",id(cls),"into",id(orig))
for attr in dir(cls):
if not attr.startswith("_"):
setattr(orig,attr,getattr(cls,attr))
return orig

class Foo:
def method1(self):
print("I am method 1")

print("Foo is currently",id(Foo))
some_object = Foo()

@monkeypatch
class Foo:
def method2(self):
print("I am method 2")

print("Foo is now",id(Foo))

some_object.method1()
some_object.method2()



Is this undocumented behaviour? Should it be supported? It works on every 
Python I've tried it on (CPython 2.7 and 3.6, PyPy2 and PyPy3, Jython, and 
MicroPython), but it's not something I'd depend on in production code unless 
it's documented.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

Chris Angelico added the comment:

I may be a committer, but I don't push to cpython - just to the peps. But sure, 
pretty little logo :)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

New submission from Chris Angelico:

The official documentation declares an unambiguous equivalence which is not 
true in some corner cases:

@deco
def f(x): pass

is not quite the same as

def f(x): pass
f = deco(f)

as the name is never bound to the undecorated function. This is what makes 
@property and @prop.setter work; otherwise, the undecorated setter function 
would overwrite the property, and the decoration would fail. Attached patch 
loosens the wording slightly to "broadly equivalent"; this permits corner cases 
to vary from the equivalence, while still retaining its simplicity for the 99% 
of cases where it's correct. (Think of explaining "yield from iter" as "for x 
in iter: yield x" and you have a similar near-equivalence.)

Also, class decorators aren't required to return classes. Text removed saying 
that they do.

--
assignee: docs@python
components: Documentation
files: deco-docos.patch
keywords: patch
messages: 261888
nosy: Rosuav, docs@python
priority: normal
severity: normal
status: open
title: Tweak wording of decorator docos
Added file: http://bugs.python.org/file42181/deco-docos.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

Chris Angelico added the comment:

Sure - changing it to "roughly". I started with that wording, and then changed 
to "broadly", for reasons which I now can't remember - so they can't have been 
too important. Consistency wins.

--
Added file: http://bugs.python.org/file42214/deco-docos.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Raymond Hettinger]

Raymond Hettinger added the comment:

Elsewhere we use "roughly equivalent to" instead of "broadly equivalent to".  
The latter seems a little bit off the mark.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

Chris Angelico added the comment:

Sounds good to me. Replacement patch.

--
Added file: http://bugs.python.org/file42182/deco-docos.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Chris Angelico]

Chris Angelico added the comment:

Question: Is it worth having an explanation somewhere of exactly what *does* 
happen? To what extent is it guaranteed by the language?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Georg Brandl]

Georg Brandl added the comment:

The patch is definitely an improvement.

What about a remark like ", except that `deco` is evaluated before the function 
`f` is created"?  That should cover the remaining difference.

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26576] Tweak wording of decorator docos

[Georg Brandl]

Georg Brandl added the comment:

That is definitely supported.  Whether it's actually useful to document, I'm 
not sure.

"except that the original function is not temporarily bound to the name `f`" 
could work.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com