ovld 0.3.9__py3-none-any.whl → 0.4.0__py3-none-any.whl

ovld/utils.py

@@ -1,9 +1,6 @@
 """Miscellaneous utilities."""
 
 import functools
-import sys
-from dataclasses import dataclass
-from typing import Protocol, runtime_checkable
 
 
 class Named:
@@ -48,122 +45,24 @@ def keyword_decorator(deco):
     return new_deco
 
 
-class _MetaMC(type):
-    def __subclasscheck__(cls, sub):
-        return cls.chk(sub)
+class UsageError(Exception):
+    pass
 
 
-def meta(condition):
-    """Return a class with a subclassing relation defined by condition.
+class Unusable:
+    def __init__(self, message):
+        self.__message = message
 
-    For example, a dataclass is a subclass of `meta(dataclasses.is_dataclass)`,
-    and a class which name starts with "X" is a subclass of
-    `meta(lambda cls: cls.__name__.startswith("X"))`.
+    def __call__(self, *args, **kwargs):
+        raise UsageError(self.__message)
 
-    Arguments:
-        condition: A function that takes a class as an argument and returns
-            True or False depending on whether it matches some condition.
-    """
-
-    class M(metaclass=_MetaMC):
-        @classmethod
-        def chk(cls, sub):
-            return condition(sub)
-
-    return M
-
-
-def _getcls(ref):
-    module, *parts = ref.split(".")
-    curr = __import__(module)
-    for part in parts:
-        curr = getattr(curr, part)
-    return curr
-
-
-def deferred(ref):
-    """Represent a class from an external module without importing it.
-
-    For instance, `deferred("numpy.ndarray")` matches instances of
-    numpy.ndarray, but it does not import numpy. When tested against a
-    class, if the first part of class's `__module__` is `numpy`, then
-    we do get the class and perform a normal issubclass check.
-
-    If the module is already loaded, `deferred` returns the class directly.
-
-    Arguments:
-        ref: A string starting with a module name representing the path
-            to import a class.
-    """
-    module, _ = ref.split(".", 1)
-    if module in sys.modules:
-        return _getcls(ref)
-
-    @meta
-    def check(cls):
-        full_cls_mod = getattr(cls, "__module__", None)
-        cls_module = full_cls_mod.split(".", 1)[0] if full_cls_mod else None
-        if cls_module == module:
-            return issubclass(cls, _getcls(ref))
-        else:
-            return False
-
-    return check
-
-
-def exactly(base_cls):
-    """Match the class but not its subclasses."""
-
-    @meta
-    def check(cls):
-        return cls is base_cls
-
-    return check
-
-
-def strict_subclass(base_cls):
-    """Match subclasses but not the base class."""
-
-    @meta
-    def check(cls):
-        return (
-            isinstance(cls, type)
-            and issubclass(cls, base_cls)
-            and cls is not base_cls
-        )
-
-    return check
-
-
-def has_attribute(*attrs):
-    """Match classes with the given attributes."""
-
-    @meta
-    def check(cls):
-        return all(hasattr(cls, a) for a in attrs)
-
-    return check
-
-
-@runtime_checkable
-@dataclass
-class Dataclass(Protocol):
-    @classmethod
-    def __subclasshook__(cls, subclass):
-        return hasattr(subclass, "__dataclass_fields__") and hasattr(
-            subclass, "__dataclass_params__"
-        )
+    def __getattr__(self, attr):
+        raise UsageError(self.__message)
 
 
 __all__ = [
     "BOOTSTRAP",
     "MISSING",
-    "Dataclass",
     "Named",
-    "deferred",
-    "exactly",
-    "has_attribute",
-    "meta",
     "keyword_decorator",
-    "strict_subclass",
 ]

ovld/version.py

@@ -1 +1 @@
-version = "0.3.9"
+version = "0.4.0"

