Metadata-Version: 1.1
Name: genericfuncs
Version: 0.2.0
Summary: Dynamic dispatch over arbitrary predicates
Home-page: https://github.com/AvivC/genericfuncs
Author: Aviv Cohn
Author-email: avivcohn123@yahoo.com
License: MIT
Description: 
        genericfuncs
        ============
        
        :code:`genericfuncs` allows you to create functions which execute different
        implementations depending on the arguments.
        
        This module can be seen as a powerful improvement over Python 3's :code:`singledispatch`:
        
        * Allows dispatch over any boolean callable, not just type checks.
        * Allows dispatch over any number of arguments, not just the first argument.
        
        
        Basic usage
        ***********
        
            from genericfuncs import generic
        
            @generic
            def func(a):
                # default implementation
                raise ValueError()
        
            @func.when(lambda a: a.startswith('foo')):
            def _impl_1(a):
                return a.upper()
        
            @func.when(lambda a: a.startswith('bar')):
            def _impl_2(a):
                return a.lower()
        
        The first predicate that returns True has its mapped implementation invoked.
        Predicates are checked in order of definition.
        
        
        Installation
        ************
        
        :code:`pip install genericfuncs`
        
        
        Advanced
        ********
        
        Arguments are injected into predicates and implementations by their name.
        This means a predicate or implementation is able to specify only the arguments it needs. For example::
        
            @generic
            def multiple_params_func(a, b, c):
                return a + b + c  # default implementation
        
            @multiple_params_func.when(lambda b: b > 10)  # only inject argument `b` to the predicate
            def _when_b_greater_than_10(a):  # only inject `a` to the implementation
                return a * 10
        
            @multiple_params_func.when(lambda a, b: a % b == 0)  # only inject `a` and `b`
            def _when_a_divisible_by_c(a, b, c):  # use all arguments
                return a / b * c
        
        However the call site must list all mandatory arguments, as usual in Python::
        
            multiple_params_func(10, 20, 30) --> 100  # _when_b_great_than_10() invoked
            multiple_params_func(4, 2, 'bla') --> 'blabla'  # _when_a_divisible_by_c() invoked
            multiple_params_func(0, 0, 0) --> 0  # default implementation invoked
        
        When defining a predicate, one can list exception types that should not
        propagate if raised inside the predicate. For example::
        
            @my_generic_func.when(lambda a: a > 10, ignored_errors=[TypeError])
            def _implementation(a):
                ...
        
        When invoking :code:`my_generic_func(MyThing())`, a :code:`TypeError` will be raised inside the predicate
        because :code:`MyThing` doesn't support :code:`>` operator.
        Normally, the error would propagate and crash the program.
        Specifying :code:`ignored_errors=[TypeError]` makes the error be silently ignored,
        moving on to the next predicate.
        
Keywords: generic functions utility programming development
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
