ovld 0.4.1__tar.gz → 0.4.3__tar.gz

{ovld-0.4.1 → ovld-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ovld
-Version: 0.4.1
+Version: 0.4.3
 Summary: Overloading Python functions
 Project-URL: Homepage, https://ovld.readthedocs.io/en/latest/
 Project-URL: Documentation, https://ovld.readthedocs.io/en/latest/

{ovld-0.4.1 → ovld-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ovld"
-version = "0.4.1"
+version = "0.4.3"
 description = "Overloading Python functions"
 authors = [
     { name = "Olivier Breuleux", email = "breuleux@gmail.com" }

ovld-0.4.3/reddit.md

@@ -0,0 +1,54 @@
+## What My Project Does
+
+[ovld](https://github.com/breuleux/ovld) implements multiple dispatch in Python. This lets you define multiple versions of the same function with different type signatures.
+
+For example:
+
+```python
+import math
+from typing import Literal
+from ovld import ovld
+
+@ovld
+def div(x: int, y: int):
+    return x / y
+
+@ovld
+def div(x: str, y: str):
+    return f"{x}/{y}"
+
+@ovld
+def div(x: int, y: Literal[0]):
+    return math.inf
+
+assert div(8, 2) == 4
+assert div("/home", "user") == "/home/user"
+assert div(10, 0) == math.inf
+```
+
+
+## Target Audience
+
+Ovld is pretty generally applicable: multiple dispatch is a central feature of several programming languages, e.g. Julia. I find it particularly useful when doing work on complex heterogeneous data structures, for instance walking an AST, serializing/deserializing data, generating HTML representations of data, etc.
+
+
+## Features
+
+* Wide range of supported annotations: normal types, protocols, Union, Literal, [custom types](https://ovld.readthedocs.io/en/latest/types/#defining-new-types) such as HasMethod, Intersection and arbitrary user-defined types.
+* Support for [dependent types](https://ovld.readthedocs.io/en/latest/dependent/), by which I mean "types" that depend on the values of the arguments. For example you can easily implement a `Regexp[regex]` type that matches string arguments based on regular expressions, or a type that only matches 2x2 torch.Tensor with int8 dtype.
+* Dispatch on keyword arguments (with a few limitations).
+* Define numeric priority levels for disambiguation.
+* Define [variants](https://ovld.readthedocs.io/en/latest/usage/#variants) of existing functions (copies of existing overloads with additional functionality)
+* Special `recurse()` function for recursive calls that also work with variants.
+* Special `call_next()` function to call the next dispatch.
+
+
+## Comparison
+
+There already exist a few multiple dispatch libraries: plum, multimethod, multipledispatch, runtype, fastcore, and the builtin functools.singledispatch (single argument).
+
+Ovld is faster than all of them. From 1.5x to 100x faster depending on use case, and in the ballpark of isinstance/match. It is also generally more featureful: no other library supports dispatch on keyword arguments, and only a few support `Literal` annotations, but with massive performance penalties.
+
+You can also do many things ovld does with the `match` statement, except you cannot extend existing `match` statements with more signatures.
+
+[Whole comparison section, with benchmarks, can be found here.](https://ovld.readthedocs.io/en/latest/compare/)

ovld-0.4.3/reddit.py

@@ -0,0 +1,24 @@
+import math
+from typing import Literal
+
+from ovld import ovld
+
+
+@ovld
+def div(x: int, y: int):
+    return x / y
+
+
+@ovld
+def div(x: str, y: str):
+    return f"{x}/{y}"
+
+
+@ovld
+def div(x: int, y: Literal[0]):
+    return math.inf
+
+
+assert div(8, 2) == 4
+assert div("/home", "user") == "/home/user"
+assert div(10, 0) == math.inf

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/__init__.py

@@ -15,6 +15,11 @@ from .dependent import (
     ParametrizedDependentType,
     dependent_check,
 )
+from .mro import (
+    TypeRelationship,
+    subclasscheck,
+    typeorder,
+)
 from .recode import call_next, recurse
 from .typemap import (
     MultiTypeMap,
@@ -66,6 +71,9 @@ __all__ = [
     "Intersection",
     "StrictSubclass",
     "class_check",
+    "subclasscheck",
+    "typeorder",
+    "TypeRelationship",
     "parametrized_class_check",
     "keyword_decorator",
     "call_next",

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/core.py

@@ -85,6 +85,7 @@ class Signature:
     req_names: frozenset
     vararg: bool
     priority: float
+    tiebreak: int = 0
     is_method: bool = False
     arginfo: list[Arginfo] = field(
         default_factory=list, hash=False, compare=False
@@ -393,8 +394,8 @@ class _Ovld:
             )
         else:
             hlp = ""
-            for p, prio, spc in possibilities:
-                hlp += f"* {p.__name__}  (priority: {prio}, specificity: {list(spc)})\n"
+            for c in possibilities:
+                hlp += f"* {c.handler.__name__}  (priority: {c.priority}, specificity: {list(c.specificity)})\n"
             return TypeError(
                 f"Ambiguous resolution in {self} for"
                 f" argument types [{typenames}]\n"
@@ -503,7 +504,15 @@ class _Ovld:
             raise TypeError(
                 f"There is already a method for {sigstring(sig.types)}"
             )
-        self._defns[sig] = fn
+
+        def _set(sig, fn):
+            if sig in self._defns:
+                # Push down the existing handler with a lower tiebreak
+                msig = replace(sig, tiebreak=sig.tiebreak - 1)
+                _set(msig, self._defns[sig])
+            self._defns[sig] = fn
+
+        _set(sig, fn)
 
         self._update()
         return self

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/dependent.py

@@ -7,7 +7,6 @@ from typing import TYPE_CHECKING, Any, Mapping, TypeVar, Union
 from .types import (
     Intersection,
     Order,
-    TypeRelationship,
     normalize_type,
     subclasscheck,
     typeorder,
@@ -67,26 +66,34 @@ class DependentType:
     def codegen(self):
         return CodeGen("{this}.check({arg})", {"this": self})
 
-    def __typeorder__(self, other):
+    def __type_order__(self, other):
         if isinstance(other, DependentType):
             order = typeorder(self.bound, other.bound)
             if order is Order.SAME:
                 # It isn't fully deterministic which of these will be called
                 # because of set ordering between the types we compare
                 if self < other:  # pragma: no cover
-                    return TypeRelationship(Order.LESS, matches=False)
+                    return Order.LESS
                 elif other < self:  # pragma: no cover
-                    return TypeRelationship(Order.MORE, matches=False)
+                    return Order.MORE
                 else:
-                    return TypeRelationship(Order.NONE, matches=False)
+                    return Order.NONE
             else:  # pragma: no cover
-                return TypeRelationship(order, matches=False)
-        elif (matches := subclasscheck(other, self.bound)) or subclasscheck(
+                return order
+        elif subclasscheck(other, self.bound) or subclasscheck(
             self.bound, other
         ):
-            return TypeRelationship(Order.LESS, matches=matches)
+            return Order.LESS
         else:
-            return TypeRelationship(Order.NONE, matches=False)
+            return Order.NONE
+
+    def __is_supertype__(self, other):
+        if isinstance(other, DependentType):
+            return False
+        elif subclasscheck(other, self.bound):
+            return True
+        else:
+            return False
 
     def __lt__(self, other):
         return False

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/mro.py

@@ -22,7 +22,8 @@ class Order(Enum):
 @dataclass
 class TypeRelationship:
     order: Order
-    matches: bool = None
+    supertype: bool = NotImplemented
+    subtype: bool = NotImplemented
 
 
 def _issubclass(t1, t2):
@@ -48,19 +49,16 @@ def typeorder(t1, t2):
     if t1 == t2:
         return Order.SAME
 
-    t1 = getattr(t1, "__proxy_for__", t1)
-    t2 = getattr(t2, "__proxy_for__", t2)
-
     if (
-        hasattr(t1, "__typeorder__")
-        and (result := t1.__typeorder__(t2)) is not NotImplemented
+        hasattr(t1, "__type_order__")
+        and (result := t1.__type_order__(t2)) is not NotImplemented
     ):
-        return result.order
+        return result
     elif (
-        hasattr(t2, "__typeorder__")
-        and (result := t2.__typeorder__(t1)) is not NotImplemented
+        hasattr(t2, "__type_order__")
+        and (result := t2.__type_order__(t1)) is not NotImplemented
     ):
-        return result.order.opposite()
+        return result.opposite()
 
     o1 = getattr(t1, "__origin__", None)
     o2 = getattr(t2, "__origin__", None)
@@ -135,14 +133,17 @@ def subclasscheck(t1, t2):
     if t1 == t2:
         return True
 
-    t1 = getattr(t1, "__proxy_for__", t1)
-    t2 = getattr(t2, "__proxy_for__", t2)
+    if (
+        hasattr(t2, "__is_supertype__")
+        and (result := t2.__is_supertype__(t1)) is not NotImplemented
+    ):
+        return result
 
     if (
-        hasattr(t2, "__typeorder__")
-        and (result := t2.__typeorder__(t1)) is not NotImplemented
+        hasattr(t1, "__is_subtype__")
+        and (result := t1.__is_subtype__(t2)) is not NotImplemented
     ):
-        return result.matches
+        return result
 
     o1 = getattr(t1, "__origin__", None)
     o2 = getattr(t2, "__origin__", None)

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/recode.py

@@ -373,6 +373,7 @@ class NameConverter(ast.NodeTransformer):
         self.call_next_sym = call_next_sym
         self.ovld_mangled = ovld_mangled
         self.code_mangled = code_mangled
+        self.count = count()
 
     def visit_Name(self, node):
         if node.id == self.recurse_sym:
@@ -396,15 +397,16 @@ class NameConverter(ast.NodeTransformer):
             return self.generic_visit(node)
 
         cn = node.func.id == self.call_next_sym
+        tmp = f"__TMP{next(self.count)}_"
 
         def _make_lookup_call(key, arg):
             value = ast.NamedExpr(
-                target=ast.Name(id=f"__TMP{key}", ctx=ast.Store()),
+                target=ast.Name(id=f"{tmp}{key}", ctx=ast.Store()),
                 value=self.visit(arg),
             )
             if self.analysis.lookup_for(key) == "self.map.transform":
                 func = ast.Attribute(
-                    value=ast.Name(id="__TMPM", ctx=ast.Load()),
+                    value=ast.Name(id=f"{tmp}M", ctx=ast.Load()),
                     attr="transform",
                     ctx=ast.Load(),
                 )
@@ -437,7 +439,7 @@ class NameConverter(ast.NodeTransformer):
             type_parts.insert(0, ast.Name(id=self.code_mangled, ctx=ast.Load()))
         method = ast.Subscript(
             value=ast.NamedExpr(
-                target=ast.Name(id="__TMPM", ctx=ast.Store()),
+                target=ast.Name(id=f"{tmp}M", ctx=ast.Store()),
                 value=ast.Attribute(
                     value=ast.Name(id=self.ovld_mangled, ctx=ast.Load()),
                     attr="map",
@@ -464,13 +466,13 @@ class NameConverter(ast.NodeTransformer):
         new_node = ast.Call(
             func=method,
             args=[
-                ast.Name(id=f"__TMP{i}", ctx=ast.Load())
+                ast.Name(id=f"{tmp}{i}", ctx=ast.Load())
                 for i, arg in enumerate(node.args)
             ],
             keywords=[
                 ast.keyword(
                     arg=kw.arg,
-                    value=ast.Name(id=f"__TMP{kw.arg}", ctx=ast.Load()),
+                    value=ast.Name(id=f"{tmp}{kw.arg}", ctx=ast.Load()),
                 )
                 for kw in node.keywords
             ],

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/typemap.py

@@ -1,6 +1,7 @@
 import inspect
 import math
 import typing
+from dataclasses import dataclass
 from itertools import count
 from types import CodeType
 
@@ -69,6 +70,27 @@ class TypeMap(dict):
             raise KeyError(obj_t)
 
 
+@dataclass
+class Candidate:
+    handler: object
+    priority: float
+    specificity: tuple
+    tiebreak: int
+
+    def sort_key(self):
+        return self.priority, sum(self.specificity), self.tiebreak
+
+    def dominates(self, other):
+        if self.priority > other.priority:
+            return True
+        elif self.specificity != other.specificity:
+            return all(
+                s1 >= s2 for s1, s2 in zip(self.specificity, other.specificity)
+            )
+        else:
+            return self.tiebreak > other.tiebreak
+
+
 class MultiTypeMap(dict):
     """Represents a mapping from tuples of types to handlers.
 
@@ -91,6 +113,7 @@ class MultiTypeMap(dict):
     def __init__(self, name="_ovld", key_error=KeyError):
         self.maps = {}
         self.priorities = {}
+        self.tiebreaks = {}
         self.dependent = {}
         self.type_tuples = {}
         self.empty = MISSING
@@ -155,7 +178,12 @@ class MultiTypeMap(dict):
                 specificities.setdefault(c, []).append(results[c])
 
         candidates = [
-            (c, self.priorities.get(c, 0), tuple(specificities[c]))
+            Candidate(
+                handler=c,
+                priority=self.priorities.get(c, 0),
+                specificity=tuple(specificities[c]),
+                tiebreak=self.tiebreaks.get(c, 0),
+            )
             for c in candidates
         ]
 
@@ -164,33 +192,30 @@ class MultiTypeMap(dict):
         # other possibilities on all arguments, so the sum of all specificities
         # has to be greater.
         # Note: priority is always more important than specificity
-        candidates.sort(key=lambda cspc: (cspc[1], sum(cspc[2])), reverse=True)
+
+        candidates.sort(key=Candidate.sort_key, reverse=True)
 
         self.all[obj_t_tup] = {
-            getattr(c[0], "__code__", None) for c in candidates
+            getattr(c.handler, "__code__", None) for c in candidates
         }
 
         processed = set()
 
         def _pull(candidates):
-            candidates = [
-                (c, a, b) for (c, a, b) in candidates if c not in processed
-            ]
+            candidates = [c for c in candidates if c.handler not in processed]
             if not candidates:
                 return
             rval = [candidates[0]]
-            c1, p1, spc1 = candidates[0]
-            for c2, p2, spc2 in candidates[1:]:
-                if p1 > p2 or (
-                    spc1 != spc2 and all(s1 >= s2 for s1, s2 in zip(spc1, spc2))
-                ):
+            c1 = candidates[0]
+            for c2 in candidates[1:]:
+                if c1.dominates(c2):
                     # Candidate 1 dominates candidate 2
                     continue
                 else:
-                    processed.add(c2)
+                    processed.add(c2.handler)
                     # Candidate 1 does not dominate candidate 2, so we add it
                     # to the list.
-                    rval.append((c2, p2, spc2))
+                    rval.append(c2)
             yield rval
             if len(rval) >= 1:
                 yield from _pull(candidates[1:])
@@ -212,6 +237,7 @@ class MultiTypeMap(dict):
             self.empty = entry
 
         self.priorities[handler] = sig.priority
+        self.tiebreaks[handler] = sig.tiebreak
         self.type_tuples[handler] = obj_t_tup
         self.dependent[handler] = any(
             isinstance(t[1] if isinstance(t, tuple) else t, DependentType)
@@ -257,15 +283,16 @@ class MultiTypeMap(dict):
         finished = False
         rank = 1
         for grp in self.mro(tuple(argt)):
-            grp.sort(key=lambda x: x[0].__name__)
+            grp.sort(key=lambda x: x.handler.__name__)
             match = [
                 dependent_match(
-                    self.type_tuples[handler], [*args, *kwargs.items()]
+                    self.type_tuples[c.handler], [*args, *kwargs.items()]
                 )
-                for handler, _, _ in grp
+                for c in grp
             ]
             ambiguous = len([m for m in match if m]) > 1
-            for m, (handler, prio, spec) in zip(match, grp):
+            for m, c in zip(match, grp):
+                handler = c.handler
                 color = "\033[0m"
                 if finished:
                     bullet = "--"
@@ -282,8 +309,8 @@ class MultiTypeMap(dict):
                         message = f"{handler.__name__} will be called first."
                         color = "\033[1;32m"
                     rank += 1
-                spec = ".".join(map(str, spec))
-                lvl = f"[{prio}:{spec}]"
+                spec = ".".join(map(str, c.specificity))
+                lvl = f"[{c.priority}:{spec}]"
                 width = 2 * len(args) + 6
                 print(f"{color}{bullet} {lvl:{width}} {handler.__name__}")
                 co = handler.__code__
@@ -320,8 +347,8 @@ class MultiTypeMap(dict):
 
         funcs = []
         for group in reversed(results):
-            handlers = [fn for (fn, _, _) in group]
-            dependent = any(self.dependent[fn] for (fn, _, _) in group)
+            handlers = [c.handler for c in group]
+            dependent = any(self.dependent[c.handler] for c in group)
             if dependent:
                 nxt = self.wrap_dependent(
                     obj_t_tup, handlers, group, funcs[-1] if funcs else None

{ovld-0.4.1 → ovld-0.4.3}/src/ovld/types.py

@@ -61,19 +61,31 @@ class MetaMC(type):
     def __init__(cls, name, order):
         pass
 
-    def __typeorder__(cls, other):
-        order = cls.order(other)
-        if isinstance(order, bool):
-            return NotImplemented
+    def __type_order__(cls, other):
+        results = cls.order(other)
+        if isinstance(results, TypeRelationship):
+            return results.order
         else:
-            return order
+            return NotImplemented
+
+    def __is_supertype__(cls, other):
+        results = cls.order(other)
+        if isinstance(results, bool):
+            return results
+        elif isinstance(results, TypeRelationship):
+            return results.supertype
+        else:  # pragma: no cover
+            return NotImplemented
+
+    def __is_subtype__(cls, other):
+        results = cls.order(other)
+        if isinstance(results, TypeRelationship):
+            return results.subtype
+        else:  # pragma: no cover
+            return NotImplemented
 
     def __subclasscheck__(cls, sub):
-        result = cls.order(sub)
-        if isinstance(result, TypeRelationship):
-            return result.order in (Order.MORE, Order.SAME)
-        else:
-            return result
+        return cls.__is_supertype__(sub)
 
 
 def class_check(condition):
@@ -164,7 +176,7 @@ def Exactly(cls, base_cls):
     """Match the class but not its subclasses."""
     return TypeRelationship(
         order=Order.LESS if cls is base_cls else typeorder(base_cls, cls),
-        matches=cls is base_cls,
+        supertype=cls is base_cls,
     )
 
 
@@ -184,11 +196,11 @@ def Intersection(cls, *classes):
     matches = all(subclasscheck(cls, t) for t in classes)
     compare = [x for t in classes if (x := typeorder(t, cls)) is not Order.NONE]
     if not compare:
-        return TypeRelationship(Order.NONE, matches=matches)
+        return TypeRelationship(Order.NONE, supertype=matches)
     elif any(x is Order.LESS or x is Order.SAME for x in compare):
-        return TypeRelationship(Order.LESS, matches=matches)
+        return TypeRelationship(Order.LESS, supertype=matches)
     else:
-        return TypeRelationship(Order.MORE, matches=matches)
+        return TypeRelationship(Order.MORE, supertype=matches)
 
 
 @parametrized_class_check

ovld-0.4.3/src/ovld/version.py

@@ -0,0 +1 @@
+version = "0.4.3"

ovld-0.4.3/tests/test_mro.py

@@ -0,0 +1,112 @@
+try:
+    from types import UnionType
+except ImportError:  # pragma: no cover
+    UnionType = None
+
+import sys
+from typing import Union
+
+from ovld.dependent import Dependent
+from ovld.mro import Order, subclasscheck, typeorder
+
+
+def identity(x):
+    return x
+
+
+class A:
+    pass
+
+
+class B(A):
+    pass
+
+
+class Prox:
+    _cls = object
+
+    def __class_getitem__(cls, other):
+        return type(f"Prox[{other.__name__}]", (Prox,), {"_cls": other})
+
+    @classmethod
+    def __is_supertype__(cls, other):
+        return subclasscheck(other, cls._cls)
+
+    @classmethod
+    def __is_subtype__(cls, other):
+        return subclasscheck(cls._cls, other)
+
+    @classmethod
+    def __type_order__(cls, other):
+        return typeorder(cls._cls, other)
+
+
+def test_subclasscheck():
+    assert subclasscheck(B, A)
+    assert not subclasscheck(A, B)
+    assert subclasscheck(A, A)
+    assert subclasscheck(A, object)
+    assert subclasscheck(A, Union[A, int])
+    assert subclasscheck(int, Union[A, int])
+
+
+def test_subclasscheck_generic():
+    assert subclasscheck(list[int], list[int])
+    assert subclasscheck(list[int], list[object])
+    assert not subclasscheck(list[object], list[int])
+
+
+def test_subclasscheck_type():
+    assert subclasscheck(type[int], type[object])
+
+
+def test_subclasscheck_type_union():
+    if sys.version_info >= (3, 10):
+        assert subclasscheck(type[int | str], type[UnionType])
+    assert subclasscheck(type[Union[int, str]], type[Union])
+    assert subclasscheck(type[Union], object)
+    assert not subclasscheck(object, type[Union])
+
+
+def test_typeorder_type_union():
+    if sys.version_info >= (3, 10):
+        assert typeorder(type[int | str], type[UnionType]) is Order.LESS
+    assert typeorder(type[Union[int, str]], type[Union]) is Order.LESS
+    assert typeorder(object, type[Union]) is Order.MORE
+
+
+def test_subclasscheck_dependent():
+    assert subclasscheck(B, Dependent[A, identity])
+    assert not subclasscheck(
+        Dependent[int, identity], Dependent[float, identity]
+    )
+
+
+def test_typeorder_dependent():
+    assert typeorder(Dependent[int, identity], float) is Order.NONE
+    assert (
+        typeorder(Dependent[int, identity], Dependent[A, identity])
+        is Order.NONE
+    )
+    assert (
+        typeorder(Dependent[int, identity], Dependent[float, identity])
+        is Order.NONE
+    )
+
+
+def test_subclasscheck_proxy():
+    assert subclasscheck(Prox[int], int)
+    assert subclasscheck(int, Prox[int])
+    assert subclasscheck(Prox[int], Prox)
+    assert not subclasscheck(Prox, Prox[int])
+
+    assert subclasscheck(Prox[B], A)
+    assert not subclasscheck(Prox[A], B)
+    assert subclasscheck(B, Prox[A])
+    assert not subclasscheck(A, Prox[B])
+    assert subclasscheck(Prox[B], Prox[A])
+
+    assert typeorder(Prox[int], int) is Order.SAME
+    assert typeorder(int, Prox[int]) is Order.SAME
+    assert typeorder(Prox[int], Prox) is Order.LESS
+    assert typeorder(Prox, Prox[int]) is Order.MORE