handle simple generics like list[str].

Fix inheritance bugs.

Author: tim-mitchell

README.rst

@@ -42,16 +42,18 @@ The ``register()`` attribute returns the undecorated function which enables deco
 ...             print("Half of your number:", end=" ")
 ...         print(arg / 2)
 
-The ``register()`` attribute only works inside a class statement, relying on ``SingleDispatch.__init_subclass__``
-to create the actual dispatch table.  This also means that (unlike functools.singledispatch) two methods
+The ``register()`` method relys on ``SingleDispatch.__init_subclass__``
+to create the actual dispatch table rather than adding the function directly.
+This also means that (unlike functools.singledispatchmethod) two methods
 with the same name cannot be registered as only the last one will be in the class dictionary.
 
-Functions not defined in the class can be registered using the ``add_overload`` attribute.
+Functions not defined in the class can be registered with a generic method using the ``add_overload`` method.
 
 >>> def nothing(obj, arg, verbose=False):
 ...    print('Nothing.')
 >>> MyClass.fun.add_overload(type(None), nothing)
 
+Using ``add_overload`` will affect all instances of ``MyClass`` as if it were part of the class declaration.
 When called, the generic function dispatches on the type of the first argument
 
 >>> a = MyClass()
@@ -72,9 +74,10 @@ Nothing.
 >>> a.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.
+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
+To check which implementation will the generic function choose for a given type, use the ``dispatch()`` method
 
 >>> a.fun.dispatch(float)
 <function MyClass.fun_num at 0x1035a2840>
@@ -84,55 +87,90 @@ To check which implementation will the generic function choose for a given type,
 To access all registered implementations, use the read-only ``registry`` attribute
 
 >>> a.fun.registry.keys()
-dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
-          <class 'decimal.Decimal'>, <class 'list'>,
-          <class 'float'>])
+dict_keys([<class 'object'>, <class 'int'>, <class 'list'>, <class 'decimal.Decimal'>, <class 'float'>, <class 'NoneType'>])
 >>> a.fun.registry[float]
 <function MyClass.fun_num at 0x1035a2840>
 >>> a.fun.registry[object]
 <function MyClass.fun at 0x103fe0000>
 
+Extending the dispatch table.
+-----------------------------
+
 Subclasses can extend the type registry of the function on the base class with their own overrides.
 The ``SingleDispatch`` mixin class ensures that each subclass has it's own independant copy of the dispatch registry
 
 >>> class SubClass(MyClass):
 ...     @MyClass.fun.register(str)
 ...     def fun_str(self, arg, verbose=False):
-...         print('str')
+...         print('subclass')
 ...
 >>> s = SubClass()
 >>> s.fun('hello')
-str
+subclass
 >>> b = MyClass()
 >>> b.fun('hello')
 hello
 
-Method overrides do not need to provide the ``register`` decorator again to be used in the dispatch of ``fun``
+Overriding the dispatch table
+-----------------------------
+There are two ways to override the dispatch function for a given type.
+One way is to override a base-class method that is in the base class dispatch table.
+Method overrides do not need to provide the ``register`` decorator again to be used in the dispatch of ``fun``, you can
+simply override the specific dispatch function you want to modify.
 
->>> class SubClass2(MyClass):
+>>> class Mixin1(MyClass):
 ...     def fun_int(self, arg, verbose=False):
 ...         print('subclass int')
 ...
->>> s = SubClass2()
+>>> s = Mixin1()
 >>> s.fun(1)
 subclass int
 
-However, providing the register decorator with the same type will also work.
-Decorating a method override with a different type (not a good idea) will register the different type and leave the base-class handler in place for the orginal type.
+The other way is to register a method with the same type using the `register` method.
+
+>>> class SubClass3(MyClass):
+...    @MyClass.fun.register(int)
+...    def fun_int_override(self, arg, verbose=False):
+...        print('subclass3 int')
+...
+>>> s = SubClass3()
+>>> s.fun(1)
+subclass3 int
+
+Note that the decorator takes precedence over the method name, so if you do something like this:
+
+>>> class SubClass4(MyClass):
+...    @MyClass.fun.register(str)
+...    def fun_int(self, arg, verbose=False):
+...        print('silly mistake')
+
+then SubClass4.fun_int is used for string arguments.
+
+>>> s = SubClass4()
+>>> s.fun(1)
+1
+>>> s.fun('a string')
+silly mistake
+
+Instance overrides
+------------------
 
 Method overrides can be specified on individual instances if necessary
 
 >>> def fun_str(obj, arg, verbose=False):