ovld-0.4.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.3
+Name: ovld
+Version: 0.4.0
+Summary: Overloading Python functions
+Author-email: Olivier Breuleux <breuleux@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+
+# Ovld
+
+Fast multiple dispatch in Python, with many extra features.
+
+[📋 Documentation](https://ovld.readthedocs.io/en/latest/)
+
+With ovld, you can write a version of the same function for every type signature using annotations instead of writing an awkward sequence of `isinstance` statements. Unlike Python's `singledispatch`, it works for multiple arguments.
+
+* ⚡️ **[Fast](https://ovld.readthedocs.io/en/latest/compare/#results):** `ovld` is the fastest multiple dispatch library around, by some margin.
+* 🚀 [**Variants**](https://ovld.readthedocs.io/en/latest/usage/#variants) and [**mixins**](https://ovld.readthedocs.io/en/latest/usage/#mixins) of functions and methods.
+* 🦄 **[Dependent types](https://ovld.readthedocs.io/en/latest/dependent/):** Overloaded functions can depend on more than argument types: they can depend on actual values.
+* 🔑 **Extensive:** Dispatch on functions, methods, positional arguments and even [keyword arguments](https://ovld.readthedocs.io/en/latest/usage/#keyword-arguments) (with some restrictions).
+
+## Example
+
+Here's a function that recursively adds lists, tuples and dictionaries:
+
+```python
+from ovld import ovld, recurse
+
+@ovld
+def add(x: list, y: list):
+    return [recurse(a, b) for a, b in zip(x, y)]
+
+@ovld
+def add(x: tuple, y: tuple):
+    return tuple(recurse(a, b) for a, b in zip(x, y))
+
+@ovld
+def add(x: dict, y: dict):
+    return {k: recurse(v, y[k]) for k, v in x.items()}
+
+@ovld
+def add(x: object, y: object):
+    return x + y
+
+assert add([1, 2], [3, 4]) == [4, 6]
+```
+
+The `recurse` function is special: it will recursively call the current ovld object. You may ask: how is it different from simply calling `add`? The difference is that if you create a *variant* of `add`, `recurse` will automatically call the variant.
+
+For example:
+
+
+## Variants
+
+A *variant* of an `ovld` is a copy of the `ovld`, with some methods added or changed. For example, let's take the definition of `add` above and make a variant that multiplies numbers instead:
+
+```python
+@add.variant
+def mul(self, x: object, y: object):
+    return x * y
+
+assert mul([1, 2], [3, 4]) == [3, 8]
+```
+
+Simple! This means you can define one `ovld` that recursively walks generic data structures, and then specialize it in various ways.
+
+
+## Priority and call_next
+
+You can define a numeric priority for each method (the default priority is 0):
+
+```python
+from ovld import call_next
+
+@ovld(priority=1000)
+def f(x: int):
+    return call_next(x + 1)
+
+@ovld
+def f(x: int):
+    return x * x
+
+assert f(10) == 121
+```
+
+Both definitions above have the same type signature, but since the first has higher priority, that is the one that will be called.
+
+However, that does not mean there is no way to call the second one. Indeed, when the first function calls the special function `call_next(x + 1)`, it will call the next function in the list below itself.
+
+The pattern you see above is how you may wrap each call with some generic behavior. For instance, if you did something like that:
+
+```python
+@f.variant(priority=1000)
+def f2(x: object)
+    print(f"f({x!r})")
+    return call_next(x)
+```
+
+You would effectively be creating a clone of `f` that traces every call.
+
+
+## Dependent types
+
+A dependent type is a type that depends on a value. `ovld` supports this, either through `Literal[value]` or `Dependent[bound, check]`. For example, this definition of factorial:
+
+```python
+from typing import Literal
+from ovld import ovld, recurse, Dependent
+
+@ovld
+def fact(n: Literal[0]):
+    return 1
+
+@ovld
+def fact(n: Dependent[int, lambda n: n > 0]):
+    return n * recurse(n - 1)
+
+assert fact(5) == 120
+fact(-1)   # Error!
+```
+
+The first argument to `Dependent` must be a type bound. The bound must match before the logic is called, which also ensures we don't get a performance hit for unrelated types. For type checking purposes, `Dependent[T, A]` is equivalent to `Annotated[T, A]`.
+
+### dependent_check
+
+Define your own types with the `@dependent_check` decorator:
+
+```python
+import torch
+from ovld import ovld, dependent_check
+
+@dependent_check
+def Shape(tensor: torch.Tensor, *shape):
+    return (
+        len(tensor.shape) == len(shape)
+        and all(s2 is Any or s1 == s2 for s1, s2 in zip(tensor.shape, shape))
+    )
+
+@dependent_check
+def Dtype(tensor: torch.Tensor, dtype):
+    return tensor.dtype == dtype
+
+@ovld
+def f(tensor: Shape[3, Any]):
+    # Matches 3xN tensors
+    ...
+
+@ovld
+def f(tensor: Shape[2, 2] & Dtype[torch.float32]):
+    # Only matches 2x2 tensors that also have the float32 dtype
+    ...
+```
+
+The first parameter is the value to check. The type annotation (e.g. `value: torch.Tensor` above) is interpreted by `ovld` to be the bound for this type, so `Shape` will only be called on parameters of type `torch.Tensor`.
+
+## Methods
+
+Either inherit from `OvldBase` or use the `OvldMC` metaclass to use multiple dispatch on methods.
+
+```python
+from ovld import OvldBase, OvldMC
+
+# class Cat(OvldBase):  <= Also an option
+class Cat(metaclass=OvldMC):
+    def interact(self, x: Mouse):
+        return "catch"
+
+    def interact(self, x: Food):
+        return "devour"
+
+    def interact(self, x: PricelessVase):
+        return "destroy"
+```
+
+### Subclasses
+
+Subclasses inherit overloaded methods. They may define additional overloads for these methods which will only be valid for the subclass, but they need to use the `@extend_super` decorator (this is required for clarity):
+
+
+```python
+from ovld import OvldMC, extend_super
+
+class One(metaclass=OvldMC):
+    def f(self, x: int):
+        return "an integer"
+
+class Two(One):
+    @extend_super
+    def f(self, x: str):
+        return "a string"
+
+assert Two().f(1) == "an integer"
+assert Two().f("s") == "a string"
+```
+
+# Benchmarks
+
+`ovld` is pretty fast: the overhead is comparable to `isinstance` or `match`, and only 2-3x slower when dispatching on `Literal` types. Compared to other multiple dispatch libraries, it is 1.5x to 100x faster.
+
+Time relative to the fastest implementation (1.00) (lower is better).
+
+| Bench | custom | [ovld](https://github.com/breuleux/ovld) | [plum](https://github.com/beartype/plum) | [multim](https://github.com/coady/multimethod) | [multid](https://github.com/mrocklin/multipledispatch/) | [runtype](https://github.com/erezsh/runtype) | [fastcore](https://github.com/fastai/fastcore) | [singled](https://docs.python.org/3/library/functools.html#functools.singledispatch) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+|[trivial](https://github.com/breuleux/ovld/tree/master/benchmarks/test_trivial.py)|1.14|1.00|2.53|3.64|1.61|1.86|41.31|1.54|
+|[add](https://github.com/breuleux/ovld/tree/master/benchmarks/test_add.py)|1.01|1.00|3.46|4.83|2.21|2.66|56.08|x|
+|[multer](https://github.com/breuleux/ovld/tree/master/benchmarks/test_multer.py)|1.00|1.06|9.79|4.11|7.19|1.89|40.37|6.34|
+|[ast](https://github.com/breuleux/ovld/tree/master/benchmarks/test_ast.py)|1.00|1.06|23.07|3.04|1.68|1.87|29.11|1.63|
+|[calc](https://github.com/breuleux/ovld/tree/master/benchmarks/test_calc.py)|1.00|1.96|80.00|43.21|x|x|x|x|
+|[fib](https://github.com/breuleux/ovld/tree/master/benchmarks/test_fib.py)|1.00|3.58|438.97|123.58|x|x|x|x|
+|[tweak](https://github.com/breuleux/ovld/tree/master/benchmarks/test_tweaknum.py)|1.00|2.59|x|x|x|x|x|x|

ovld-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+ovld/__init__.py,sha256=nF8ymgr8dSL2WvDpOXVxqDuEGUywbkiCGr4ICumMD8U,1286
+ovld/core.py,sha256=siahCDuw78n02-2g7TGI1GerrGvPxT0zPouN6Z30Z-g,25497
+ovld/dependent.py,sha256=QITsWu2uCwqkHE0tunETy8Jqwc272uoG5YM0I5yy0m4,7303
+ovld/mro.py,sha256=dNuVW5DIOT8TJtY4vEpxT4q3R8fQxJ8UyDQSD9oFYYo,5116
+ovld/recode.py,sha256=Vc97Nv1j2GWuitLOzIuIhpscZ4gaOJQP3hLNp8SGTQ8,17890
+ovld/typemap.py,sha256=U_BmXtts1oYVa6gI3cgGHMX5kFcCJY_mt_cjWvDo3jQ,12979
+ovld/types.py,sha256=Zeb7xhHbL4T7qIRHI-I_cjG61UIWrfZv_EwjwqhB-rY,6381
+ovld/utils.py,sha256=V6Y8oZ6ojq8JaODL1rMZbU5L9QG0YSqHNYmpIFiwy3M,1294
+ovld/version.py,sha256=yhiWOz0HoJGRRI9-JQ2eh_0AbByy-6psK08-kpTSHJw,18
+ovld-0.4.0.dist-info/METADATA,sha256=4NkzmXbqa8ZNCwESYT4U8yILZyaIlw1rcghfCyaT50U,7526
+ovld-0.4.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+ovld-0.4.0.dist-info/licenses/LICENSE,sha256=cSwNTIzd1cbI89xt3PeZZYJP2y3j8Zus4bXgo4svpX8,1066
+ovld-0.4.0.dist-info/RECORD,,

ovld-0.3.9.dist-info/METADATA

@@ -1,305 +0,0 @@
-Metadata-Version: 2.3
-Name: ovld
-Version: 0.3.9
-Summary: Overloading Python functions
-Author-email: Olivier Breuleux <breuleux@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-
-
-# Ovld
-
-Multiple dispatch in Python, with some extra features.
-
-With ovld, you can write a version of the same function for every type signature using annotations instead of writing an awkward sequence of `isinstance` statements. Unlike Python `singledispatch`, it works for multiple arguments.
-
-Other features of `ovld`:
-
-* Multiple dispatch for methods (with `metaclass=ovld.OvldMC`)
-* Create variants of functions
-* Built-in support for extensible recursion
-* Function wrappers
-* Function postprocessors
-* Nice stack traces
-
-## Example
-
-Here's a function that adds lists, tuples and dictionaries:
-
-```python
-from ovld import ovld
-
-@ovld
-def add(x: list, y: list):
-    return [add(a, b) for a, b in zip(x, y)]
-
-@ovld
-def add(x: tuple, y: tuple):
-    return tuple(add(a, b) for a, b in zip(x, y))
-
-@ovld
-def add(x: dict, y: dict):
-    return {k: add(v, y[k]) for k, v in x.items()}
-
-@ovld
-def add(x: object, y: object):
-    return x + y
-```
-
-## Bootstrapping and variants
-
-Now, there is another way to do this using ovld's *auto-bootstrapping*. Simply list `self` as the first argument to the function, and `self` will be bound to the function itself, so you can call `self(x, y)` for the recursion instead of `add(x, y)`:
-
-
-```python
-@ovld
-def add(self, x: list, y: list):
-    return [self(a, b) for a, b in zip(x, y)]
-
-@ovld
-def add(self, x: tuple, y: tuple):
-    return tuple(self(a, b) for a, b in zip(x, y))
-
-@ovld
-def add(self, x: dict, y: dict):
-    return {k: self(v, y[k]) for k, v in x.items()}
-
-@ovld
-def add(self, x: object, y: object):
-    return x + y
-```
-
-Why is this useful, though? Observe:
-
-```python
-@add.variant
-def mul(self, x: object, y: object):
-    return x * y
-
-assert add([1, 2], [3, 4]) == [4, 6]
-assert mul([1, 2], [3, 4]) == [3, 8]
-```
-
-A `variant` of a function is a copy which inherits all of the original's implementations but may define new ones. And because `self` is bound to the function that's called at the top level, the implementations for `list`, `tuple` and `dict` will bind `self` to `add` or `mul` depending on which one was called. You may also call `self.super(*args)` to invoke the parent implementation for that type.
-
-
-## Custom dispatch
-
-You can define your own dispatching function. The dispatcher's first argument is always `self`.
-
-* `self.resolve(x, y)` to get the right function for the types of x and y
-* `self[type(x), type(y)]` will also return the right function for these types, but it works directly with the types.
-
-For example, here is how you might define a function such that f(x) <=> f(x, x):
-
-```python
-@ovld.dispatch
-def add_default(self, x, y=None):
-    if y is None:
-        y = x
-    return self.resolve(x, y)(x, y)
-
-@ovld
-def add_default(x: int, y: int):
-    return x + y
-
-@ovld
-def add_default(x: str, y: str):
-    return x + y
-
-@ovld
-def add_default(xs: list, ys: list):
-    return [add_default(x, y) for x, y in zip(xs, ys)]
-
-assert add_default([1, 2, "alouette"]) == [2, 4, "alouettealouette"]
-```
-
-There are other uses for this feature, e.g. memoization.
-
-The normal functions may also have a `self`, which works the same as bootstrapping.
-
-## Postprocess
-
-`@ovld`, `@ovld.dispatch`, etc. take a `postprocess` argument which should be a function of one argument. That function will be called with the result of the call and must return the final result of the call.
-
-Note that intermediate, bootstrapped recursive calls (recursive calls using `self()`) will **not** be postprocessed (if you want to wrap these calls, you can do so otherwise, like defining a custom dispatch). Only the result of the top level call is postprocessed.
-
-## Methods
-
-Use the `OvldMC` metaclass to use multiple dispatch on methods. In this case there is no bootstrapping as described above and `self` is simply bound to the class instance.
-
-```python
-from ovld import OvldMC
-
-class Cat(metaclass=OvldMC):
-    def interact(self, x: Mouse):
-        return "catch"
-
-    def interact(self, x: Food):
-        return "devour"
-
-    def interact(self, x: PricelessVase):
-        return "destroy"
-```
-
-Subclasses of `Cat` will inherit the overloaded `interact` and it may define additional overloaded methods which will only be valid for the subclass.
-
-**Note:** It is possible to use `ovld.dispatch` on methods, but in this case be aware that the first argument for the dispatch method will not be the usual `self` but an `OvldCall` object. The `self` can be retrived as `ovldcall.obj`. Here's an example to make it all clear:
-
-```python
-class Stuff(metaclass=OvldMC):
-    def __init__(self, mul):
-        self.mul = mul
-
-    @ovld.dispatch
-    def calc(ovldcall, x):
-        # Wraps every call to self.calc, but we receive ovldcall instead of self
-        # ovldcall[type(x)] returns the right method to call
-        # ovldcall.obj is the self (the actual instance of Stuff)
-        return ovldcall[type(x)](x) * ovldcall.obj.mul
-
-    def calc(self, x: int):
-        return x + 1
-
-    def calc(self, xs: list):
-        return [self.calc(x) for x in xs]
-
-print(Stuff(2).calc([1, 2, 3]))  # [4, 6, 8, 4, 6, 8]
-```
-
-### Mixins in subclasses
-
-The `@extend_super` decorator on a method will combine the method with the definition on the superclass:
-
-```python
-from ovld import OvldMC, extend_super
-
-class One(metaclass=OvldMC):
-    def f(self, x: int):
-        return "an integer"
-
-class Two(One):
-    @extend_super
-    def f(self, x: str):
-        return "a string"
-
-assert Two().f(1) == "an integer"
-assert Two().f("s") == "a string"
-```
-
-## Ambiguous calls
-
-The following definitions will cause a TypeError at runtime when called with two ints, because it is unclear which function is the right match:
-
-```python
-@ovld
-def ambig(x: int, y: object):
-    print("io")
-
-@ovld
-def ambig(x: object, y: int):
-    print("oi")
-
-ambig(8, 8)  # ???
-```
-
-You may define an additional function with signature (int, int) to disambiguate:
-
-```python
-@ovld
-def ambig(x: int, y: int):
-    print("ii")
-```
-
-## Other features
-
-### meta
-
-To test arbitrary conditions, you can use `meta`:
-
-```python
-from ovld import ovld, meta
-
-@meta
-def StartsWithT(cls):
-    return cls.__name__.startswith("T")
-
-@ovld
-def f(x: StartsWithT):
-    return "T"
-
-assert f(TypeError("xyz")) == "T"
-
-
-# Or: a useful example, since dataclasses have no common superclass:
-
-from dataclasses import dataclass, is_dataclass
-
-@dataclass
-class Point:
-    x: int
-    y: int
-
-@ovld
-def f(x: meta(is_dataclass)):
-    return "dataclass"
-
-assert f(Point(1, 2)) == "dataclass"
-```
-
-
-### deferred
-
-You may define overloads for certain classes from external packages without
-having to import them:
-
-
-```python
-from ovld import ovld, deferred
-
-@ovld
-def f(x: deferred("numpy.ndarray")):
-    return "ndarray"
-
-# numpy is not imported
-assert "numpy" not in sys.modules
-
-# But once we import it, the ovld works:
-import numpy
-assert f(numpy.arange(10)) == "ndarray"
-```
-
-
-### Tracebacks
-
-`ovld` automagically renames functions so that the stack trace is more informative:
-
-```python
-@add.variant
-def bad(self, x: object, y: object):
-    raise Exception("Bad.")
-
-bad([1], [2])
-
-"""
-  File "/Users/breuleuo/code/ovld/ovld/core.py", line 148, in bad.entry
-    res = ovc(*args, **kwargs)
-  File "/Users/breuleuo/code/ovld/ovld/core.py", line 182, in bad.dispatch
-    return method(self.bind_to, *args, **kwargs)
-  File "example.py", line 6, in bad[list, list]
-    return [self(a, b) for a, b in zip(x, y)]
-  File "example.py", line 6, in <listcomp>
-    return [self(a, b) for a, b in zip(x, y)]
-  File "/Users/breuleuo/code/ovld/ovld/core.py", line 182, in bad.dispatch
-    return method(self.bind_to, *args, **kwargs)
-  File "example.py", line 26, in bad[*, *]
-    raise Exception("Bad.")
-  Exception: Bad.
-"""
-```
-
-The functions on the stack have names like `bad.entry`, `bad.dispatch`, `bad[list, list]` and `bad[*, *]` (`*` stands for `object`), which lets you better understand what happened just from the stack trace.
-
-This also means profilers will be able to differentiate between these paths and between variants, even if they share code paths.

ovld-0.3.9.dist-info/RECORD

@@ -1,10 +0,0 @@
-ovld/__init__.py,sha256=jqq7r0RhfvkqmQa8Wc7wqX3Qh5NbwL_6Nfr1sp88Kh0,734
-ovld/core.py,sha256=3JmnfLF6puVtWkc01Hnxuss4gVdWzX9mrLVMfysQqJY,32895
-ovld/mro.py,sha256=W6T5IPec6YQIvv8oSwg-xGHTzZP1zOuTZuaRCegbl-I,6296
-ovld/recode.py,sha256=45VmTUmk2GmWRfTLANMHhyzVcgBit2RvwULzyWpOMhI,2234
-ovld/utils.py,sha256=8kINtHrWdC0bNVccxYIkHBaGFk_YFpjtnjAa9GyXNmA,3861
-ovld/version.py,sha256=8WhSz7JLKtk-44zKbF-sqJmexEzvpM-d0cPHqr6cE5k,18
-ovld-0.3.9.dist-info/METADATA,sha256=wbN2H6NflCIkt-OZJvzrVXWNIz8bH0FTow83Ir0C8NM,8282
-ovld-0.3.9.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-ovld-0.3.9.dist-info/licenses/LICENSE,sha256=cSwNTIzd1cbI89xt3PeZZYJP2y3j8Zus4bXgo4svpX8,1066
-ovld-0.3.9.dist-info/RECORD,,