ovld 0.4.0__tar.gz → 0.4.2__tar.gz

{ovld-0.4.0 → ovld-0.4.2}/PKG-INFO

@@ -1,7 +1,10 @@
 Metadata-Version: 2.3
 Name: ovld
-Version: 0.4.0
+Version: 0.4.2
 Summary: Overloading Python functions
+Project-URL: Homepage, https://ovld.readthedocs.io/en/latest/
+Project-URL: Documentation, https://ovld.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/breuleux/ovld
 Author-email: Olivier Breuleux <breuleux@gmail.com>
 License-Expression: MIT
 License-File: LICENSE

{ovld-0.4.0 → ovld-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ovld"
-version = "0.4.0"
+version = "0.4.2"
 description = "Overloading Python functions"
 authors = [
     { name = "Olivier Breuleux", email = "breuleux@gmail.com" }
@@ -8,10 +8,13 @@ authors = [
 dependencies = []
 readme = "README.md"
 license = "MIT"
-homepage = "https://github.com/breuleux/ovld"
-repository = "https://github.com/breuleux/ovld"
 requires-python = ">= 3.9"
 
+[project.urls]
+Homepage = "https://ovld.readthedocs.io/en/latest/"
+Documentation = "https://ovld.readthedocs.io/en/latest/"
+Repository = "https://github.com/breuleux/ovld"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -41,9 +44,6 @@ line-length = 80
 extend-select = ["I"]
 ignore = ["E241", "F722", "E501", "E203", "F811", "F821"]
 
-[tool.ruff.lint.per-file-ignores]
-"__init__.py" = ["F401", "F403"]
-
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = "--benchmark-columns=median,min,max"

ovld-0.4.2/reddit.md

@@ -0,0 +1,54 @@
+## What My Project Does
+
+`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.2/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.0 → ovld-0.4.2}/src/ovld/__init__.py

@@ -70,4 +70,5 @@ __all__ = [
     "keyword_decorator",
     "call_next",
     "recurse",
+    "__version__",
 ]

{ovld-0.4.0 → ovld-0.4.2}/src/ovld/core.py

@@ -20,12 +20,6 @@ from .typemap import MultiTypeMap, is_type_of_type
 from .types import normalize_type
 from .utils import UsageError, keyword_decorator
 
-try:
-    from types import UnionType
-except ImportError:  # pragma: no cover
-    UnionType = None
-
-
 _current_id = itertools.count()
 
 
@@ -91,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
@@ -399,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"
@@ -509,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.0 → ovld-0.4.2}/src/ovld/mro.py

@@ -25,6 +25,16 @@ class TypeRelationship:
     matches: bool = None
 
 
+def _issubclass(t1, t2):
+    try:
+        return issubclass(t1, t2)
+    except TypeError:
+        try:
+            return isinstance(t1, t2)
+        except TypeError:  # pragma: no cover
+            return False
+
+
 def typeorder(t1, t2):
     """Order relation between two types.
 
@@ -56,6 +66,8 @@ def typeorder(t1, t2):
     o2 = getattr(t2, "__origin__", None)
 
     if o2 is typing.Union:
+        if t1 is typing.Union:
+            return Order.MORE
         compare = [
             x for t in t2.__args__ if (x := typeorder(t1, t)) is not Order.NONE
         ]
@@ -105,8 +117,8 @@ def typeorder(t1, t2):
             # Not sure when t1 != t2 and that happens
             return Order.SAME
 
-    sx = issubclass(t1, t2)
-    sy = issubclass(t2, t1)
+    sx = _issubclass(t1, t2)
+    sy = _issubclass(t2, t1)
     if sx and sy:  # pragma: no cover
         # Not sure when t1 != t2 and that happens
         return Order.SAME
@@ -136,14 +148,23 @@ def subclasscheck(t1, t2):
     o2 = getattr(t2, "__origin__", None)
 
     if o2 is typing.Union:
-        return any(subclasscheck(t1, t) for t in t2.__args__)
+        return t1 is typing.Union or any(
+            subclasscheck(t1, t) for t in t2.__args__
+        )
     elif o1 is typing.Union:
-        return all(subclasscheck(t, t2) for t in t1.__args__)
+        return t2 is typing.Union or all(
+            subclasscheck(t, t2) for t in t1.__args__
+        )
+
+    if not isinstance(o1, type):
+        o1 = None
+    if not isinstance(o2, type):
+        o2 = None
 
     if o1 or o2:
         o1 = o1 or t1
         o2 = o2 or t2
-        if issubclass(o1, o2):
+        if _issubclass(o1, o2):
             if o2 is t2:  # pragma: no cover
                 return True
             else:
@@ -157,7 +178,7 @@ def subclasscheck(t1, t2):
         else:
             return False
     else:
-        return issubclass(t1, t2)
+        return _issubclass(t1, t2)
 
 
 def sort_types(cls, avail):

{ovld-0.4.0 → ovld-0.4.2}/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.0 → ovld-0.4.2}/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.2/src/ovld/version.py

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

ovld-0.4.2/tests/test_mro.py

@@ -0,0 +1,51 @@
+try:
+    from types import UnionType
+except ImportError:  # pragma: no cover
+    UnionType = None
+
+import sys
+from typing import Union
+
+from ovld.mro import Order, subclasscheck, typeorder
+
+
+class A:
+    pass
+
+
+class B(A):
+    pass
+
+
+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

{ovld-0.4.0 → ovld-0.4.2}/tests/test_ovld.py

@@ -559,6 +559,22 @@ def test_recurse_method():
     assert C().f([1, 2, 3]) == [2, 3, 4]
 
 
+def test_recurse_nested():
+    @ovld
+    def f(xs: list):
+        return recurse(sum(recurse(x) for x in xs))
+
+    @ovld
+    def f(x: str):
+        return len(x)
+
+    @ovld
+    def f(x: int):
+        return x * x
+
+    assert f(["a", "bbb", "cc"]) == 36
+
+
 def test_call_next():
     f = Ovld()
 
@@ -573,6 +589,44 @@ def test_call_next():
     assert f(3) == 8
 
 
+def test_call_next_unrelated():
+    f = Ovld()
+
+    @f.register
+    def f(x: int):
+        return f.next(str(x))
+
+    @f.register
+    def f(x: str):
+        return x * 2
+
+    @f.register
+    def f(x: object):
+        return "no"
+
+    assert f(3) == "33"
+    for k, v in f.map.items():
+        print(k, v)
+
+
+def test_call_next_same_priority():
+    f = Ovld()
+
+    @f.register
+    def f(x: int):
+        return x * 2
+
+    @f.register
+    def f(x: int):
+        return call_next(x + 1)
+
+    @f.register
+    def f(x: int):
+        return call_next(-x)
+
+    assert f(5) == -8
+
+
 def test_recurse_renamed():
     f = Ovld()
 
@@ -1540,11 +1594,16 @@ def test_keywords():
     def f(name: str, *, hello: int):
         return "hello" * hello + " " + name
 
+    @ovld
+    def f(name: str, *, hello: str):
+        return hello + " " + name
+
     @f.register
     def f(name: str, *, goodbye: int):
         return "goodbye" * goodbye + " " + name
 
     assert f("Helena", hello=3) == "hellohellohello Helena"
+    assert f("Helena", hello="Bonjour") == "Bonjour Helena"
     assert f("Gertrude", goodbye=2) == "goodbyegoodbye Gertrude"
 
 
@@ -1560,6 +1619,14 @@ def test_keywords_recurse():
     assert f([1, 2, 3], factor=3) == [3, 6, 9]
 
 
+def test_passing_types_to_normal_func():
+    @ovld
+    def f(x):
+        return x
+
+    assert f(list[int]) == list[int]
+
+
 def test_doc(file_regression):
     @ovld
     def mushroom(x: int):

{ovld-0.4.0 → ovld-0.4.2}/tests/test_typemap.py

@@ -31,7 +31,7 @@ def _get(tm, *key):
     try:
         return [tm[key]]
     except KeyError as err:
-        return [x for x, _, _ in err.args[1]]
+        return [x.handler for x in err.args[1]]
 
 
 def test_empty():

{ovld-0.4.0 → ovld-0.4.2}/todo.q

@@ -12,6 +12,7 @@
 * Properly identify nested DependentTypes when figuring out if type is dependent
 * Optimize the itertools.product in mro
 * Context variable to turn off code generation
+* Add second priority level corresponding to definition order
 
 
 = DONE

{ovld-0.4.0 → ovld-0.4.2}/uv.lock

@@ -330,7 +330,7 @@ wheels = [
 
 [[package]]
 name = "ovld"
-version = "0.3.9"
+version = "0.4.1"
 source = { editable = "." }
 
 [package.dev-dependencies]

ovld-0.4.0/src/ovld/version.py

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