thds.attrs-utils 1.6.20251103154246__py3-none-any.whl

thds/attrs_utils/type_cache.py

@@ -0,0 +1,110 @@
+from collections import ChainMap, deque
+from types import MemberDescriptorType, ModuleType
+from typing import Any, Collection, Dict, Generic, Iterator, Optional, Set, Tuple, Type, Union
+
+from .type_utils import T, typename
+
+CLASS_DUNDER_NAMES: Set[str] = (
+    set(vars(object))
+    .union(dir(ModuleType("")))
+    .union(
+        {
+            "__name__",
+            "__file__",
+            "__module__",
+            "__dict__",
+            "__weakref__",
+            "__builtins__",
+        }
+    )
+)
+
+#######################################################
+# Store for naming types from many modules succinctly #
+# and keeping track of computations on them           #
+#######################################################
+
+
+class TypeCache(Generic[T]):
+    """Key-value store for type objects whose main purpose is to provide canonical names for types,
+    given a set of modules they are defined in. Passing modules via keyword allows you to override the
+    name of a module in the final dotted name of a type, in case there is some display concern where that
+    would be useful, or when generating an external-facing interface where stability is required even
+    while the internal module structure may be changing. Also allows storage of metadata about types;
+    this is what is parameterized by the `T` type variable.
+
+    Example:
+
+        import builtins, datetime
+        from thds.attrs_utils import type_cache
+
+        types = TypeCache(internal=[type_cache], python=[builtins, datetime])
+
+        print(types.name_of(int))
+        print(types.name_of(datetime.date))
+        print(types.name_of(type_cache.TypeCache))
+
+        # python.int
+        # python.date
+        # internal.TypeCache
+    """
+
+    def __init__(self, **modules: Union[ModuleType, Collection[ModuleType]]):
+        name_lookups = []
+        for module_name, m in modules.items():
+            ms: Collection[ModuleType]
+            ms = [m] if isinstance(m, ModuleType) else m
+            for module in ms:  # type: ignore
+                names = {
+                    id(obj): name
+                    for name, obj in object_names_recursive(module, cache=set(), name=module_name)
+                }
+                name_lookups.append(names)
+
+        self.type_names = ChainMap(*name_lookups)
+        self.schemas: Dict[int, T] = {}
+
+    def name_of(self, type_: Type):
+        if id(type_) in self.type_names:
+            return self.type_names[id(type_)]
+        return typename(type_)
+
+    def base_name_of(self, type_: Type):
+        return self.name_of(type_).split(".")[-1]
+
+    def __setitem__(self, key: Type, value: T):
+        # some type objects which are distinct (different `id`) actually compare equal, so we have to
+        # store and look up distinct types by `id` to avoid collisions and therefore ambiguous naming;
+        # otherwise, the `name_of` a type could change during the course of program execution as the
+        # contents of the cache are populated
+        self.schemas[id(key)] = value
+
+    def __getitem__(self, key: Type) -> T:
+        return self.schemas[id(key)]
+
+    def __contains__(self, key: Type) -> bool:
+        return id(key) in self.schemas
+
+    def pop(self, key: Type) -> T:
+        return self.schemas.pop(id(key))
+
+
+def object_names_recursive(
+    module: Union[ModuleType, Type],
+    cache: Set[int],
+    name: Optional[str] = None,
+) -> Iterator[Tuple[str, Any]]:
+    """Names of objects, recursing into namespaces of classes, breadth-first"""
+    q = deque([(name or module.__name__, module)])
+    while q:
+        prefix, module = q.popleft()
+        for name, obj in vars(module).items():
+            if (
+                name not in CLASS_DUNDER_NAMES
+                and not isinstance(obj, MemberDescriptorType)
+                and id(obj) not in cache
+            ):
+                yield f"{prefix}.{name}", obj
+                cache.add(id(obj))
+                if isinstance(obj, type):  # recurse
+                    q.append((f"{prefix}.{name}", obj))

thds/attrs_utils/type_recursion.py

