ovld 0.5.5__tar.gz → 0.5.7__tar.gz

{ovld-0.5.5 → ovld-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ovld
-Version: 0.5.5
+Version: 0.5.7
 Summary: Overloading Python functions
 Project-URL: Homepage, https://ovld.readthedocs.io/en/latest/
 Project-URL: Documentation, https://ovld.readthedocs.io/en/latest/
@@ -22,13 +22,53 @@ With ovld, you can write a version of the same function for every type signature
 
 * ⚡️ **[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), [**mixins**](https://ovld.readthedocs.io/en/latest/usage/#mixins) and [**medleys**](https://ovld.readthedocs.io/en/latest/medley) 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.
+* 🦄 **[Value-based dispatch](https://ovld.readthedocs.io/en/latest/dependent/):** Overloaded functions can depend on more than argument types: they can depend on actual values.
 * 🔑 **[Extensive](https://ovld.readthedocs.io/en/latest/usage/#keyword-arguments):** Dispatch on functions, methods, positional arguments and even keyword arguments (with some restrictions).
 * ⚙️ **[Codegen](https://ovld.readthedocs.io/en/latest/codegen/):** (Experimental) For advanced use cases, you can generate custom code for overloads.
 
+Install with `pip install ovld`
+
+
 ## Example
 
-Here's a function that recursively adds lists, tuples and dictionaries:
+Define one version of your function for each type signature you want to support. `ovld` supports all basic types, plus literals and value-dependent types such as `Regexp`.
+
+```python
+from ovld import ovld
+from ovld.dependent import Regexp
+from typing import Literal
+
+@ovld
+def f(x: str):
+    return f"The string {x!r}"
+
+@ovld
+def f(x: int):
+    return f"The number {x}"
+
+@ovld
+def f(x: int, y: int):
+    return "Two numbers!"
+
+@ovld
+def f(x: Literal[0]):
+    return "zero"
+
+@ovld
+def f(x: Regexp[r"^X"]):
+    return "A string that starts with X"
+
+assert f("hello") == "The string 'hello'"
+assert f(3) == "The number 3"
+assert f(1, 2) == "Two numbers!"
+assert f(0) == "zero"
+assert f("XSECRET") == "A string that starts with X"
+```
+
+
+## Recursive example
+
+`ovld` shines particularly with recursive definitions, for example tree maps or serialization. Here we define a function that recursively adds lists of lists and integers:
 
 ```python
 from ovld import ovld, recurse
@@ -38,18 +78,19 @@ 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))
+def add(x: list, y: int):
+    return [recurse(a, y) for a in x]
 
 @ovld
-def add(x: dict, y: dict):
-    return {k: recurse(v, y[k]) for k, v in x.items()}
+def add(x: int, y: list):
+    return [recurse(x, a) for a in y]
 
 @ovld
-def add(x: object, y: object):
+def add(x: int, y: int):
     return x + y
 
 assert add([1, 2], [3, 4]) == [4, 6]
+assert add([1, 2, [3]], 7) == [8, 9, [10]]
 ```
 
 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.
@@ -63,7 +104,7 @@ A *variant* of an `ovld` is a copy of the `ovld`, with some methods added or cha
 
 ```python
 @add.variant
-def mul(x: object, y: object):
+def mul(x: int, y: int):
     return x * y
 
 assert mul([1, 2], [3, 4]) == [3, 8]
@@ -92,9 +133,9 @@ 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.
+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 line, in order of priority and specificity.
 
-The pattern you see above is how you may wrap each call with some generic behavior. For instance, if you did something like that:
+The pattern you see above is how you may wrap each call with some generic behavior. For instance, if you did something like this:
 
 ```python
 @f.variant(priority=1000)
@@ -103,12 +144,12 @@ def f2(x: object)
     return call_next(x)
 ```
 
-You would effectively be creating a clone of `f` that traces every call.
+The above is effectively a clone of `f` that traces every call. Useful for debugging.
 
 
 ## 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:
+A dependent type is a type that depends on a value. This enables dispatching based on the actual value of an argument. The simplest example of a dependent type is `typing.Literal[value]`, which matches one single value. `ovld` also supports `Dependent[bound, check]` for arbitrary checks. For example, this definition of factorial:
 
 ```python
 from typing import Literal

{ovld-0.5.5 → ovld-0.5.7}/README.md

@@ -9,13 +9,53 @@ With ovld, you can write a version of the same function for every type signature
 
 * ⚡️ **[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), [**mixins**](https://ovld.readthedocs.io/en/latest/usage/#mixins) and [**medleys**](https://ovld.readthedocs.io/en/latest/medley) 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.
+* 🦄 **[Value-based dispatch](https://ovld.readthedocs.io/en/latest/dependent/):** Overloaded functions can depend on more than argument types: they can depend on actual values.
 * 🔑 **[Extensive](https://ovld.readthedocs.io/en/latest/usage/#keyword-arguments):** Dispatch on functions, methods, positional arguments and even keyword arguments (with some restrictions).
 * ⚙️ **[Codegen](https://ovld.readthedocs.io/en/latest/codegen/):** (Experimental) For advanced use cases, you can generate custom code for overloads.
 
+Install with `pip install ovld`
+
+
 ## Example
 
-Here's a function that recursively adds lists, tuples and dictionaries:
+Define one version of your function for each type signature you want to support. `ovld` supports all basic types, plus literals and value-dependent types such as `Regexp`.
+
+```python
+from ovld import ovld
+from ovld.dependent import Regexp
+from typing import Literal
+
+@ovld
+def f(x: str):
+    return f"The string {x!r}"
+
+@ovld
+def f(x: int):
+    return f"The number {x}"
+
+@ovld
+def f(x: int, y: int):
+    return "Two numbers!"
+
+@ovld
+def f(x: Literal[0]):
+    return "zero"
+
+@ovld
+def f(x: Regexp[r"^X"]):
+    return "A string that starts with X"
+
+assert f("hello") == "The string 'hello'"
+assert f(3) == "The number 3"
+assert f(1, 2) == "Two numbers!"
+assert f(0) == "zero"
+assert f("XSECRET") == "A string that starts with X"
+```
+
+
+## Recursive example
+
+`ovld` shines particularly with recursive definitions, for example tree maps or serialization. Here we define a function that recursively adds lists of lists and integers:
 
 ```python
 from ovld import ovld, recurse
@@ -25,18 +65,19 @@ 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))
+def add(x: list, y: int):
+    return [recurse(a, y) for a in x]
 
 @ovld
-def add(x: dict, y: dict):
-    return {k: recurse(v, y[k]) for k, v in x.items()}
+def add(x: int, y: list):
+    return [recurse(x, a) for a in y]
 
 @ovld
-def add(x: object, y: object):
+def add(x: int, y: int):
     return x + y
 
 assert add([1, 2], [3, 4]) == [4, 6]
+assert add([1, 2, [3]], 7) == [8, 9, [10]]
 ```
 
 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.
@@ -50,7 +91,7 @@ A *variant* of an `ovld` is a copy of the `ovld`, with some methods added or cha
 
 ```python
 @add.variant
-def mul(x: object, y: object):
+def mul(x: int, y: int):
     return x * y
 
 assert mul([1, 2], [3, 4]) == [3, 8]
@@ -79,9 +120,9 @@ 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.
+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 line, in order of priority and specificity.
 
-The pattern you see above is how you may wrap each call with some generic behavior. For instance, if you did something like that:
+The pattern you see above is how you may wrap each call with some generic behavior. For instance, if you did something like this:
 
 ```python
 @f.variant(priority=1000)
@@ -90,12 +131,12 @@ def f2(x: object)
     return call_next(x)
 ```
 
-You would effectively be creating a clone of `f` that traces every call.
+The above is effectively a clone of `f` that traces every call. Useful for debugging.
 
 
 ## 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:
+A dependent type is a type that depends on a value. This enables dispatching based on the actual value of an argument. The simplest example of a dependent type is `typing.Literal[value]`, which matches one single value. `ovld` also supports `Dependent[bound, check]` for arbitrary checks. For example, this definition of factorial:
 
 ```python
 from typing import Literal

{ovld-0.5.5 → ovld-0.5.7}/docs/index.md

@@ -12,7 +12,44 @@ With ovld, you can write a version of the same function for every type signature
 
 ## Example
 
-Here's a function that adds lists, tuples and dictionaries:
+Define one version of your function for each type signature you want to support. `ovld` supports all basic types, plus literals and value-dependent types such as `Regexp`.
+
+```python
+from ovld import ovld
+from ovld.dependent import Regexp
+from typing import Literal
+
+@ovld
+def f(x: str):
+    return f"The string {x!r}"
+
+@ovld
+def f(x: int):
+    return f"The number {x}"
+
+@ovld
+def f(x: int, y: int):
+    return "Two numbers!"
+
+@ovld
+def f(x: Literal[0]):
+    return "zero"
+
+@ovld
+def f(x: Regexp[r"^X"]):
+    return "A string that starts with X"
+
+assert f("hello") == "The string 'hello'"
+assert f(3) == "The number 3"
+assert f(1, 2) == "Two numbers!"
+assert f(0) == "zero"
+assert f("XSECRET") == "A string that starts with X"
+```
+
+
+## Recursive example
+
+`ovld` shines particularly with recursive definitions, for example tree maps or serialization. Here we define a function that recursively adds lists of lists and integers:
 
 ```python
 from ovld import ovld, recurse
@@ -22,16 +59,19 @@ 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))
+def add(x: list, y: int):
+    return [recurse(a, y) for a in x]
 
 @ovld
-def add(x: dict, y: dict):
-    return {k: recurse(v, y[k]) for k, v in x.items()}
+def add(x: int, y: list):
+    return [recurse(x, a) for a in y]
 
 @ovld
-def add(x: object, y: object):
+def add(x: int, y: int):
     return x + y
+
+assert add([1, 2], [3, 4]) == [4, 6]
+assert add([1, 2, [3]], 7) == [8, 9, [10]]
 ```
 
 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:
@@ -43,7 +83,7 @@ A **variant** of an `ovld` is a copy of the `ovld`, with some methods added or c
 
 ```python
 @add.variant
-def mul(x: object, y: object):
+def mul(x: int, y: int):
     return x * y
 
 assert mul([1, 2], [3, 4]) == [3, 8]

{ovld-0.5.5 → ovld-0.5.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ovld"
-version = "0.5.5"
+version = "0.5.7"
 description = "Overloading Python functions"
 authors = [
     { name = "Olivier Breuleux", email = "breuleux@gmail.com" }
@@ -44,6 +44,8 @@ line-length = 95
 [tool.ruff.lint]
 extend-select = ["I"]
 ignore = ["E241", "F722", "E501", "E203", "F811", "F821"]
+# Ignore these for now, ruff reports SyntaxError because they use Python 3.10+ features
+exclude = ["benchmarks/test_calc.py", "benchmarks/test_tweaknum.py"]
 
 [tool.pytest.ini_options]
 minversion = "6.0"

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/core.py

@@ -45,6 +45,7 @@ def bootstrap_dispatch(ov, name):
     dispatch.register = ov.register
     dispatch.resolve_for_values = ov.resolve_for_values
     dispatch.resolve = ov.resolve
+    dispatch.resolve_all = ov.resolve_all
     dispatch.copy = ov.copy
     dispatch.variant = ov.variant
     dispatch.display_methods = ov.display_methods
@@ -250,6 +251,11 @@ class Ovld:
         else:
             return self.map[args]
 
+    def resolve_all(self, *args, **kwargs):
+        """Yield all methods that match the arguments, in priority order."""
+        self.ensure_compiled()
+        return self.map.resolve_all(*args, **kwargs)
+
     def register_signature(self, sig, orig_fn):
         """Register a function for the given signature."""
         fn = adapt_function(orig_fn, self, f"{self.__name__}[{sigstring(sig.types)}]")

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/dependent.py

@@ -15,22 +15,15 @@ from .types import (
     Intersection,
     Order,
     clsstring,
-    get_args,
     normalize_type,
     subclasscheck,
     typeorder,
 )
 
 
-def is_dependent(t):
-    if isinstance(t, DependentType):
-        return True
-    elif any(is_dependent(subt) for subt in get_args(t)):
-        return True
-    return False
-
-
 class DependentType(type):
+    __dependent__ = True
+
     exclusive_type = False
     keyable_type = False
     bound_is_name = False

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/mro.py

@@ -3,7 +3,7 @@ from enum import Enum
 from graphlib import TopologicalSorter
 from typing import get_args, get_origin
 
-from .utils import UnionTypes
+from .utils import UnionTypes, is_dependent
 
 
 class Order(Enum):
@@ -123,6 +123,11 @@ def subclasscheck(t1, t2):
     ):
         return result
 
+    if is_dependent(t2):
+        # t2's instancecheck could return anything, and unless it defines
+        # __is_supertype__ or __is_subtype__ the bound devolves to object
+        return True
+
     if t2 in UnionTypes:
         return isinstance(t1, t2)
 

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/recode.py

@@ -12,7 +12,7 @@ from .codegen import (
     rename_function,
     transfer_function,
 )
-from .utils import MISSING, NameDatabase, SpecialForm, UsageError, subtler_type
+from .utils import MISSING, NameDatabase, SpecialForm, UsageError, is_dependent, subtler_type
 
 recurse = SpecialForm("recurse")
 call_next = SpecialForm("call_next")
@@ -160,8 +160,6 @@ def generate_dispatch(ov, arganal):
 
 
 def generate_dependent_dispatch(tup, handlers, next_call, slf, name, err, nerr):
-    from .dependent import is_dependent
-
     def to_dict(tup):
         return dict(
             entry if isinstance(entry, tuple) else (i, entry) for i, entry in enumerate(tup)

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/typemap.py

@@ -1,12 +1,13 @@
 import inspect
 import math
 from dataclasses import dataclass
+from functools import partial
 from itertools import count
 from types import CodeType
 
 from .mro import sort_types
 from .recode import generate_dependent_dispatch
-from .utils import MISSING, CodegenInProgress, subtler_type
+from .utils import MISSING, CodegenInProgress, is_dependent, subtler_type
 
 
 class TypeMap(dict):
@@ -213,8 +214,6 @@ class MultiTypeMap(dict):
             sig: A Signature object.
             handler: A function to handle the tuple.
         """
-        from .dependent import is_dependent
-
         self.clear()
 
         obj_t_tup = sig.types
@@ -250,9 +249,7 @@ class MultiTypeMap(dict):
             co = h.__code__
             print(f"{'':{width - 2}} @ {co.co_filename}:{co.co_firstlineno}")
 
-    def display_resolution(self, *args, **kwargs):
-        from .dependent import is_dependent
-
+    def _resolve_all_helper(self, *args, **kwargs):
         def dependent_match(tup, args):
             for t, a in zip(tup, args):
                 if isinstance(t, tuple):
@@ -262,21 +259,35 @@ class MultiTypeMap(dict):
                     return False
             return True
 
-        message = "No method will be called."
         argt = [
             *map(subtler_type, args),
             *[(k, subtler_type(v)) for k, v in kwargs.items()],
         ]
-        finished = False
-        rank = 1
         for grp in self.mro(tuple(argt)):
-            grp.sort(key=lambda x: x.handler.__name__)
-            match = [
-                dependent_match(self.type_tuples[c.base_handler], [*args, *kwargs.items()])
+            yield [
+                (
+                    c,
+                    dependent_match(
+                        self.type_tuples[c.base_handler], [*args, *kwargs.items()]
+                    ),
+                )
                 for c in grp
             ]
-            ambiguous = len([m for m in match if m]) > 1
-            for m, c in zip(match, grp):
+
+    def resolve_all(self, *args, **kwargs):
+        for grp in self._resolve_all_helper(*args, **kwargs):
+            for c, m in grp:
+                if m:
+                    yield partial(c.handler, *args, **kwargs)
+
+    def display_resolution(self, *args, **kwargs):
+        message = "No method will be called."
+        finished = False
+        rank = 1
+        for grp in self._resolve_all_helper(*args, **kwargs):
+            grp.sort(key=lambda x: x[0].handler.__name__)
+            ambiguous = len([m for _, m in grp if m]) > 1
+            for c, m in grp:
                 handler = c.handler
                 color = "\033[0m"
                 if finished:

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/types.py

@@ -10,14 +10,9 @@ from .codegen import Code
 from .mro import Order, TypeRelationship, subclasscheck, typeorder
 from .recode import generate_checking_code
 from .typemap import TypeMap
-from .utils import UnionType, UnionTypes, UsageError, clsstring
+from .utils import UnionType, UnionTypes, UsageError, clsstring, get_args
 
-
-def get_args(tp):
-    args = getattr(tp, "__args__", None)
-    if not isinstance(args, tuple):
-        args = ()
-    return args
+NoneType = type(None)
 
 
 def eval_annotation(t, ctx, locals, catch=False):
@@ -90,6 +85,8 @@ class TypeNormalizer:
             raise UsageError(
                 f"Dependent type {t} has not been given a type bound. Please use Dependent[<bound>, {t}] instead."
             )
+        elif t is None:
+            return NoneType
         else:
             return t
 
@@ -103,6 +100,8 @@ def _(self, t, fn):
 
 
 class MetaMC(type):
+    __dependent__ = False
+
     def __new__(T, name, handler):
         return super().__new__(T, name, (), {"_handler": handler})
 

{ovld-0.5.5 → ovld-0.5.7}/src/ovld/utils.py

@@ -4,6 +4,7 @@ import builtins
 import functools
 import re
 import typing
+from abc import ABCMeta
 from itertools import count
 
 _builtins_dict = vars(builtins)
@@ -183,3 +184,31 @@ class NameDatabase:
         return name
 
     __getitem__ = get
+
+
+def get_args(tp):
+    args = getattr(tp, "__args__", None)
+    if not isinstance(args, tuple):
+        args = ()
+    return args
+
+
+_standard_instancechecks = {
+    type.__instancecheck__,
+    GenericAlias.__instancecheck__,
+    type(list[object]).__instancecheck__,
+    ABCMeta.__instancecheck__,
+    type(typing.Protocol).__instancecheck__,
+}
+
+
+def is_dependent(t):
+    if any(is_dependent(subt) for subt in get_args(t)):
+        return True
+    elif hasattr(t, "__dependent__"):
+        return t.__dependent__
+    elif not isinstance(t, type):
+        return False
+    elif type(t).__instancecheck__ not in _standard_instancechecks:
+        return True
+    return False

ovld-0.5.7/src/ovld/version.py

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

{ovld-0.5.5 → ovld-0.5.7}/tests/test_dependent.py

@@ -350,3 +350,31 @@ def test_keyed_plus_other():
     assert f(0, 50) == "yes"
     assert f(3, 50) == "yes"
     assert f(0, 150) == "no"
+
+
+class Lettered(type):
+    def __instancecheck__(cls, x):
+        return cls.letter in (getattr(x, "__name__", None) or str(x))
+
+
+LetterF = Lettered("LetterF", (), {"letter": "f"})
+LetterX = Lettered("LetterX", (), {"letter": "x"})
+
+
+def test_arbitrary_instancecheck():
+    @ovld
+    def f(x: LetterX):
+        return "X-TREME"
+
+    @ovld
+    def f(x: LetterF):
+        return "fudged"
+
+    @ovld
+    def f(x: object):
+        return False
+
+    assert f(next) == "X-TREME"
+    assert f("wow") is False
+    assert f("extreme") == "X-TREME"
+    assert f(filter) == "fudged"

{ovld-0.5.5 → ovld-0.5.7}/tests/test_ovld.py

@@ -19,7 +19,7 @@ from ovld import (
     recurse,
     resolve,
 )
-from ovld.dependent import Dependent, Equals, StartsWith
+from ovld.dependent import Dependent, Equals, Regexp, StartsWith
 from ovld.types import UnionTypes
 from ovld.utils import MISSING, UsageError
 
@@ -324,6 +324,19 @@ def test_optional():
     assert f(1.0) == "f"
 
 
+def test_none():
+    @ovld
+    def f(x: None):
+        return "null"
+
+    @ovld
+    def f(x: object):
+        return "X"
+
+    assert f(None) == "null"
+    assert f(123) == "X"
+
+
 def test_abstract_types():
     from collections.abc import Iterable
 
@@ -1678,6 +1691,33 @@ def test_keywords_recurse():
     assert f([1, 2, 3], factor=3) == [3, 6, 9]
 
 
+def test_resolve_all():
+    @ovld
+    def f(x: str):
+        return "str"
+
+    @ovld(priority=7)
+    def f(x: str):
+        return "MAX"
+
+    @ovld(priority=1)
+    def f(x: Regexp["^hello"]):
+        return "hello"
+
+    @ovld
+    def f(x: Regexp["world$"]):
+        return "world"
+
+    @ovld
+    def f(x: int):
+        return "int"
+
+    assert [t() for t in f.resolve_all("hello world")] == ["MAX", "hello", "world", "str"]
+    assert [t() for t in f.resolve_all("hello, you!")] == ["MAX", "hello", "str"]
+    assert [t() for t in f.resolve_all(73)] == ["int"]
+    assert [t() for t in f.resolve_all(object())] == []
+
+
 def test_passing_types_to_normal_func():
     @ovld
     def f(x):