Add reference implementation for PEP 443

PEP accepted: http://mail.python.org/pipermail/python-dev/2013-June/126734.html

6 files changed, 613 insertions, 54 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index d8fcf0f..5ee07a7 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -6,6 +6,7 @@
 .. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
 .. moduleauthor:: Raymond Hettinger <python@rcn.com>
 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
+.. moduleauthor:: Łukasz Langa <lukasz@langa.pl>
 .. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
 
 **Source code:** :source:`Lib/functools.py`
@@ -186,6 +187,115 @@ The :mod:`functools` module defines the following functions:
    *sequence* contains only one item, the first item is returned.
 
 
+.. decorator:: singledispatch(default)
+
+   Transforms a function into a single-dispatch generic function.  A **generic
+   function** is composed of multiple functions implementing the same operation
+   for different types. Which implementation should be used during a call is
+   determined by the dispatch algorithm.  When the implementation is chosen
+   based on the type of a single argument, this is known as **single
+   dispatch**.
+
+   To define a generic function, decorate it with the ``@singledispatch``
+   decorator. Note that the dispatch happens on the type of the first argument,
+   create your function accordingly::
+
+     >>> from functools import singledispatch
+     >>> @singledispatch
+     ... def fun(arg, verbose=False):
+     ...     if verbose:
+     ...         print("Let me just say,", end=" ")
+     ...     print(arg)
+
+   To add overloaded implementations to the function, use the :func:`register`
+   attribute of the generic function.  It is a decorator, taking a type
+   parameter and decorating a function implementing the operation for that
+   type::
+
+     >>> @fun.register(int)
+     ... def _(arg, verbose=False):
+     ...     if verbose:
+     ...         print("Strength in numbers, eh?", end=" ")
+     ...     print(arg)
+     ...
+     >>> @fun.register(list)
+     ... def _(arg, verbose=False):
+     ...     if verbose:
+     ...         print("Enumerate this:")
+     ...     for i, elem in enumerate(arg):
+     ...         print(i, elem)
+
+   To enable registering lambdas and pre-existing functions, the
+   :func:`register` attribute can be used in a functional form::
+
+     >>> def nothing(arg, verbose=False):
+     ...     print("Nothing.")
+     ...
+     >>> fun.register(type(None), nothing)
+
+   The :func:`register` attribute returns the undecorated function which
+   enables decorator stacking, pickling, 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 type of the first
+   argument::
+
+     >>> fun("Hello, world.")
+     Hello, world.
+     >>> fun("test.", verbose=True)
+     Let me just say, test.
+     >>> fun(42, verbose=True)
+     Strength in numbers, eh? 42
+     >>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)
+     Enumerate this:
+     0 spam
+     1 spam
+     2 eggs
+     3 spam
+     >>> fun(None)
+     Nothing.
+     >>> fun(1.23)
+     0.615
+
+   Where there is no registered implementation for a specific type, its
+   method resolution order is used to find a more generic implementation.
+   The original function decorated with ``@singledispatch`` is registered
+   for the base ``object`` type, which means it is used if no better
+   implementation is found.
+
+   To check which implementation will the generic function choose for
+   a given type, use the ``dispatch()`` attribute::
+
+     >>> fun.dispatch(float)
+     <function fun_num at 0x1035a2840>
+     >>> fun.dispatch(dict)    # note: default implementation
+     <function fun at 0x103fe0000>
+
+   To access all registered implementations, use the read-only ``registry``
+   attribute::
+
+    >>> fun.registry.keys()
+    dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
+              <class 'decimal.Decimal'>, <class 'list'>,
+              <class 'float'>])
+    >>> fun.registry[float]
+    <function fun_num at 0x1035a2840>
+    >>> fun.registry[object]
+    <function fun at 0x103fe0000>
+
+   .. versionadded:: 3.4
+
+
 .. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
 
    Update a *wrapper* function to look like the *wrapped* function. The optional
diff --git a/Lib/functools.py b/Lib/functools.py
index fa11d2f..67af370 100644
--- a/Lib/functools.py
+++ b/Lib/functools.py
@@ -3,19 +3,24 @@
 # Python module wrapper for _functools C module
 # to allow utilities written in Python to be added
 # to the functools module.
