ovld 0.5.6__py3-none-any.whl → 0.5.7__py3-none-any.whl

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/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/version.py

@@ -1 +1 @@
-version = "0.5.6"
+version = "0.5.7"

{ovld-0.5.6.dist-info → ovld-0.5.7.dist-info}/METADATA

@@ -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.dist-info → ovld-0.5.7.dist-info}/RECORD

@@ -1,18 +1,18 @@
 ovld/__init__.py,sha256=JuCM8Sj65gobV0KYyLr95cSI23Pi6RYZ7X3_F3fdsSw,1821
 ovld/abc.py,sha256=4qpZyYwI8dWgY1Oiv5FhdKg2uzNcyWxIpGmGJVcjXrs,1177
 ovld/codegen.py,sha256=27tmamlanuTPDT-x31ISyqP0wGKW9BCFZJGVyq9qLg8,9728
-ovld/core.py,sha256=HEREHblKcjM9dhFBr0FNwUCyec7o-9XjCsCfJ23SnNw,17544
+ovld/core.py,sha256=WqZ1lvcAGSri02XZeY73Bj5AKB9RYBCAvHLbyns8u68,17792
 ovld/dependent.py,sha256=JIgsc_5ddPH51_2IrZ6JW6bWE5RyrrrOwR2e9UvDhZ4,8922
 ovld/medley.py,sha256=0fseIntzJRCPYXq-tmnxgy5ipNa4ZxR0D_6So0xstdQ,12729
 ovld/mro.py,sha256=Aw1r5Zz7V9cVBDwWzQ-WNnbpBwoGztgbw3wLAyS6Y60,4863
 ovld/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ovld/recode.py,sha256=vXg9XLExp_9LdAHO0JWR4wvwHhpOLu2Xcrg9ZYg1nms,16407
 ovld/signatures.py,sha256=Q8JucSOun0ESGx14aWtHtBzLEiM6FxY5HP3imyqXoDo,8984
-ovld/typemap.py,sha256=EH3oM_QmX-SHLEz14saVrQtRlqG_ltPyJGORLvcGOFk,13520
+ovld/typemap.py,sha256=wkLuCc6xa2VZJOMaAhuYYgnNrywhovkQwbkBnoRfCsY,13985
 ovld/types.py,sha256=CRL6Vuzg5moXgAAhIj2698GvZoyF4HWbUDYz2hKt6us,13373
 ovld/utils.py,sha256=cyy9pcuMhmo1_UdPonH9JT6B9QlI4oH6_JK89cM3_gk,5046
-ovld/version.py,sha256=FtfC8ptaFH0Unc72bPRynMH_N62bxa4tnazGgIcgnTY,18
-ovld-0.5.6.dist-info/METADATA,sha256=NuqYyUraNAzGzrl8XUVET_xO6xBSzbPhy5F5AtzITWk,9383
-ovld-0.5.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ovld-0.5.6.dist-info/licenses/LICENSE,sha256=cSwNTIzd1cbI89xt3PeZZYJP2y3j8Zus4bXgo4svpX8,1066
-ovld-0.5.6.dist-info/RECORD,,
+ovld/version.py,sha256=06EkKCZh0our2EHc5Ssv0FmkpTsQ75viNNVyU74k-Zg,18
+ovld-0.5.7.dist-info/METADATA,sha256=8kgc5SptJGDMMR4twLX9cB88rnMMC-GvuUn2Z8mCmgE,10458
+ovld-0.5.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ovld-0.5.7.dist-info/licenses/LICENSE,sha256=cSwNTIzd1cbI89xt3PeZZYJP2y3j8Zus4bXgo4svpX8,1066
+ovld-0.5.7.dist-info/RECORD,,