ovld 0.5.6__tar.gz → 0.5.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ovld
-Version: 0.5.6
+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.6 → 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.6 → 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.6 → ovld-0.5.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ovld"
-version = "0.5.6"
+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.6 → 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.6 → ovld-0.5.7}/src/ovld/typemap.py

@@ -1,6 +1,7 @@
 import inspect
 import math
 from dataclasses import dataclass
+from functools import partial
 from itertools import count
 from types import CodeType
 
@@ -248,7 +249,7 @@ class MultiTypeMap(dict):
             co = h.__code__
             print(f"{'':{width - 2}} @ {co.co_filename}:{co.co_firstlineno}")
 
-    def display_resolution(self, *args, **kwargs):
+    def _resolve_all_helper(self, *args, **kwargs):
         def dependent_match(tup, args):
             for t, a in zip(tup, args):
                 if isinstance(t, tuple):
@@ -258,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.7/src/ovld/version.py

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

{ovld-0.5.6 → 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
 
@@ -1691,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):