-# Written by Nick Coghlan <ncoghlan at gmail.com>
-# and Raymond Hettinger <python at rcn.com>
-#   Copyright (C) 2006-2010 Python Software Foundation.
+# Written by Nick Coghlan <ncoghlan at gmail.com>,
+# Raymond Hettinger <python at rcn.com>,
+# and Łukasz Langa <lukasz at langa.pl>.
+#   Copyright (C) 2006-2013 Python Software Foundation.
 # See C source code for _functools credits/copyright
 
 __all__ = ['update_wrapper', 'wraps', 'WRAPPER_ASSIGNMENTS', 'WRAPPER_UPDATES',
-           'total_ordering', 'cmp_to_key', 'lru_cache', 'reduce', 'partial']
+           'total_ordering', 'cmp_to_key', 'lru_cache', 'reduce', 'partial',
+           'singledispatch']
 
 try:
     from _functools import reduce
 except ImportError:
     pass
+from abc import get_cache_token
 from collections import namedtuple
+from types import MappingProxyType
+from weakref import WeakKeyDictionary
 try:
     from _thread import RLock
 except:
@@ -354,3 +359,118 @@ def lru_cache(maxsize=128, typed=False):
         return update_wrapper(wrapper, user_function)
 
     return decorating_function
+
+
+################################################################################
+### singledispatch() - single-dispatch generic function decorator
+################################################################################
+
+def _compose_mro(cls, haystack):
+    """Calculates the MRO for a given class `cls`, including relevant abstract
+    base classes from `haystack`.
+
+    """
+    bases = set(cls.__mro__)
+    mro = list(cls.__mro__)
+    for needle in haystack:
+        if (needle in bases or not hasattr(needle, '__mro__')
+                            or not issubclass(cls, needle)):
+            continue   # either present in the __mro__ already or unrelated
+        for index, base in enumerate(mro):
+            if not issubclass(base, needle):
+                break
+        if base in bases and not issubclass(needle, base):
+            # Conflict resolution: put classes present in __mro__ and their
+            # subclasses first. See test_mro_conflicts() in test_functools.py
+            # for examples.
+            index += 1
+        mro.insert(index, needle)
+    return mro
+
+def _find_impl(cls, registry):
+    """Returns the best matching implementation for the given class `cls` in
+    `registry`. Where there is no registered implementation for a specific
+    type, its method resolution order is used to find a more generic
+    implementation.
+
+    Note: if `registry` does not contain an implementation for the base
+    `object` type, this function may return None.
+
+    """
+    mro = _compose_mro(cls, registry.keys())
+    match = None
+    for t in mro:
+        if match is not None:
+            # If `match` is an ABC but there is another unrelated, equally
+            # matching ABC. Refuse the temptation to guess.
+            if (t in registry and not issubclass(match, t)
+                              and match not in cls.__mro__):
+                raise RuntimeError("Ambiguous dispatch: {} or {}".format(
+                    match, t))
+            break
+        if t in registry:
+            match = t
+    return registry.get(match)
+
+def singledispatch(func):
+    """Single-dispatch generic function decorator.
+
+    Transforms a function into a generic function, which can have different
+    behaviours depending upon the type of its first argument. The decorated
+    function acts as the default implementation, and additional
+    implementations can be registered using the 'register()' attribute of
+    the generic function.
+
+    """
+    registry = {}
+    dispatch_cache = WeakKeyDictionary()
+    cache_token = None
+
+    def dispatch(typ):
+        """generic_func.dispatch(type) -> <function implementation>
+
+        Runs the dispatch algorithm to return the best available implementation
+        for the given `type` registered on `generic_func`.
+
+        """
+        nonlocal cache_token
+        if cache_token is not None:
+            current_token = get_cache_token()
+            if cache_token != current_token:
+                dispatch_cache.clear()
+                cache_token = current_token
+        try:
+            impl = dispatch_cache[typ]
+        except KeyError:
+            try:
+                impl = registry[typ]
+            except KeyError:
+                impl = _find_impl(typ, registry)
+            dispatch_cache[typ] = impl
+        return impl
+
+    def register(typ, func=None):
+        """generic_func.register(type, func) -> func
+
+        Registers a new implementation for the given `type` on a `generic_func`.
+
+        """
+        nonlocal cache_token
+        if func is None:
+            return lambda f: register(typ, f)
+        registry[typ] = func
+        if cache_token is None and hasattr(typ, '__abstractmethods__'):
+            cache_token = get_cache_token()
+        dispatch_cache.clear()
+        return func
+
+    def wrapper(*args, **kw):
+        return dispatch(args[0].__class__)(*args, **kw)
+
+    registry[object] = func
+    wrapper.register = register
+    wrapper.dispatch = dispatch
+    wrapper.registry = MappingProxyType(registry)
+    wrapper._clear_cache = dispatch_cache.clear
+    update_wrapper(wrapper, func)
+    return wrapper
diff --git a/Lib/pkgutil.py b/Lib/pkgutil.py
index 1901a5b..d2a6f1e 100644
--- a/Lib/pkgutil.py
+++ b/Lib/pkgutil.py
@@ -1,12 +1,13 @@
 """Utilities to support packages."""
 