-...    print('str')
+...    print('instance str')
 >>> b = MyClass()
 >>> b.fun.register(str, fun_str)
 <function fun_str at 0x000002376A3D32F0>
 >>> b.fun('hello')
-str
+instance str
 >>> b2 = MyClass()
 >>> b2.fun('hello')
 hello
 
+Integration with type hints
+---------------------------
+
 For functions annotated with types, the decorator will infer the type of the first argument automatically as shown below
 
 >>> class MyClassAnno(SingleDispatch):
@@ -148,65 +186,77 @@ For functions annotated with types, the decorator will infer the type of the fir
 ...     @MyClassAnno.fun.register
 ...     def fun_float(self, arg: float):
 ...         print('float')
+...
+...     @MyClassAnno.fun.register
+...     def fun_list(self, arg: typing.List[str]):
+...         print('list')
+
+Note that methoddispatch ignores type specialization in annotations as only the class is used for dispatching.
+This means that ``fun_list`` will be called for all list instances regardless of what is in the list.
 
-Finally, accessing the method ``fun`` via a class will use the dispatch registry for that class
+Accessing the method ``fun`` via a class will use the dispatch registry for that class
 
->>> SubClass2.fun(s, 1)
+>>> Mixin1.fun(s, 1)
 subclass int
 >>> MyClass.fun(s, 1)
 1
 
-You can use Mixin or multiple inheritance to add a generic method to a class, like this:
+``super()`` also works as expected using the dispatch table of the super class.
+
+>>> super(Mixin1, s).fun(1)
+1
+
+The usual method resolution order applies to mixin or multiple inheritance. For example:
 
 >>> class BaseClassForMixin(SingleDispatch):
-...
 ...    def __init__(self):
-...        self.mixin_base = 0
+...        self.dispatched_by = ''
 ...
 ...    @singledispatch
 ...    def foo(self, bar):
-...        self.mixin_base += 1
+...        print('BaseClass')
 ...        return 'default'
 ...
->>> class SubClass2Mixin(BaseClassForMixin):
-...    def __init__(self):
-...        self.mixin_2 = 1
-...        super().__init__()
+...    @foo.register(float)
+...    def foo_float(self, bar):
+...        print('BaseClass')
+...        return 'float'
+...
+>>> class Mixin1(BaseClassForMixin):
 ...
 ...    @BaseClassForMixin.foo.register(int)
 ...    def foo_int(self, bar):
-...        self.mixin_2 += 1
+...        print('Mixin1')
 ...        return 'int'
 ...
->>> class SubClass3Mixin(BaseClassForMixin):
-...    def __init__(self):
-...        self.mixin_3 = 1
-...        super().__init__()
-...
 ...    @BaseClassForMixin.foo.register(str)
 ...    def foo_str(self, bar):
-...        self.mixin_3 += 2
-...        return 'str'
-...
->>> class SubClass4Mixin(BaseClassForMixin):
-...    @BaseClassForMixin.foo.register(set)
-...    def foo_set(self, bar):
-...        return 'set'
+...        print('Mixin1')
+...        return 'str2'
 ...
->>> class SubClassWithMixin(SubClass4Mixin, SubClass3Mixin, SubClass2Mixin, BaseClassForMixin):
-...    def __init__(self):
-...        self.master = 10
-...        super().__init__()
+>>> class Mixin2(BaseClassForMixin):
+...    @BaseClassForMixin.foo.register(str)
+...    def foo_str2(self, bar):
+...        print('Mixin2')
+...        return 'str3'
 ...
-...    @BaseClassForMixin.foo.register(float)
+>>> class SubClassWithMixins(Mixin2, Mixin1):
 ...    def foo_float(self, bar):
-...        self.master += 1
+...        print('SubClassWithMixins')
 ...        return 'float'
 
-Then you can use it like this:
+Note that even though ``Mixin2`` has method ``foo_str2`` it will still override ``Mixin1.foo_str`` in
+the dispatch of ``foo()`` because they are both handlers for the ``str`` type and Mixin2 comes before 
+Mixin1 in the bases list.
+
 
->>> b = SubClassWithMixin()
->>> b.foo('text')
-'str'
->>> b.mixin_3
-2
+>>> s = SubClassWithMixins()
+>>> s.foo('text')
+Mixin2
+'str3'
+>>> s.foo(1)
+Mixin1
+'int'
+>>> s.foo(3.2)
+SubClassWithMixins
+'float'