jaclang 0.7.34__py3-none-any.whl → 0.8.1__py3-none-any.whl

jaclang/vendor/cattrs/disambiguators.py

@@ -1,19 +1,34 @@
 """Utilities for union (sum type) disambiguation."""
-from collections import OrderedDict, defaultdict
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import MISSING
 from functools import reduce
 from operator import or_
-from typing import Any, Callable, Dict, Mapping, Optional, Set, Type, Union
+from typing import TYPE_CHECKING, Any, Callable, Literal, Mapping, Union
 
-from attrs import NOTHING, fields, fields_dict
+from attrs import NOTHING, Attribute, AttrsInstance
 
-from ._compat import get_args, get_origin, has, is_literal, is_union_type
+from ._compat import (
+    NoneType,
+    adapted_fields,
+    fields_dict,
+    get_args,
+    get_origin,
+    has,
+    is_literal,
+    is_union_type,
+)
+from .gen import AttributeOverride
 
-__all__ = ("is_supported_union", "create_default_dis_func")
+if TYPE_CHECKING:
+    from .converters import BaseConverter
 
-NoneType = type(None)
+__all__ = ["is_supported_union", "create_default_dis_func"]
 
 
-def is_supported_union(typ: Type) -> bool:
+def is_supported_union(typ: Any) -> bool:
     """Whether the type is a union of attrs classes."""
     return is_union_type(typ) and all(
         e is NoneType or has(get_origin(e) or e) for e in typ.__args__
@@ -21,30 +36,50 @@ def is_supported_union(typ: Type) -> bool:
 
 
 def create_default_dis_func(
-    *classes: Type[Any], use_literals: bool = True
-) -> Callable[[Mapping[Any, Any]], Optional[Type[Any]]]:
-    """Given attrs classes, generate a disambiguation function.
+    converter: BaseConverter,
+    *classes: type[AttrsInstance],
+    use_literals: bool = True,
+    overrides: (
+        dict[str, AttributeOverride] | Literal["from_converter"]
+    ) = "from_converter",
+) -> Callable[[Mapping[Any, Any]], type[Any] | None]:
+    """Given attrs classes or dataclasses, generate a disambiguation function.
 
-    The function is based on unique fields or unique values.
+    The function is based on unique fields without defaults or unique values.
 
     :param use_literals: Whether to try using fields annotated as literals for
         disambiguation.
+    :param overrides: Attribute overrides to apply.
+
+    .. versionchanged:: 24.1.0
+        Dataclasses are now supported.
     """
     if len(classes) < 2:
         raise ValueError("At least two classes required.")
 
+    if overrides == "from_converter":
+        overrides = [
+            getattr(converter.get_structure_hook(c), "overrides", {}) for c in classes
+        ]
+    else:
+        overrides = [overrides for _ in classes]
+
     # first, attempt for unique values
     if use_literals:
         # requirements for a discriminator field:
         # (... TODO: a single fallback is OK)
         #  - it must always be enumerated
         cls_candidates = [
-            {at.name for at in fields(get_origin(cl) or cl) if is_literal(at.type)}
+            {
+                at.name
+                for at in adapted_fields(get_origin(cl) or cl)
+                if is_literal(at.type)
+            }
             for cl in classes
         ]
 
         # literal field names common to all members
-        discriminators: Set[str] = cls_candidates[0]
+        discriminators: set[str] = cls_candidates[0]
         for possible_discriminators in cls_candidates:
             discriminators &= possible_discriminators
 
@@ -76,7 +111,7 @@ def create_default_dis_func(
                 for k, v in best_result.items()
             }
 
-            def dis_func(data: Mapping[Any, Any]) -> Optional[Type]:
+            def dis_func(data: Mapping[Any, Any]) -> type | None:
                 if not isinstance(data, Mapping):
                     raise ValueError("Only input mappings are supported.")
                 return final_mapping[data[best_discriminator]]
@@ -88,45 +123,83 @@ def create_default_dis_func(
     # NOTE: This could just as well work with just field availability and not
     #  uniqueness, returning Unions ... it doesn't do that right now.
     cls_and_attrs = [
-        (cl, {at.name for at in fields(get_origin(cl) or cl)}) for cl in classes
+        (cl, *_usable_attribute_names(cl, override))
+        for cl, override in zip(classes, overrides)
     ]
-    if len([attrs for _, attrs in cls_and_attrs if len(attrs) == 0]) > 1:
-        raise ValueError("At least two classes have no attributes.")
-    # TODO: Deal with a single class having no required attrs.
     # For each class, attempt to generate a single unique required field.
-    uniq_attrs_dict: Dict[str, Type] = OrderedDict()
-    cls_and_attrs.sort(key=lambda c_a: -len(c_a[1]))
+    uniq_attrs_dict: dict[str, type] = {}
+
+    # We start from classes with the largest number of unique fields
+    # so we can do easy picks first, making later picks easier.
+    cls_and_attrs.sort(key=lambda c_a: len(c_a[1]), reverse=True)
 
     fallback = None  # If none match, try this.
 
-    for i, (cl, cl_reqs) in enumerate(cls_and_attrs):
-        other_classes = cls_and_attrs[i + 1 :]
-        if other_classes:
-            other_reqs = reduce(or_, (c_a[1] for c_a in other_classes))
-            uniq = cl_reqs - other_reqs
-            if not uniq:
-                m = f"{cl} has no usable unique attributes."
-                raise ValueError(m)
-            # We need a unique attribute with no default.
-            cl_fields = fields(get_origin(cl) or cl)
-            for attr_name in uniq:
-                if getattr(cl_fields, attr_name).default is NOTHING:
-                    break
-            else:
-                raise ValueError(f"{cl} has no usable non-default attributes.")
-            uniq_attrs_dict[attr_name] = cl
+    for cl, cl_reqs, back_map in cls_and_attrs:
+        # We do not have to consider classes we've already processed, since
+        # they will have been eliminated by the match dictionary already.
+        other_classes = [
+            c_and_a
+            for c_and_a in cls_and_attrs
+            if c_and_a[0] is not cl and c_and_a[0] not in uniq_attrs_dict.values()
+        ]
+        other_reqs = reduce(or_, (c_a[1] for c_a in other_classes), set())
+        uniq = cl_reqs - other_reqs
+
+        # We want a unique attribute with no default.
+        cl_fields = fields_dict(get_origin(cl) or cl)
+        for maybe_renamed_attr_name in uniq:
+            orig_name = back_map[maybe_renamed_attr_name]
+            if cl_fields[orig_name].default in (NOTHING, MISSING):
+                break
         else:
-            fallback = cl
-
-    def dis_func(data: Mapping[Any, Any]) -> Optional[Type]:
-        if not isinstance(data, Mapping):
-            raise ValueError("Only input mappings are supported.")
-        for k, v in uniq_attrs_dict.items():
-            if k in data:
-                return v
-        return fallback
+            if fallback is None:
+                fallback = cl
+                continue
+            raise TypeError(f"{cl} has no usable non-default attributes")
+        uniq_attrs_dict[maybe_renamed_attr_name] = cl
+
+    if fallback is None:
+
+        def dis_func(data: Mapping[Any, Any]) -> type[AttrsInstance] | None:
+            if not isinstance(data, Mapping):
+                raise ValueError("Only input mappings are supported")
+            for k, v in uniq_attrs_dict.items():
+                if k in data:
+                    return v
+            raise ValueError("Couldn't disambiguate")
+
+    else:
+
+        def dis_func(data: Mapping[Any, Any]) -> type[AttrsInstance] | None:
+            if not isinstance(data, Mapping):
+                raise ValueError("Only input mappings are supported")
+            for k, v in uniq_attrs_dict.items():
+                if k in data:
+                    return v
+            return fallback
 
     return dis_func
 
 
 create_uniq_field_dis_func = create_default_dis_func
+
+
+def _overriden_name(at: Attribute, override: AttributeOverride | None) -> str:
+    if override is None or override.rename is None:
+        return at.name
+    return override.rename
+
+
+def _usable_attribute_names(
+    cl: type[Any], overrides: dict[str, AttributeOverride]
+) -> tuple[set[str], dict[str, str]]:
+    """Return renamed fields and a mapping to original field names."""
+    res = set()
+    mapping = {}
+
+    for at in adapted_fields(get_origin(cl) or cl):
+        res.add(n := _overriden_name(at, overrides.get(at.name)))
+        mapping[n] = at.name
+
+    return res, mapping

jaclang/vendor/cattrs/dispatch.py

@@ -1,11 +1,15 @@
-from functools import lru_cache, partial, singledispatch
-from typing import Any, Callable, Dict, Generic, List, Optional, Tuple, TypeVar, Union
+from __future__ import annotations
 
-from attrs import Factory, define, field
+from functools import lru_cache, singledispatch
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, TypeVar
 
-from cattrs._compat import TypeAlias
+from attrs import Factory, define
 
-T = TypeVar("T")
+from ._compat import TypeAlias
+from .fns import Predicate
+
+if TYPE_CHECKING:
+    from .converters import BaseConverter
 
 TargetType: TypeAlias = Any
 UnstructuredValue: TypeAlias = Any
@@ -31,25 +35,33 @@ class FunctionDispatch:
     first argument in the method, and return True or False.
 
     objects that help determine dispatch should be instantiated objects.
+
+    :param converter: A converter to be used for factories that require converters.
+
+    ..  versionchanged:: 24.1.0
+        Support for factories that require converters, hence this requires a
+        converter when creating.
     """
 
-    _handler_pairs: List[
-        Tuple[Callable[[Any], bool], Callable[[Any, Any], Any], bool]
-    ] = Factory(list)
+    _converter: BaseConverter
+    _handler_pairs: list[tuple[Predicate, Callable[[Any, Any], Any], bool, bool]] = (
+        Factory(list)
+    )
 
     def register(
         self,
-        can_handle: Callable[[Any], bool],
+        predicate: Predicate,
         func: Callable[..., Any],
         is_generator=False,
+        takes_converter=False,
     ) -> None:
-        self._handler_pairs.insert(0, (can_handle, func, is_generator))
+        self._handler_pairs.insert(0, (predicate, func, is_generator, takes_converter))
 
-    def dispatch(self, typ: Any) -> Optional[Callable[..., Any]]:
+    def dispatch(self, typ: Any) -> Callable[..., Any] | None:
         """
         Return the appropriate handler for the object passed.
         """
-        for can_handle, handler, is_generator in self._handler_pairs:
+        for can_handle, handler, is_generator, takes_converter in self._handler_pairs:
             # can handle could raise an exception here
             # such as issubclass being called on an instance.
             # it's easier to just ignore that case.
@@ -59,6 +71,8 @@ class FunctionDispatch:
                 continue
             if ch:
                 if is_generator:
+                    if takes_converter:
+                        return handler(typ, self._converter)
                     return handler(typ)
 
                 return handler
@@ -67,37 +81,45 @@ class FunctionDispatch:
     def get_num_fns(self) -> int:
         return len(self._handler_pairs)
 
-    def copy_to(self, other: "FunctionDispatch", skip: int = 0) -> None:
+    def copy_to(self, other: FunctionDispatch, skip: int = 0) -> None:
         other._handler_pairs = self._handler_pairs[:-skip] + other._handler_pairs
 
 
-@define
+@define(init=False)
 class MultiStrategyDispatch(Generic[Hook]):
     """
     MultiStrategyDispatch uses a combination of exact-match dispatch,
     singledispatch, and FunctionDispatch.
 
+    :param converter: A converter to be used for factories that require converters.
     :param fallback_factory: A hook factory to be called when a hook cannot be
         produced.
 
-    ..  versionchanged:: 23.2.0
+    .. versionchanged:: 23.2.0
         Fallbacks are now factories.
+    .. versionchanged:: 24.1.0
+        Support for factories that require converters, hence this requires a
+        converter when creating.
     """
 
     _fallback_factory: HookFactory[Hook]
-    _direct_dispatch: Dict = field(init=False, factory=dict)
-    _function_dispatch: FunctionDispatch = field(init=False, factory=FunctionDispatch)
-    _single_dispatch: Any = field(
-        init=False, factory=partial(singledispatch, _DispatchNotFound)
-    )
-    dispatch: Callable[[TargetType], Hook] = field(
-        init=False,
-        default=Factory(
-            lambda self: lru_cache(maxsize=None)(self._dispatch), takes_self=True
-        ),
-    )
-
-    def _dispatch(self, typ: TargetType) -> Hook:
+    _converter: BaseConverter
+    _direct_dispatch: dict[TargetType, Hook]
+    _function_dispatch: FunctionDispatch
+    _single_dispatch: Any
+    dispatch: Callable[[TargetType, BaseConverter], Hook]
+
+    def __init__(
+        self, fallback_factory: HookFactory[Hook], converter: BaseConverter
+    ) -> None:
+        self._fallback_factory = fallback_factory
+        self._direct_dispatch = {}
+        self._function_dispatch = FunctionDispatch(converter)
+        self._single_dispatch = singledispatch(_DispatchNotFound)
+        self.dispatch = lru_cache(maxsize=None)(self.dispatch_without_caching)
+
+    def dispatch_without_caching(self, typ: TargetType) -> Hook:
+        """Dispatch on the type but without caching the result."""
         try:
             dispatch = self._single_dispatch.dispatch(typ)
             if dispatch is not _DispatchNotFound:
@@ -124,16 +146,19 @@ class MultiStrategyDispatch(Generic[Hook]):
 
     def register_func_list(
         self,
-        pred_and_handler: List[
-            Union[
-                Tuple[Callable[[Any], bool], Any],
-                Tuple[Callable[[Any], bool], Any, bool],
-            ]
+        pred_and_handler: list[
+            tuple[Predicate, Any]
+            | tuple[Predicate, Any, bool]
+            | tuple[Predicate, Callable[[Any, BaseConverter], Any], Literal["extended"]]
         ],
     ):
         """
-        Register a predicate function to determine if the handle
+        Register a predicate function to determine if the handler
         should be used for the type.
+
+        :param pred_and_handler: The list of predicates and their associated
+            handlers. If a handler is registered in `extended` mode, it's a
+            factory that requires a converter.
         """
         for tup in pred_and_handler:
             if len(tup) == 2:
@@ -141,7 +166,12 @@ class MultiStrategyDispatch(Generic[Hook]):
                 self._function_dispatch.register(func, handler)
             else:
                 func, handler, is_gen = tup
-                self._function_dispatch.register(func, handler, is_generator=is_gen)
+                if is_gen == "extended":
+                    self._function_dispatch.register(
+                        func, handler, is_generator=is_gen, takes_converter=True
+                    )
+                else:
+                    self._function_dispatch.register(func, handler, is_generator=is_gen)
         self.clear_direct()
         self.dispatch.cache_clear()
 
@@ -157,7 +187,7 @@ class MultiStrategyDispatch(Generic[Hook]):
     def get_num_fns(self) -> int:
         return self._function_dispatch.get_num_fns()
 
-    def copy_to(self, other: "MultiStrategyDispatch", skip: int = 0) -> None:
+    def copy_to(self, other: MultiStrategyDispatch, skip: int = 0) -> None:
         self._function_dispatch.copy_to(other._function_dispatch, skip=skip)
         for cls, fn in self._single_dispatch.registry.items():
             other._single_dispatch.register(cls, fn)

jaclang/vendor/cattrs/fns.py

@@ -1,10 +1,15 @@
 """Useful internal functions."""
-from typing import NoReturn, Type, TypeVar
 
+from typing import Any, Callable, NoReturn, Type, TypeVar
+
+from ._compat import TypeAlias
 from .errors import StructureHandlerNotFoundError
 
 T = TypeVar("T")
 
+Predicate: TypeAlias = Callable[[Any], bool]
+"""A predicate function determines if a type can be handled."""
+
 
 def identity(obj: T) -> T:
     """The identity function."""