-import os
-import sys
-import importlib
+from functools import singledispatch as simplegeneric
 import imp
+import importlib
+import os
 import os.path
-from warnings import warn
+import sys
 from types import ModuleType
+from warnings import warn
 
 __all__ = [
     'get_importer', 'iter_importers', 'get_loader', 'find_loader',
@@ -27,46 +28,6 @@ def read_code(stream):
     return marshal.load(stream)
 
 
-def simplegeneric(func):
-    """Make a trivial single-dispatch generic function"""
-    registry = {}
-    def wrapper(*args, **kw):
-        ob = args[0]
-        try:
-            cls = ob.__class__
-        except AttributeError:
-            cls = type(ob)
-        try:
-            mro = cls.__mro__
-        except AttributeError:
-            try:
-                class cls(cls, object):
-                    pass
-                mro = cls.__mro__[1:]
-            except TypeError:
-                mro = object,   # must be an ExtensionClass or some such  :(
-        for t in mro:
-            if t in registry:
-                return registry[t](*args, **kw)
-        else:
-            return func(*args, **kw)
-    try:
-        wrapper.__name__ = func.__name__
-    except (TypeError, AttributeError):
-        pass    # Python 2.3 doesn't allow functions to be renamed
-
-    def register(typ, func=None):
-        if func is None:
-            return lambda f: register(typ, f)
-        registry[typ] = func
-        return func
-
-    wrapper.__dict__ = func.__dict__
-    wrapper.__doc__ = func.__doc__
-    wrapper.register = register
-    return wrapper
-
-
 def walk_packages(path=None, prefix='', onerror=None):
     """Yields (module_loader, name, ispkg) for all modules recursively
     on path, or, if path is None, all accessible modules.
@@ -148,13 +109,12 @@ def iter_modules(path=None, prefix=''):
                 yield i, name, ispkg
 
 
-#@simplegeneric
+@simplegeneric
 def iter_importer_modules(importer, prefix=''):
     if not hasattr(importer, 'iter_modules'):
         return []
     return importer.iter_modules(prefix)
 
-iter_importer_modules = simplegeneric(iter_importer_modules)
 
 # Implement a file walker for the normal importlib path hook
 def _iter_file_finder_modules(importer, prefix=''):
diff --git a/Lib/test/test_functools.py b/Lib/test/test_functools.py
index 9b3c31e..a6b1e03 100644
--- a/Lib/test/test_functools.py
+++ b/Lib/test/test_functools.py
@@ -1,24 +1,30 @@
 import collections
+from itertools import permutations
+import pickle
+from random import choice
 import sys
-import unittest
 from test import support
+import unittest
 from weakref import proxy
-import pickle
-from random import choice
 
 import functools
 
 py_functools = support.import_fresh_module('functools', blocked=['_functools'])
 c_functools = support.import_fresh_module('functools', fresh=['_functools'])
 
+decimal = support.import_fresh_module('decimal', fresh=['_decimal'])
+
+
 def capture(*args, **kw):
     """capture all positional and keyword arguments"""
     return args, kw
 
+
 def signature(part):
     """ return the signature of a partial object """
     return (part.func, part.args, part.keywords, part.__dict__)
 
+
 class TestPartial:
 
     def test_basic_examples(self):
@@ -138,6 +144,7 @@ class TestPartial:
         join = self.partial(''.join)
         self.assertEqual(join(data), '0123456789')
 
+
 @unittest.skipUnless(c_functools, 'requires the C _functools module')
 class TestPartialC(TestPartial, unittest.TestCase):
     if c_functools:
@@ -194,18 +201,22 @@ class TestPartialC(TestPartial, unittest.TestCase):
                 "new style getargs format but argument is not a tuple",
                 f.__setstate__, BadSequence())
 
+
 class TestPartialPy(TestPartial, unittest.TestCase):
     partial = staticmethod(py_functools.partial)
 
+
 if c_functools:
     class PartialSubclass(c_functools.partial):
         pass
 
+
 @unittest.skipUnless(c_functools, 'requires the C _functools module')
 class TestPartialCSubclass(TestPartialC):
     if c_functools:
         partial = PartialSubclass
 
+
 class TestUpdateWrapper(unittest.TestCase):
 
     def check_wrapper(self, wrapper, wrapped,
@@ -312,6 +323,7 @@ class TestUpdateWrapper(unittest.TestCase):
         self.assertTrue(wrapper.__doc__.startswith('max('))
         self.assertEqual(wrapper.__annotations__, {})
 
+
 class TestWraps(TestUpdateWrapper):
 
     def _default_update(self):
@@ -372,6 +384,7 @@ class TestWraps(TestUpdateWrapper):
         self.assertEqual(wrapper.attr, 'This is a different test')
         self.assertEqual(wrapper.dict_attr, f.dict_attr)
 
+
 class TestReduce(unittest.TestCase):
     func = functools.reduce
 
@@ -452,6 +465,7 @@ class TestReduce(unittest.TestCase):
         d = {"one": 1, "two": 2, "three": 3}
         self.assertEqual(self.func(add, d), "".join(d.keys()))
 
+
 class TestCmpToKey:
 
     def test_cmp_to_key(self):
@@ -534,14 +548,17 @@ class TestCmpToKey:
         self.assertRaises(TypeError, hash, k)
         self.assertNotIsInstance(k, collections.Hashable)
 
+
 @unittest.skipUnless(c_functools, 'requires the C _functools module')
 class TestCmpToKeyC(TestCmpToKey, unittest.TestCase):
     if c_functools:
         cmp_to_key = c_functools.cmp_to_key
 
+
 class TestCmpToKeyPy(TestCmpToKey, unittest.TestCase):
     cmp_to_key = staticmethod(py_functools.cmp_to_key)
 
+
 class TestTotalOrdering(unittest.TestCase):
 
     def test_total_ordering_lt(self):
@@ -642,6 +659,7 @@ class TestTotalOrdering(unittest.TestCase):
         with self.assertRaises(TypeError):
             TestTO(8) <= ()
 
+
 class TestLRU(unittest.TestCase):
 
     def test_lru(self):
@@ -834,6 +852,353 @@ class TestLRU(unittest.TestCase):
                          DoubleEq(2))               # Verify the correct return value
 
 
+class TestSingleDispatch(unittest.TestCase):
+    def test_simple_overloads(self):
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        def g_int(i):
+            return "integer"
+        g.register(int, g_int)
+        self.assertEqual(g("str"), "base")
+        self.assertEqual(g(1), "integer")
+        self.assertEqual(g([1,2,3]), "base")
+
+    def test_mro(self):
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        class C:
+            pass
+        class D(C):
+            pass
+        def g_C(c):
+            return "C"
+        g.register(C, g_C)
+        self.assertEqual(g(C()), "C")
+        self.assertEqual(g(D()), "C")
+
+    def test_classic_classes(self):
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        class C:
+            pass
+        class D(C):
+            pass
+        def g_C(c):
+            return "C"
+        g.register(C, g_C)
+        self.assertEqual(g(C()), "C")
+        self.assertEqual(g(D()), "C")
+
+    def test_register_decorator(self):
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        @g.register(int)
+        def g_int(i):
+            return "int %s" % (i,)
+        self.assertEqual(g(""), "base")
+        self.assertEqual(g(12), "int 12")
+        self.assertIs(g.dispatch(int), g_int)
+        self.assertIs(g.dispatch(object), g.dispatch(str))
+        # Note: in the assert above this is not g.
+        # @singledispatch returns the wrapper.
+
+    def test_wrapping_attributes(self):
+        @functools.singledispatch
+        def g(obj):
+            "Simple test"
+            return "Test"
+        self.assertEqual(g.__name__, "g")
+        self.assertEqual(g.__doc__, "Simple test")
+
+    @unittest.skipUnless(decimal, 'requires _decimal')
+    @support.cpython_only
+    def test_c_classes(self):
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        @g.register(decimal.DecimalException)
+        def _(obj):
+            return obj.args
+        subn = decimal.Subnormal("Exponent < Emin")
+        rnd = decimal.Rounded("Number got rounded")
+        self.assertEqual(g(subn), ("Exponent < Emin",))
+        self.assertEqual(g(rnd), ("Number got rounded",))
+        @g.register(decimal.Subnormal)
+        def _(obj):
+            return "Too small to care."
+        self.assertEqual(g(subn), "Too small to care.")
+        self.assertEqual(g(rnd), ("Number got rounded",))
+
+    def test_compose_mro(self):
+        c = collections
+        mro = functools._compose_mro
+        bases = [c.Sequence, c.MutableMapping, c.Mapping, c.Set]
+        for haystack in permutations(bases):
+            m = mro(dict, haystack)
+            self.assertEqual(m, [dict, c.MutableMapping, c.Mapping, object])
+        bases = [c.Container, c.Mapping, c.MutableMapping, c.OrderedDict]
+        for haystack in permutations(bases):
+            m = mro(c.ChainMap, haystack)
+            self.assertEqual(m, [c.ChainMap, c.MutableMapping, c.Mapping,
+                                 c.Sized, c.Iterable, c.Container, object])
+        # Note: The MRO order below depends on haystack ordering.
+        m = mro(c.defaultdict, [c.Sized, c.Container, str])
+        self.assertEqual(m, [c.defaultdict, dict, c.Container, c.Sized, object])
+        m = mro(c.defaultdict, [c.Container, c.Sized, str])
+        self.assertEqual(m, [c.defaultdict, dict, c.Sized, c.Container, object])
+
+    def test_register_abc(self):
+        c = collections
+        d = {"a": "b"}
+        l = [1, 2, 3]
+        s = {object(), None}
+        f = frozenset(s)
+        t = (1, 2, 3)
+        @functools.singledispatch
+        def g(obj):
+            return "base"
+        self.assertEqual(g(d), "base")
+        self.assertEqual(g(l), "base")
+        self.assertEqual(g(s), "base")
+        self.assertEqual(g(f), "base")
+        self.assertEqual(g(t), "base")
+        g.register(c.Sized, lambda obj: "sized")
+        self.assertEqual(g(d), "sized")
+        self.assertEqual(g(l), "sized")
+        self.assertEqual(g(s), "sized")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.MutableMapping, lambda obj: "mutablemapping")
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(g(l), "sized")
+        self.assertEqual(g(s), "sized")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.ChainMap, lambda obj: "chainmap")
+        self.assertEqual(g(d), "mutablemapping")  # irrelevant ABCs registered
+        self.assertEqual(g(l), "sized")
+        self.assertEqual(g(s), "sized")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.MutableSequence, lambda obj: "mutablesequence")
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "sized")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.MutableSet, lambda obj: "mutableset")
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.Mapping, lambda obj: "mapping")
+        self.assertEqual(g(d), "mutablemapping")  # not specific enough
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sized")
+        g.register(c.Sequence, lambda obj: "sequence")
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "sized")
+        self.assertEqual(g(t), "sequence")
+        g.register(c.Set, lambda obj: "set")
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "set")
+        self.assertEqual(g(t), "sequence")
+        g.register(dict, lambda obj: "dict")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "mutablesequence")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "set")
+        self.assertEqual(g(t), "sequence")
+        g.register(list, lambda obj: "list")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "list")
+        self.assertEqual(g(s), "mutableset")
+        self.assertEqual(g(f), "set")
+        self.assertEqual(g(t), "sequence")
+        g.register(set, lambda obj: "concrete-set")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "list")
+        self.assertEqual(g(s), "concrete-set")
+        self.assertEqual(g(f), "set")
+        self.assertEqual(g(t), "sequence")
+        g.register(frozenset, lambda obj: "frozen-set")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "list")
+        self.assertEqual(g(s), "concrete-set")
+        self.assertEqual(g(f), "frozen-set")
+        self.assertEqual(g(t), "sequence")
+        g.register(tuple, lambda obj: "tuple")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "list")
+        self.assertEqual(g(s), "concrete-set")
+        self.assertEqual(g(f), "frozen-set")
+        self.assertEqual(g(t), "tuple")
+
+    def test_mro_conflicts(self):
+        c = collections
+
+        @functools.singledispatch
+        def g(arg):
+            return "base"
+
+        class O(c.Sized):
+            def __len__(self):
+                return 0
+
+        o = O()
+        self.assertEqual(g(o), "base")
+        g.register(c.Iterable, lambda arg: "iterable")
+        g.register(c.Container, lambda arg: "container")
+        g.register(c.Sized, lambda arg: "sized")
+        g.register(c.Set, lambda arg: "set")
+        self.assertEqual(g(o), "sized")
+        c.Iterable.register(O)
+        self.assertEqual(g(o), "sized")   # because it's explicitly in __mro__
+        c.Container.register(O)
+        self.assertEqual(g(o), "sized")   # see above: Sized is in __mro__
+
+        class P:
+            pass
+
+        p = P()
+        self.assertEqual(g(p), "base")
+        c.Iterable.register(P)
+        self.assertEqual(g(p), "iterable")
+        c.Container.register(P)
+        with self.assertRaises(RuntimeError) as re:
+            g(p)
+            self.assertEqual(
+                str(re),
+                ("Ambiguous dispatch: <class 'collections.abc.Container'> "
+                    "or <class 'collections.abc.Iterable'>"),
+            )
+
+        class Q(c.Sized):
+            def __len__(self):
+                return 0
+
+        q = Q()
+        self.assertEqual(g(q), "sized")
+        c.Iterable.register(Q)
+        self.assertEqual(g(q), "sized")   # because it's explicitly in __mro__
+        c.Set.register(Q)
+        self.assertEqual(g(q), "set")     # because c.Set is a subclass of
+                                          # c.Sized which is explicitly in
+                                          # __mro__
+
+    def test_cache_invalidation(self):
+        from collections import UserDict
+        class TracingDict(UserDict):
+            def __init__(self, *args, **kwargs):
+                super(TracingDict, self).__init__(*args, **kwargs)
+                self.set_ops = []
+                self.get_ops = []
+            def __getitem__(self, key):
+                result = self.data[key]
+                self.get_ops.append(key)
+                return result
+            def __setitem__(self, key, value):
+                self.set_ops.append(key)
+                self.data[key] = value
+            def clear(self):
+                self.data.clear()
+        _orig_wkd = functools.WeakKeyDictionary
+        td = TracingDict()
+        functools.WeakKeyDictionary = lambda: td
+        c = collections
+        @functools.singledispatch
+        def g(arg):
+            return "base"
+        d = {}
+        l = []
+        self.assertEqual(len(td), 0)
+        self.assertEqual(g(d), "base")
+        self.assertEqual(len(td), 1)
+        self.assertEqual(td.get_ops, [])
+        self.assertEqual(td.set_ops, [dict])
+        self.assertEqual(td.data[dict], g.registry[object])
+        self.assertEqual(g(l), "base")
+        self.assertEqual(len(td), 2)
+        self.assertEqual(td.get_ops, [])
+        self.assertEqual(td.set_ops, [dict, list])
+        self.assertEqual(td.data[dict], g.registry[object])
+        self.assertEqual(td.data[list], g.registry[object])
+        self.assertEqual(td.data[dict], td.data[list])
+        self.assertEqual(g(l), "base")
+        self.assertEqual(g(d), "base")
+        self.assertEqual(td.get_ops, [list, dict])
+        self.assertEqual(td.set_ops, [dict, list])
+        g.register(list, lambda arg: "list")
+        self.assertEqual(td.get_ops, [list, dict])
+        self.assertEqual(len(td), 0)
+        self.assertEqual(g(d), "base")
+        self.assertEqual(len(td), 1)
+        self.assertEqual(td.get_ops, [list, dict])
+        self.assertEqual(td.set_ops, [dict, list, dict])
+        self.assertEqual(td.data[dict],
+                         functools._find_impl(dict, g.registry))
+        self.assertEqual(g(l), "list")
+        self.assertEqual(len(td), 2)
+        self.assertEqual(td.get_ops, [list, dict])
+        self.assertEqual(td.set_ops, [dict, list, dict, list])
+        self.assertEqual(td.data[list],
+                         functools._find_impl(list, g.registry))
+        class X:
+            pass
+        c.MutableMapping.register(X)   # Will not invalidate the cache,
+                                       # not using ABCs yet.
+        self.assertEqual(g(d), "base")
+        self.assertEqual(g(l), "list")
+        self.assertEqual(td.get_ops, [list, dict, dict, list])
+        self.assertEqual(td.set_ops, [dict, list, dict, list])
+        g.register(c.Sized, lambda arg: "sized")
+        self.assertEqual(len(td), 0)
+        self.assertEqual(g(d), "sized")
+        self.assertEqual(len(td), 1)
+        self.assertEqual(td.get_ops, [list, dict, dict, list])
+        self.assertEqual(td.set_ops, [dict, list, dict, list, dict])
+        self.assertEqual(g(l), "list")
+        self.assertEqual(len(td), 2)
+        self.assertEqual(td.get_ops, [list, dict, dict, list])
+        self.assertEqual(td.set_ops, [dict, list, dict, list, dict, list])
+        self.assertEqual(g(l), "list")
+        self.assertEqual(g(d), "sized")
+        self.assertEqual(td.get_ops, [list, dict, dict, list, list, dict])
+        self.assertEqual(td.set_ops, [dict, list, dict, list, dict, list])
+        g.dispatch(list)
+        g.dispatch(dict)
+        self.assertEqual(td.get_ops, [list, dict, dict, list, list, dict,
+                                      list, dict])
+        self.assertEqual(td.set_ops, [dict, list, dict, list, dict, list])
+        c.MutableSet.register(X)       # Will invalidate the cache.
+        self.assertEqual(len(td), 2)   # Stale cache.
+        self.assertEqual(g(l), "list")
+        self.assertEqual(len(td), 1)
+        g.register(c.MutableMapping, lambda arg: "mutablemapping")
+        self.assertEqual(len(td), 0)
+        self.assertEqual(g(d), "mutablemapping")
+        self.assertEqual(len(td), 1)
+        self.assertEqual(g(l), "list")
+        self.assertEqual(len(td), 2)
+        g.register(dict, lambda arg: "dict")
+        self.assertEqual(g(d), "dict")
+        self.assertEqual(g(l), "list")
+        g._clear_cache()
+        self.assertEqual(len(td), 0)
+        functools.WeakKeyDictionary = _orig_wkd
+
+
 def test_main(verbose=None):
     test_classes = (
         TestPartialC,
@@ -846,6 +1211,7 @@ def test_main(verbose=None):
         TestWraps,
         TestReduce,
         TestLRU,
+        TestSingleDispatch,
     )
     support.run_unittest(*test_classes)
 
diff --git a/Misc/NEWS b/Misc/NEWS
index a7e76f4..a608db8 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -344,6 +344,9 @@ Library
   the default for linking if LDSHARED is not also overriden.  This restores
   Distutils behavior introduced in 3.2.3 and inadvertently dropped in 3.3.0.
 
+- Implement PEP 443 "Single-dispatch generic functions".
+
+
 Tests
 -----
 
diff --git a/Modules/Setup.dist b/Modules/Setup.dist
index 8ea2b5e..d4e1fe1 100644
--- a/Modules/Setup.dist
+++ b/Modules/Setup.dist
@@ -116,6 +116,7 @@ _functools _functoolsmodule.c   # Tools for working with functions and callable
 _operator _operator.c	        # operator.add() and similar goodies
 _collections _collectionsmodule.c # Container types
 itertools itertoolsmodule.c    # Functions creating iterators for efficient looping 
+atexit atexitmodule.c      # Register functions to be run at interpreter-shutdown
 
 # access to ISO C locale support
 _locale _localemodule.c  # -lintl
@@ -170,7 +171,6 @@ _symtable symtablemodule.c
 #_weakref _weakref.c	# basic weak reference support
 #_testcapi _testcapimodule.c    # Python C API test module
 #_random _randommodule.c	# Random number generator
-#atexit atexitmodule.c      # Register functions to be run at interpreter-shutdown
 #_elementtree -I$(srcdir)/Modules/expat -DHAVE_EXPAT_CONFIG_H -DUSE_PYEXPAT_CAPI _elementtree.c	# elementtree accelerator
 #_pickle _pickle.c	# pickle accelerator
 #_datetime _datetimemodule.c	# datetime accelerator