[WIP] PEP 484: Describe a way of annotating decorated declarations

pep-0484.txt

@@ -276,6 +276,34 @@ implemented by deferring to ``isinstance(x, collections.abc.Callable)``.
 However, ``isinstance(x, typing.Callable[...])`` is not supported.
 
 
+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``.
+
 Generics
 --------