polymorphism 0.1.2
Ad hoc polymorphism for Python classes!
License: MIT
Requires Python: >=3.4
Keywords: polymorphism,multiple dispatch,ad hoc

.. highlight:: python

Ad hoc polymorphism for Python classes!
=====================================================

Installation
------------
::

    pip install polymorphism

``polymorphism`` support python 3.4+

Usage
-----
To use the ``polymorphism`` simply inherit from the ``Polymorphism`` class::


    from polymorphism import Polymorphism


    class Simple(Polymorphism):
        def calc(self, x: int, y: int) -> None:
            pass

        def calc(self, x: float, y: float) -> None:
            pass

Or use it as metaclass::

    from polymorphism import PolymorphismMeta

    class Simple(metaclass=PolymorphismMeta):
        ...


Sometimes adding another class to the inheritance is undesirable, then you can use the ``overload`` decorator::

    from polymorphism import overload


    class Simple(Polymorphism):
        @overload
        def calc(self, x: int, y: int) -> None:
            pass

        @calc.overload
        def calc(self, x: float, y: float) -> None:
            pass

The only difference between using a decorator and inheriting it is checking for method shading. With ``overload`` the next example will not raise exception::

    from polymorphism import overload


    class Simple(Polymorphism):
        @overload
        def calc(self, x: int, y: int) -> None:
            pass

        calc = 5

And ``calc`` would be only the attribute.

Why?
----
The idea to implement polymorphism is not new. Many libraries `implement <https://github.com/mrocklin/multipledispatch>`_ this idea. Even the `standard library <http://docs.python.org/3.4/library/functools.html#functools.singledispatch>`_ has an implementation.

But they do not support use with classes or standard type annotation.

The basic idea of the implementation was inspired by the great book `Python Cookbook 3rd Edition <http://shop.oreilly.com/product/0636920027072.do>`_ by David Beazley and Brian K. Jones. But the implementation in the book did not support usage of keyword arguments!

Advantages
----------
* Use standard and custom descriptors
* Use naming (keyword) arguments
* Checks for:

  * Arguments for variable length
  * Missed argument annotation
  * Name of wrapped function of descriptor
  * Shading method by attribute or data descriptor (like ``property``)
  * Redefining the method with the same types

* Using any name for instance, not only ``self``

For all checks is raised ``TypeError`` exception.

Limitations
-----------

* Simple types for dispatching
* ``overload`` should be top of decorators
* Custom descriptor should save wrapped function  under "__wrapped__" name
* Obvious, method argument can't be variable length (\* and \*\*)


Examples
--------
There are no restrictions on the use of the number of decorators, you only need to comply the naming convention.

For example::

    class Simple(Polymorphism):
        def calc(self, x: int, y: int) -> None:
            pass

        @classmethod
        def calc(cls, x: float, y: float) -> None:
            pass

        @staticmethod
        def calc(x: str, y: str) -> None:
            pass

    Simple().calc(1.0, y=2.0)

While use ``overload`` decorator place it on top::

    class Simple:
        @overload
        def calc(self, x: int, y: int) -> None:
            pass

        @calc.overload
        @classmethod
        def calc_float(cls, x: float, y: float) -> None:
            pass

        @calc.overload
        @staticmethod
        def calc_str(x: str, y: str) -> None:
            pass

With ``overload`` only first method name matter. Other methods can have any other names.

``polymorphism`` checks the class at the creation time::

    class Simple(Polymorphism):
        def calc(self, x: int, y: int) -> None:
            pass

        def calc(self, x: int, y: int, z: int = 3) -> None:
            pass

The above example will raise ``TypeError`` exception because ``calc`` method overloaded with ``z`` parameter with default value and it is impossible distinct last method from first.

``polymorphism`` will raise ``TypeError`` exception on any wrong overloading, so you don't need worry about correctness of it.

See more examples in `tests.py <https://github.com/asduj/polymorphism/blob/master/tests.py>`_.

To-do
-----

* Complex and builtin types for dispatching like ``List[int]`` or ``Number``