[New-bugs-announce] [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 at python
components: Documentation
files: deco-docos.patch
keywords: patch
messages: 261888
nosy: Rosuav, docs at 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 <report at bugs.python.org>
<http://bugs.python.org/issue26576>
_______________________________________