Metadata-Version: 1.1
Name: methoddispatch
Version: 1.0
Summary: singledispatch decorator for instance methods.
Home-page: http://packages.python.org/methoddispatch
Author: Tim Mitchell
Author-email: tim.mitchell@leapfrog3d.com
License: BSD
Description: 
            ==============
            methoddispatch 1.0.0
            ==============
        
            `PEP 443 <http://www.python.org/dev/peps/pep-0443/>`_ proposed to expose
            a mechanism in the ``functools`` standard library module in Python 3.4
            that provides a simple form of generic programming known as
            single-dispatch generic functions.
        
            This library extends this functionality to instance methods (and works for functions too)
        
            To define a generic method , decorate it with the ``@singledispatch``
            decorator. Note that the dispatch happens on the type of the first
            argument, create your function accordingly::
        
              >>> from methoddispatch 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
            ``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
            ``register()`` attribute can be used in a functional form::
        
              >>> def nothing(arg, verbose=False):
              ...     print("Nothing.")
              ...
              >>> fun.register(type(None), nothing)
              <function nothing at 0x03D3FDB0>
        
            The ``register()`` attribute returns the undecorated function which
            enables decorator stacking, pickling, as well as creating unit tests for
            each variant independently::
        
              >>> from decimal import Decimal
              >>> @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>
        
            Decorating class methods requires the class have ``SingleDispatchMeta`` as
            a metaclass.  The metaclass ensures that the dipatch registry of
            sub-classes do not affect instances of the base class::
        
              >>> class BaseClass(metaclass=SingleDispatchMeta):
              ...     @singledispatch
              ...     def foo(self, bar):
              ...         return 'default'
              ...
              ...     @foo.register(int)
              ...     def foo_int(self, bar):
              ...         return 'int'
              ...
              >>> b = BaseClass()
              >>> b.foo('hello')
              'default'
              >>> b.foo(1)
              'int'
        
              Subclasses can extend the type registry of the function on the base class with their own overrides.
              Because the ``foo`` function is not in scope, the ``register`` decorator must be used instead::
        
              >>> class SubClass(BaseClass):
              ...     @register('foo', float)
              ...     def foo_float(self, bar):
              ...         return 'float'
              ...
              >>> s = SubClass()
              >>> s.foo(1)
              'int'
              >>> s.foo(1.0)
              'float'
              >>> b.foo(1.0)
              'default'
        
              Method overrides do not need to provide the ``register`` decorator again::
        
              >>> class SubClass2(BaseClass):
              ...     def foo_int(self, bar):
              ...         return 'my int'
              ...
              >>> s = SubClass2()
              >>> s.foo(1)
              'my int'
        
              Providing the register decorator with the same type will also work.
              Decorating 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.
        
              If your class also inhertits from an ABC interface you can use the SingleDispatchABCMeta metaclass instead.
        
Keywords: single dispatch decorator
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: BSD License
