Repository navigation
Description
Since 26.2.0, a structure hook registered for a PEP 695 type alias is skipped when the alias is a member of a union handled by the union passthrough strategy, which every preconf converter configures, so the raw value comes back with no error.
Minimal example
import cattrs
from cattrs.preconf.json import make_converter
from cattrs.strategies import configure_union_passthrough
type Trimmed = str
def build_plain():
c = cattrs.Converter()
configure_union_passthrough(str | int, c)
return c
for name, c in (("Converter + passthrough", build_plain()), ("preconf.json", make_converter())):
c.register_structure_hook_func(lambda t: t is Trimmed, lambda v, _: v.strip())
print(f"[{name}]")
print(" structure(' x ', Trimmed) observed:", repr(c.structure(" x ", Trimmed)))
print(" structure(' x ', Trimmed | int) observed:", repr(c.structure(" x ", Trimmed | int)))
print(" structure(' x ', Trimmed | int) expected:", repr("x"))
Observed output
[Converter + passthrough]
structure(' x ', Trimmed) observed: 'x'
structure(' x ', Trimmed | int) observed: ' x '
structure(' x ', Trimmed | int) expected: 'x'
[preconf.json]
structure(' x ', Trimmed) observed: 'x'
structure(' x ', Trimmed | int) observed: ' x '
structure(' x ', Trimmed | int) expected: 'x'
The hook runs for Trimmed on its own but not for Trimmed | int. Trimmed | int | None behaves the same way.
Expected behaviour
'x' in both cases, as 26.1.0 returns for the same script. The Type Aliases section of docs/defaulthooks.md says alias hooks can be overridden with predicate hooks, and its versionchanged 26.2.0 note about the passthrough strategy doesn't say those hooks are skipped inside unions.
Versions
- Python 3.12.3
- cattrs 26.2.1 (26.1.0 is not affected)
- attrs 26.1.0
- OS: Linux
Cause
In configure_union_passthrough (src/cattrs/strategies/_unions.py, main at 73fa273), get_passthrough_base (lines 180-181) replaces an alias with its value, so Trimmed becomes str in args (line 183) and in non_literal_classes (lines 202-207). The alias is then not in spillover, and the native union hook returns the value as is because val.__class__ in classes (lines 251 and 262). Before 26.2.0 the alias was not unwrapped, went to spillover, and converter.structure(val, Trimmed) reached the user hook. cattrs.preconf.json.make_converter() configures the passthrough at src/cattrs/preconf/json.py line 64, and the other preconf converters do the same, so any hook on a str, int, float, bool or bytes alias used in such a union is affected.
Proposed fix
Unwrap an alias only when the converter has no dedicated hook for it, for example when converter.get_structure_hook(alias) is still the product of the default type alias factory; otherwise leave the alias in spillover while the union is still claimed through its other members. A test that registers a hook on an alias and structures Alias | int would cover it.
I'm happy to open a PR with this fix and a test.
Activity