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

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

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

@@ -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.7.dist-info/RECORD

@@ -0,0 +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=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=wkLuCc6xa2VZJOMaAhuYYgnNrywhovkQwbkBnoRfCsY,13985
+ovld/types.py,sha256=CRL6Vuzg5moXgAAhIj2698GvZoyF4HWbUDYz2hKt6us,13373
+ovld/utils.py,sha256=cyy9pcuMhmo1_UdPonH9JT6B9QlI4oH6_JK89cM3_gk,5046
+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,,

ovld-0.5.5.dist-info/RECORD

@@ -1,18 +0,0 @@
-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/dependent.py,sha256=h3j4oQYTQfGqMzggWlLV6TpojX_GtYRFWAO0GcMB0Zs,9085
-ovld/medley.py,sha256=0fseIntzJRCPYXq-tmnxgy5ipNa4ZxR0D_6So0xstdQ,12729
-ovld/mro.py,sha256=LXHkP_28J9EwM9IrXYraYI0qm4dHWkDKCgkXn0u_YCo,4655
-ovld/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ovld/recode.py,sha256=ZVqD3sCu_myaFj3lKPCMjFBf1pTdTAAd3NJdsqtLYuU,16434
-ovld/signatures.py,sha256=Q8JucSOun0ESGx14aWtHtBzLEiM6FxY5HP3imyqXoDo,8984
-ovld/typemap.py,sha256=5Pro1Ee60fH4L7NW7k5nbN5EfDygA0LFHcI6o3mCagI,13596
-ovld/types.py,sha256=0hkhAR5_5793NABdrM-fP1dSJBhYof85FILKqVP2YMg,13392
-ovld/utils.py,sha256=fD20RWWGwI3Z8q5DvrdCPDA_Wm1uiyfCZLLL2IM9ZJw,4348
-ovld/version.py,sha256=v9c8T1qB0Dxuq0vdkPvh2bpcAlRxlK4BxHPcACDymFw,18
-ovld-0.5.5.dist-info/METADATA,sha256=K1dYchmA245qK_Kji4j7t-d8CTgriiem6JM_MnigdXM,9383
-ovld-0.5.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ovld-0.5.5.dist-info/licenses/LICENSE,sha256=cSwNTIzd1cbI89xt3PeZZYJP2y3j8Zus4bXgo4svpX8,1066
-ovld-0.5.5.dist-info/RECORD,,