@@ -0,0 +1,168 @@
+import typing
+from functools import partial
+from typing import List, Optional, Tuple, Type, TypeVar
+
+import attr
+from typing_inspect import is_tuple_type, is_typevar, is_union_type
+
+from . import type_utils
+from .recursion import F, Params, Predicate, RecF, StructuredRecursion, U, _value_error
+from .registry import Registry
+
+
+def default_newtype(
+    recurse: F[Type, Params, U], type_: Type, *args: Params.args, **kwargs: Params.kwargs
+) -> U:
+    """Default implementation for `typing.NewType` that recurses by simply applying the recursion to the
+    ultimate concrete type underlying the newtype"""
+    return recurse(type_utils.newtype_base(type_), *args, **kwargs)
+
+
+def default_annotated(
+    recurse: F[Type, Params, U], type_: Type, *args: Params.args, **kwargs: Params.kwargs
+) -> U:
+    """Default implementation for `typing.Annotated` that recurses by simply applying the recursion to
+    the type that was wrapped with the annotation"""
+    return recurse(type_utils.unwrap_annotated(type_), *args, **kwargs)
+
+
+def _try_bases(
+    msg: str,
+    exc_type: Type[Exception],
+    # placeholder for the recursive function in case you wish to specify this explictly as one of the
+    # recursions; type doesn't matter
+    f: F[Type, Params, U],
+    type_: Type,
+    *args: Params.args,
+    **kwargs: Params.kwargs,
+) -> U:
+    try:
+        mro = type_.mro()
+    except (AttributeError, TypeError):
+        return _value_error(msg, exc_type, f, type_, *args, **kwargs)
+    for base in mro[1:]:
+        try:
+            return f(base, *args, **kwargs)
+        except TypeError:
+            pass
+    return _value_error(msg, exc_type, f, type_, *args, **kwargs)
+
+
+def try_bases(msg: str, exc_type: Type[Exception]) -> RecF[Type, Params, U]:
+    """Helper to be passed as the `otherwise` of a `TypeRecursion` for handling cases of types which
+    inherit from some known type that is not otherwise explicitly registered"""
+    return partial(_try_bases, msg, exc_type)  # type: ignore[return-value]
+
+
+class TypeRecursion(StructuredRecursion[Type, Params, U]):
+    """Convenience class for defining functions which operate on runtime representations of types
+    recursively. Handles the appropriate ordering of predicates such that more specific predicates
+    precede more general ones. Also handles caching of results using the `registry` when `cached=True`,
+    to allow for caching of results, since generally types are hashable never go out of program scope,
+    and are not terribly numerous. With or without caching, the `registry` allows overriding with custom
+    behavior for any specific type by using the `.register` method. Behavior registered this way will
+    take precedence regardless of which predicates match the registered type."""
+
+    def __init__(
+        self,
+        registry: Registry[Type, U],
+        cached: bool = True,
+        *,
+        first: Optional[Tuple[Predicate[Type], RecF[Type, Params, U]]] = None,
+        attrs: Optional[RecF[Type, Params, U]] = None,
+        namedtuple: Optional[RecF[Type, Params, U]] = None,
+        optional: Optional[RecF[Type, Params, U]] = None,
+        union: Optional[RecF[Type, Params, U]] = None,
+        literal: Optional[RecF[Type, Params, U]] = None,
+        enum: Optional[RecF[Type, Params, U]] = None,
+        set: Optional[RecF[Type, Params, U]] = None,
+        mapping: Optional[RecF[Type, Params, U]] = None,
+        collection: Optional[RecF[Type, Params, U]] = None,
+        tuple: Optional[RecF[Type, Params, U]] = None,
+        variadic_tuple: Optional[RecF[Type, Params, U]] = None,
+        newtype: Optional[RecF[Type, Params, U]] = default_newtype,  # type: ignore[assignment]
+        annotated: Optional[RecF[Type, Params, U]] = default_annotated,  # type: ignore[assignment]
+        typevar: Optional[RecF[Type, Params, U]] = None,
+        otherwise: RecF[Type, Params, U],
+    ):
+        prioritized_funcs: List[Tuple[Predicate[Type], Optional[RecF[Type, Params, U]]]] = (
+            [] if first is None else [first]
+        )
+        prioritized_funcs.extend(
+            [
+                (is_typevar, typevar),
+                (type_utils.is_annotated_type, annotated),
+                (type_utils.is_new_type, newtype),
+                (type_utils.is_literal_type, literal),
+                (type_utils.is_enum_type, enum),
+                (attr.has, attrs),
+                (type_utils.is_optional_type, optional),
+                (is_union_type, union),
+                (type_utils.is_set_type, set),
+                (type_utils.is_mapping_type, mapping),
+                (type_utils.is_namedtuple_type, namedtuple),
+                (type_utils.is_variadic_tuple_type, variadic_tuple),
+                (is_tuple_type, tuple),
+                (type_utils.is_collection_type, collection),
+                (type_utils.is_annotated_type, annotated),
+            ]
+        )
+        self.registry = registry
+        self.cached = cached
+        super().__init__(
+            [(predicate, f) for predicate, f in prioritized_funcs if f is not None],
+            otherwise,
+        )
+
+    def register(self, type_: Type, value: Optional[U] = None):
+        """Convenience decorator factory"""
+        if value is None:
+            return self.registry.register(type_)
+        else:
+            return self.registry.register(type_, value)
+
+    def __call__(self, obj: Type, *args: Params.args, **kwargs: Params.kwargs) -> U:
+        if self.registry is None:
+            return super().__call__(obj, *args, **kwargs)
+        try:
+            result = self.registry[obj]
+        except KeyError:
+            result = super().__call__(obj, *args, **kwargs)
+            if self.cached:
+                self.registry[obj] = result
+        return result
+
+
+T = TypeVar("T")
+Constructor = typing.Callable[..., T]
+
+
+class ConstructorFactory(TypeRecursion[Params, Constructor]):
+    """Specialization of `TypeRecursion` for the common case of functions that take a type and return a function that
+    returns instances of that type. Common examples include random or default instance generators.
+
+    Consider the following example:
+
+    ```python
+    random_gen: TypeRecursion[[], Factory]]
+
+    random_int = random_gen(int)  # returns a function that generates random integers
+    random_str = random_gen(str)  # returns a function that generates random strings
+
+    def add_one(x: int) -> int:
+        return x + 1
+
+    add_one(random_int())  # totally fine
+    add_one(random_str())  # type error, but `mypy` doesn't catch it
+    ```
+
+    In this case, `add_one(random_str())` is a type error, but `mypy` doesn't catch it because `random_gen`'s signature
+    does not constrain the returned constructor as returning the same type as the input type. If, on the other hand,
+    `random_gen` had been typed as a `ConstructorFactory`, the type checker would be able to catch this error.
+    It is up to you as the implementer to ensure that your implementation of any `ConstructorFactory` actually respects
+    this constraint, since the implementation is too dynamic for most type checkers to verify this automatically, but if
+    you do so, then the type checker _can_ detect common errors downstream of any given constructor creation.
+    """
+
+    def __call__(self, type_: Type[T], *args: Params.args, **kwargs: Params.kwargs) -> Constructor[T]:  # type: ignore[override]
+        return super().__call__(type_)

