(original) (raw)

> Here's the proposed text (wordsmithing suggestions in the PR please):

\>
\> +Decorators
\> +----------
\> +
\> +Decorators can modify the types of the functions or classes they
\> +decorate. Use the \`\`decorated\_type\`\` decorator to declare the type of
\> +the resulting item after all other decorators have been applied::
\> +
\> + from typing import ContextManager, Iterator, decorated\_type
\> + from contextlib import contextmanager
\> +
\> + class DatabaseSession: ...
\> +
\> + @decorated\_type(Callable\[\[str\], ContextManager\[DatabaseSession\]\])
\> + @contextmanager
\> + def session(url: str) -> Iterator\[DatabaseSession\]:
\> + s = DatabaseSession(url)
\> + try:
\> + yield s
\> + finally:
\> + s.close()
\> +
\> +The argument of \`\`decorated\_type\`\` is a type annotation on the name
\> +being declared (\`\`session\`\`, in the example above). If you have
\> +multiple decorators, \`\`decorated\_type\`\` must be topmost. The
\> +\`\`decorated\_type\`\` decorator is invalid on a function declaration that
\> +is also decorated with \`\`overload\`\`, but you can annotate the
\> +implementation of the overload series with \`\`decorated\_type\`\`.
\> +
\>

Would \_\_annotations\_\_ be set by the decorator? To me, not setting them
would seem weird, but cases where the result is not a function could
be weird. I also don't see a mention of this only working in stubs.

I like Jukka's version, as it has a clear distinction between
functions and other attributes. But that might require a language
change to provide \_\_annotations\_\_ in a clean manner? Maybe that
language change would be useful elsewhere.