[Python-checkins] peps: * deferred the annotation-driven form

[lukasz.langa]

http://hg.python.org/peps/rev/340e90cfa121
changeset:   4906:340e90cfa121
user:        Łukasz Langa <lukasz at langa.pl>
date:        Thu May 23 22:15:26 2013 +0200
summary:
  * deferred the annotation-driven form

* clarified that register() returns an undecorated function

files:
  pep-0443.txt |  42 ++++++++++++++++++++++++++-------------
  1 files changed, 28 insertions(+), 14 deletions(-)


diff --git a/pep-0443.txt b/pep-0443.txt
--- a/pep-0443.txt
+++ b/pep-0443.txt
@@ -96,7 +96,21 @@
   ...
   >>> fun.register(type(None), nothing)
 
-When called, the function dispatches on the first argument::
+The ``register()`` attribute returns the undecorated function which
+enables decorator stacking, as well as creating unit tests for each
+variant independently::
+
+  >>> @fun.register(float)
+  ... @fun.register(Decimal)
+  ... def fun_num(arg, verbose=False):
+  ...     if verbose:
+  ...         print("Half of your number:", end=" ")
+  ...     print(arg / 2)
+  ...
+  >>> fun_num is fun
+  False
+
+When called, the generic function dispatches on the first argument::
 
   >>> fun("Hello, world.")
   Hello, world.
@@ -112,6 +126,8 @@
   3 spam
   >>> fun(None)
   Nothing.
+  >>> fun_num(1.23)
+  0.615
 
 The proposed API is intentionally limited and opinionated, as to ensure
 it is easy to explain and use, as well as to maintain consistency with
@@ -123,21 +139,19 @@
 
 The functionality described in this PEP is already implemented in the
 ``pkgutil`` standard library module as ``simplegeneric``. Because this
-implementation is mature, the goal is to move it largely as-is. Several
-open issues remain:
+implementation is mature, the goal is to move it largely as-is.
 
-* the current implementation relies on ``__mro__`` alone, making it
-  incompatible with Abstract Base Classes'
-  ``register()``/``unregister()`` functionality. A possible solution has
-  been proposed by PJE on the original issue for exposing
-  ``pkgutil.simplegeneric`` as part of the ``functools`` API
-  [#issue-5135]_.
+The current implementation relies on ``__mro__`` alone, it will be made
+compatible with Abstract Base Classes' ``register()``/``unregister()``
+functionality. A possible solution has been proposed by PJE on the
+original issue for exposing ``pkgutil.simplegeneric`` as part of the
+``functools`` API [#issue-5135]_.
 
-* the dispatch type is currently specified as a decorator argument. The
-  implementation could allow a form using argument annotations. This
-  usage pattern is out of scope for the standard library [#pep-0008]_.
-  However, whether this registration form would be acceptable for
-  general usage, is up to debate.
+The dispatch type is specified as a decorator argument. An alternative
+form using function annotations has been considered but its inclusion
+has been deferred. As of May 2013, this usage pattern is out of scope
+for the standard library [#pep-0008]_ and the best practices for
+annotation usage are still debated.
 
 Based on the current ``pkgutil.simplegeneric`` implementation and
 following the convention on registering virtual subclasses on Abstract

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