thds/attrs_utils/type_utils.py

@@ -0,0 +1,180 @@
+import collections
+import enum
+import inspect
+import typing
+from typing import Callable, List, Mapping, Optional, Tuple, Type, TypeVar, Union
+
+import attr
+from typing_inspect import (
+    get_args,
+    get_origin,
+    get_parameters,
+    is_literal_type,
+    is_new_type,
+    is_optional_type,
+    is_tuple_type,
+    is_typevar,
+)
+
+T = TypeVar("T")
+
+COLLECTION_TYPES = set(
+    map(
+        get_origin,
+        [
+            typing.List,
+            typing.Tuple,
+            typing.Set,
+            typing.MutableSet,
+            typing.FrozenSet,
+            typing.AbstractSet,
+            typing.Sequence,
+            typing.Collection,
+        ],
+    )
+)
+UNIQUE_COLLECTION_TYPES = set(
+    map(get_origin, [typing.Set, typing.MutableSet, typing.FrozenSet, typing.AbstractSet])
+)
+MAPPING_TYPES = set(
+    map(
+        get_origin,
+        [
+            typing.Dict,
+            typing.Mapping,
+            typing.MutableMapping,
+            typing.DefaultDict,
+            typing.OrderedDict,
+            typing.Counter,
+        ],
+    )
+)
+TUPLE = get_origin(Tuple)
+ORIGIN_TO_CONSTRUCTOR = {
+    get_origin(t): c
+    for t, c in [
+        (typing.List, list),
+        (typing.Tuple, tuple),
+        (typing.Set, set),
+        (typing.MutableSet, set),
+        (typing.AbstractSet, set),
+        (typing.FrozenSet, frozenset),
+        (typing.Sequence, list),
+        (typing.Collection, list),
+        (typing.Dict, dict),
+        (typing.Mapping, dict),
+        (typing.MutableMapping, dict),
+        (typing.OrderedDict, collections.OrderedDict),
+    ]
+}
+
+
+def typename(type_: Type) -> str:
+    if attr.has(type_) or is_new_type(type_) or is_typevar(type_):
+        return type_.__name__
+    else:
+        raise TypeError(f"can't generate meaningful name for type {type_}")
+
+
+def newtype_base(type_: Type) -> Type:
+    return newtype_base(type_.__supertype__) if is_new_type(type_) else type_
+
+
+def literal_base(type_: Type) -> Type:
+    assert is_literal_type(type_)
+    types = tuple(map(type, get_args(type_)))
+    return Union[types]  # type: ignore
+
+
+def enum_base(type_: Type) -> Type:
+    assert is_enum_type(type_)
+    if issubclass(type_, int):  # IntEnum, IntFlag
+        return int
+    types = tuple(type(e.value) for e in type_)
+    return Union[types]  # type: ignore
+
+
+def unwrap_optional(type_: Type) -> Type:
+    if is_optional_type(type_):
+        args = get_args(type_)
+        return Union[tuple(a for a in args if a is not type(None))]  # type: ignore  # noqa:E721
+    else:
+        return type_
+
+
+def is_annotated_type(type_: Type) -> bool:
+    return (
+        hasattr(type_, "__origin__")
+        and hasattr(type_, "__args__")
+        and isinstance(getattr(type_, "__metadata__", None), tuple)
+    )
+
+
+def unwrap_annotated(type_: Type) -> Type:
+    if is_annotated_type(type_):
+        return type_.__origin__
+    return type_
+
+
+def is_enum_type(type_: Type) -> bool:
+    return isinstance(type_, type) and issubclass(type_, enum.Enum)
+
+
+def is_collection_type(type_: Type) -> bool:
+    origin = get_origin(type_)
+    return (type_ in COLLECTION_TYPES) if origin is None else (origin in COLLECTION_TYPES)
+
+
+def is_mapping_type(type_: Type) -> bool:
+    origin = get_origin(type_)
+    return (type_ in MAPPING_TYPES) if origin is None else (origin in MAPPING_TYPES)
+
+
+def is_set_type(type_: Type) -> bool:
+    origin = get_origin(type_)
+    return (type_ in UNIQUE_COLLECTION_TYPES) if origin is None else (origin in UNIQUE_COLLECTION_TYPES)
+
+
+def is_namedtuple_type(type_: Type) -> bool:
+    return getattr(type_, "__bases__", None) == (tuple,) and hasattr(type_, "_fields")
+
+
+def is_variadic_tuple_type(type_: Type) -> bool:
+    if is_tuple_type(type_):
+        args = get_args(type_)
+        return len(args) == 2 and args[-1] is Ellipsis
+    else:
+        return False
+
+
+def is_builtin_type(type_: Type) -> bool:
+    return getattr(type_, "__module__", None) == "builtins" and not get_args(type_)
+
+
+def concrete_constructor(type_: Type[T]) -> Callable[..., T]:
+    if is_namedtuple_type(type_):
+        return type_
+    origin = get_origin(type_)
+    return ORIGIN_TO_CONSTRUCTOR[type_] if origin is None else ORIGIN_TO_CONSTRUCTOR[origin]
+
+
+def parameterize(
+    type_: Union[Type, TypeVar], params: Mapping[TypeVar, Union[TypeVar, Type]]
+) -> Union[Type, TypeVar]:
+    if isinstance(type_, TypeVar):
+        return params.get(type_, type_)
+    else:
+        tparams = get_parameters(type_)
+        new_args = tuple(params.get(t, t) for t in tparams)
+        return type_[new_args]
+
+
+def bases(type_: Type, predicate: Optional[Callable[[Type], bool]] = None) -> List[Type]:
+    if not inspect.isclass(type_):
+        raise TypeError(
+            f"{bases.__module__}.{bases.__name__} can be called only on concrete classes; got {type_}"
+        )
+    elif predicate is None:
+        return list(inspect.getmro(type_))
+    else:
+        return list(filter(predicate, inspect.getmro(type_)))

