[Python-checkins] peps: Relax constraints on @overload. It may occur in modules if followed by a

[guido.van.rossum]

https://hg.python.org/peps/rev/2ce4a999d01c
changeset:   6265:2ce4a999d01c
user:        Guido van Rossum <guido at python.org>
date:        Mon Mar 21 13:51:08 2016 -0700
summary:
  Relax constraints on @overload. It may occur in modules if followed by a non- at overload version.

files:
  pep-0484.txt |  59 +++++++++++++++++++++++++++++++--------
  1 files changed, 46 insertions(+), 13 deletions(-)


diff --git a/pep-0484.txt b/pep-0484.txt
--- a/pep-0484.txt
+++ b/pep-0484.txt
@@ -1020,7 +1020,7 @@
 * Modules that use annotations for other purposes
 
 Stub files have the same syntax as regular Python modules.  There is one
-feature of the ``typing`` module that may only be used in stub files:
+feature of the ``typing`` module that is different in stub files:
 the ``@overload`` decorator described below.
 
 The type checker should only check function signatures in stub files;
@@ -1047,13 +1047,21 @@
   exported.  (This makes it easier to re-export all objects from a
   given module that may vary by Python version.)
 
-Function overloading
---------------------
+* Stub files may be incomplete. To make type checkers aware of this, the file
+  can contain the following code::
 
-The ``@overload`` decorator allows describing functions that support
-multiple different combinations of argument types.  This pattern is
-used frequently in builtin modules and types.  For example, the
-``__getitem__()`` method of the ``bytes`` type can be described as
+    def __getattr__(name) -> Any: ...
+
+  Any identifier not defined in the stub is therefore assumed to be of type
+  ``Any``.
+
+Function/method overloading
+---------------------------
+
+The ``@overload`` decorator allows describing functions and methods
+that support multiple different combinations of argument types.  This
+pattern is used frequently in builtin modules and types.  For example,
+the ``__getitem__()`` method of the ``bytes`` type can be described as
 follows::
 
   from typing import overload
@@ -1101,18 +1109,43 @@
           iter1: Iterable[T1],
           iter2: Iterable[T2]) -> Iterable[Tuple[T1, T2]]: ...
 
-The ``@overload`` decorator may only be used in stub files.  While it
-would be possible to provide a multiple dispatch implementation using
-this syntax, its implementation would require using
-``sys._getframe()``, which is frowned upon.  Also, designing and
+Uses of the ``@overload`` decorator as shown above are suitable for
+stub files.  In regular modules, a series of ``@overload``-decorated
+definitions must be followed by exactly one
+non-``@overload``-decorated definition (for the same function/method).
+The ``@overload``-decorated definitions are for the benefit of the
+type checker only, since they will be overwritten by the
+non-``@overload``-decorated definition, while the latter is used at
+runtime but should be ignored by a type checker.  At runtime, calling
+a ``@overload``-decorated function directly will raise
+``NotImplementedError``.  Here's an example of a non-stub overload
+that can't easily be expressed using a union or a type variable::
+
+  @overload
+  def utf8(value: None) -> None:
+      pass
+  @overload
+  def utf8(value: bytes) -> bytes:
+      pass
+  @overload
+  def utf8(value: unicode) -> bytes:
+      pass
+  def utf8(value):
+      <actual implementation>
+
+NOTE: While it would be possible to provide a multiple dispatch
+implementation using this syntax, its implementation would require
+using ``sys._getframe()``, which is frowned upon.  Also, designing and
 implementing an efficient multiple dispatch mechanism is hard, which
 is why previous attempts were abandoned in favor of
 ``functools.singledispatch()``.  (See PEP 443, especially its section
 "Alternative approaches".)  In the future we may come up with a
 satisfactory multiple dispatch design, but we don't want such a design
 to be constrained by the overloading syntax defined for type hints in
-stub files.  In the meantime, using the ``@overload`` decorator or
-calling ``overload()`` directly raises ``RuntimeError``.
+stub files.  It is also possible that both features will develop
+independent from each other (since overloading in the type checker
+has different use cases and requirements than multiple dispatch
+at runtime -- e.g. the latter is unlikely to support generic types).
 
 A constrained ``TypeVar`` type can often be used instead of using the
 ``@overload`` decorator.  For example, the definitions of ``concat1``

-- 
Repository URL: https://hg.python.org/peps