Introduce SimpleStructureHook

src/cattrs/__init__.py

@@ -11,32 +11,34 @@
     StructureHandlerNotFoundError,
 )
 from .gen import override
+from .types import SimpleStructureHook
 from .v import transform_error
 
 __all__ = [
-    "structure",
-    "unstructure",
-    "get_structure_hook",
-    "get_unstructure_hook",
-    "register_structure_hook_func",
-    "register_structure_hook",
-    "register_unstructure_hook_func",
-    "register_unstructure_hook",
-    "structure_attrs_fromdict",
-    "structure_attrs_fromtuple",
-    "global_converter",
-    "BaseConverter",
-    "Converter",
     "AttributeValidationNote",
+    "BaseConverter",
     "BaseValidationError",
     "ClassValidationError",
+    "Converter",
     "ForbiddenExtraKeysError",
     "GenConverter",
+    "get_structure_hook",
+    "get_unstructure_hook",
+    "global_converter",
     "IterableValidationError",
     "IterableValidationNote",
     "override",
+    "register_structure_hook_func",
+    "register_structure_hook",
+    "register_unstructure_hook_func",
+    "register_unstructure_hook",
+    "SimpleStructureHook",
+    "structure_attrs_fromdict",
+    "structure_attrs_fromtuple",
+    "structure",
     "StructureHandlerNotFoundError",
     "transform_error",
+    "unstructure",
     "UnstructureStrategy",
 ]
 

src/cattrs/gen/__init__.py

@@ -29,6 +29,7 @@
     StructureHandlerNotFoundError,
 )
 from ..fns import identity
+from ..types import SimpleStructureHook
 from ._consts import AttributeOverride, already_generating, neutral
 from ._generics import generate_mapping
 from ._lc import generate_unique_filename
@@ -892,8 +893,6 @@ def mapping_unstructure_factory(
 
 make_mapping_unstructure_fn: Final = mapping_unstructure_factory
 
-MappingStructureFn = Callable[[Mapping[Any, Any], Any], T]
-
 
 # This factory is here for backwards compatibility and circular imports.
 def mapping_structure_factory(
@@ -903,7 +902,7 @@ def mapping_structure_factory(
     key_type=NOTHING,
     val_type=NOTHING,
     detailed_validation: bool | Literal["from_converter"] = "from_converter",
-) -> MappingStructureFn[T]:
+) -> SimpleStructureHook[Mapping[Any, Any], T]:
     """Generate a specialized structure function for a mapping."""
     fn_name = "structure_mapping"
 
@@ -1010,7 +1009,8 @@ def mapping_structure_factory(
     for k, v in internal_arg_parts.items():
         globs[k] = v
 
-    def_line = f"def {fn_name}(mapping, _{internal_arg_line}):"
+    globs["cl"] = cl
+    def_line = f"def {fn_name}(mapping, cl=cl{internal_arg_line}):"
     total_lines = [def_line, *lines, "  return res"]
     script = "\n".join(total_lines)
 

src/cattrs/types.py

@@ -0,0 +1,13 @@
+from typing import Protocol, TypeVar
+
+In = TypeVar("In")
+T = TypeVar("T")
+
+__all__ = ["SimpleStructureHook"]
+
+
+class SimpleStructureHook(Protocol[In, T]):
+    """A structure hook with an optional (ignored) second argument."""
+
+    def __call__(self, _: In, /, cl=...) -> T:
+        ...