thds_attrs_utils-1.6.20251103154246.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: thds.attrs-utils
+Version: 1.6.20251103154246
+Summary: Utilities for attrs record classes.
+Author-email: Trillianth Health <info@trillianthealth.com>
+Project-URL: Repository, https://github.com/TrilliantHealth/ds-monorepo
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: returns
+Requires-Dist: thds-core
+Requires-Dist: typing-inspect
+Provides-Extra: cattrs
+Requires-Dist: cattrs>=22.2.0; extra == "cattrs"
+Provides-Extra: docstrings
+Requires-Dist: docstring-parser; extra == "docstrings"
+Provides-Extra: jsonschema
+Requires-Dist: fastjsonschema; extra == "jsonschema"
+
+# `thds.attrs-utils` Library
+
+This library contains utilities for working with basic data types and type annotations in a generic way -
+transforming, checking, generating, or anything else you'd want to do with types.
+
+## Supported types:
+
+- Builtin types, e.g. `int`, `str`, `float`, `bool`, `bytes`
+- `datetime.date`, `datetime.datetime`
+- Most standard library collection types, e.g. `List[T]`, `Sequence[T]`, `Dict[K, V]`, `Mapping[K, V]`,
+  `Set[T]`
+- Heterogeneous tuple types, e.g. `typing.Tuple[A, B, C]`
+- Variadic tuple types, e.g. `Tuple[T, ...]`
+- `typing.NamedTuple` record types
+- `attrs`-defined record types
+- Union types using `typing.Union`
+- `typing.Literal`
+- `typing.Annotated`
+- `typing.NewType`
+
+## General Recursion Framework
+
+The `thds.attrs_utils.type_recursion` module defines a generic interface for performing operations on
+arbitrarily nested types. If you have some operation you'd like to do, e.g. transform a python data model
+into some other schema language, or define a generic validation check, all you need to do is define it on
+a particular set of cases.
+
+For example, here's a simple implementation that counts the number of types referenced inside of a nested
+type definition:
+
+```python
+from typing import List, Mapping, Tuple, get_args
+from thds.attrs_utils.type_recursion import TypeRecursion, Registry
+
+def n_types_generic(recurse, type_):
+    args = get_args(type_)
+    return 1 + sum(map(recurse, args))
+
+n_types = TypeRecursion(
+    Registry(),
+    tuple=n_types_generic,       # these aren't strictly required because the implementation is the same for all of them
+    collection=n_types_generic,  # but I include them
+    mapping=n_types_generic,
+    otherwise=n_types_generic,
+)
+
+print(n_types(Mapping[Tuple[int, str], List[bytes]]))
+#             1       2     3    4     5    6
+# 6
+```
+
+This example is very simple to illustrate the point. However, much more complex use cases are enabled by
+the framework. Most useful are type recursions which accept types and return _callables_ that apply to or
+return values inhabiting those types. Examples included in this library are
+
+- an instance checker takes an arbitrarily nested type and returns a callable which recursively checks
+  that all fields inside a nested value are of the expected type
+- a jsonschema generator which takes a type and returns a jsonschema, which can then be used to validate
+  deserialized values that may be structured into instances of that type
+- a random generator which takes a type and returns random instances of that type
+
+Note that the cases which return callables are _static_ with respect to the given type. This allows you
+to freeze the callable as specialized to a specific type, so that the type itself only has to be
+inspected only once - the callable itself only needs to inspect values.
+
+## Use Cases in this Library
+
+This library includes a few useful implementations of the above pattern.
+
+### Random Data Generation
+
+You can create a callable to generate instances of a given type as follows:
+
+```python
+import itertools
+from typing import Dict, Literal, NewType, Optional, Tuple
+import attr
+from thds.attrs_utils.random.builtin import random_bool_gen, random_int_gen, random_str_gen
+from thds.attrs_utils.random.tuple import random_tuple_gen
+from thds.attrs_utils.random.attrs import register_random_gen_by_field
+from thds.attrs_utils.random import random_gen
+
+@register_random_gen_by_field(
+    a=random_str_gen(random_int_gen(1, 3), "ABCD"),
+    b=random_tuple_gen(random_int_gen(0, 3), random_bool_gen(0.99))
+)
+@attr.define
+class Record1:
+    a: Optional[str]
+    b: Tuple[int, bool]
+
+ID = NewType("ID", int)
+Key = Literal["foo", "bar", "baz"]
+
+@attr.define
+class Record2:
+    id: ID
+    records: Dict[Key, Record1]
+
+ids = itertools.count(1)
+random_gen.register(ID, lambda: next(ids))
+
+random_record = random_gen(Record2)
+
+print(random_record())
+print(random_record())
+# Record2(id=1, records={'bar': Record1(a='B', b=(1, True)), 'baz': Record1(a='C', b=(3, True)), 'foo': Record1(a='ACB', b=(1, True))})
+# Record2(id=2, records={'foo': Record1(a='A', b=(3, True)), 'bar': Record1(a='ADB', b=(1, True)), 'baz': Record1(a='CAD', b=(0, True))})
+```
+
+This can be useful for certain kinds of tests, e.g. round-trip tests, run-time profiling, and
+property-based tests. It saves you maintenance because you don't need a sample of "real" data that is
+completely up to date with your data model changes, and it saves you time because it's faster to generate
+random instances in memory than to fetch a file and deserialize instances from it.
+
+### Validation
+
+There are two kinds of validation provided in this library: jsonschema validation and basic instance
+checking.
+
+#### Jsonschema
+
+Jsonschema validation applies to an "unstructured" precursor of your data that would come, e.g. from
+parsing json or deserializing data in some other way. This expects a value composed of builtin python
+types - dicts, lists, strings, ints, floats, bools, and null values, arbitrarily nested.
+
+To generate a jsonschema for your type (usually a nested record type of some kind), you need only run the
+following:
+
+```python
+from thds.attrs_utils.jsonschema import to_jsonschema, jsonschema_validator
+
+from my_library import my_module
+
+schema = to_jsonschema(my_module.MyRecordType, modules=[my_module])
+
+check = jsonschema_validator(schema)
+
+check({})  # fails for absence of fields defined in my_module.MyRecordType
+```
+
+#### Simple instance checks
+
+Instance checking asserts that the run time types of all references inside some object are as expected.
+It is semantically similar to the builtin `isinstance`, but checks all references inside an object
+recursively.
+
+```python
+from typing import Literal, Mapping
+
+from thds.attrs_utils.isinstance import isinstance as deep_isinstance
+
+Num = Literal["one", "two", "three"]
+
+value = {"one": 2, "three": 4}
+
+# can't use `isinstance` with parameterized types
+print(isinstance(value, Mapping))
+# True
+print(deep_isinstance(value, Mapping[Num, int]))
+# True
+print(deep_isinstance(value, Mapping[str, int]))
+# True
+print(deep_isinstance(value, Mapping[Num, str]))
+# False
+```
+
+This can be useful for validating data from an unknown source, but is generally less useful that
+jsonschema validation, because it applies to data that has already been "structured", (assuming that the
+input was even in the correct shape for such an operation), and most of the errors it would catch could
+also be caught statically and more efficiently via static type checking. We provide it mainly as a
+reference implementation for using the `TypeRecursion` framework in a relatively simple, but mostly
+complete way. We also use it in a property-based test of random data generation; for any type `T`,
+`isinstance(random_gen(T)(), T)` should hold.
+
+## Serialization/Deserialization
+
+The `thds.attrs_utils.cattrs` submodule defines useful defaults for serialization/deserialization of
+values of various types, and utils to customize behavior for your own custom types, should you need to.
+The goal is that the defaults do what you want in 99% of cases.
+
+To use the converters:
+
+```python
+from thds.attrs_utils.cattrs import DEFAULT_JSON_CONVERTER
+
+from my_library import my_module
+
+ready_for_json = DEFAULT_JSON_CONVERTER.unstructure(my_module.MyRecordType())
+```
+
+or if you require some custom behavior, you may define your own hooks and use helper functions to
+construct your own converter. Here's an example where we register custom hooks for the UUID type, which
+you would need if that type was present in your data model:
+
+```python
+from typing import Type
+from uuid import UUID
+
+from thds.attrs_utils.cattrs import default_converter, setup_converter, DEFAULT_STRUCTURE_HOOKS, DEFAULT_UNSTRUCTURE_HOOKS_JSON
+
+def structure_uuid(s: str, type_: Type[UUID]) -> UUID:
+  return type_(s)
+
+
+CONVERTER = setup_converter(
+    default_converter(),
+    struct_hooks=[*DEFAULT_STRUCTURE_HOOKS, (UUID, structure_uuid)],
+    unstruct_hooks=[*DEFAULT_UNSTRUCTURE_HOOKS_JSON, (UUID, str)],
+)
+```