configure_tagged_union: support type aliases

Author: Tinche

HISTORY.md

@@ -30,6 +30,7 @@ Our backwards-compatibility policy can be found [here](https://github.com/python
   ([#519](https://github.com/python-attrs/cattrs/issues/519) [#588](https://github.com/python-attrs/cattrs/pull/588))
 - Generic PEP 695 type aliases are now supported.
   ([#611](https://github.com/python-attrs/cattrs/issues/611) [#618](https://github.com/python-attrs/cattrs/pull/618))
+- The [tagged union strategy](https://catt.rs/en/stable/strategies.html#tagged-unions-strategy) now also supports type aliases of unions.
 - {meth}`Converter.copy` and {meth}`BaseConverter.copy` are correctly annotated as returning `Self`.
   ([#644](https://github.com/python-attrs/cattrs/pull/644))
 - Many preconf converters (_bson_, stdlib JSON, _cbor2_, _msgpack_, _msgspec_, _orjson_, _ujson_) skip unstructuring `int` and `str` enums,

docs/strategies.md

@@ -67,6 +67,10 @@ This also means union members can be reused in multiple unions easily.
 {'a': 1}
 ```
 
+```{versionchanged} 25.1.0
+The strategy can also be called with a type alias of a union.
+```
+
 ### Real-life Case Study
 
 The Apple App Store supports [server callbacks](https://developer.apple.com/documentation/appstoreservernotifications), by which Apple sends a JSON payload to a URL of your choice.

src/cattrs/strategies/_unions.py

@@ -3,8 +3,9 @@
 
 from attrs import NOTHING, NothingType
 
-from cattrs import BaseConverter
-from cattrs._compat import get_newtype_base, is_literal, is_subclass, is_union_type
+from .. import BaseConverter
+from .._compat import get_newtype_base, is_literal, is_subclass, is_union_type
+from ..typealiases import is_type_alias
 
 __all__ = [
     "configure_tagged_union",
@@ -26,8 +27,8 @@ def configure_tagged_union(
     default: Union[type, NothingType] = NOTHING,
 ) -> None:
     """
-    Configure the converter so that `union` (which should be a union) is
-    un/structured with the help of an additional piece of data in the
+    Configure the converter so that `union` (which should be a union, or a type alias
+    of one) is un/structured with the help of an additional piece of data in the
     unstructured payload, the tag.
 
     :param converter: The converter to apply the strategy to.
@@ -44,7 +45,12 @@ def configure_tagged_union(
     un/structuring base strategy.
 
     .. versionadded:: 23.1.0
+
+    ..  versionchanged:: 25.1
+        Type aliases of unions are now also supported.
     """
+    if is_type_alias(union):
+        union = union.__value__
     args = union.__args__
     tag_to_hook = {}
     exact_cl_unstruct_hooks = {}

tests/strategies/test_tagged_unions.py

@@ -177,3 +177,16 @@ class Top:
 
     data = c.unstructure(Top(u=[B(a="")]), Top)
     c.structure(data, Top)
+
+
+def test_type_alias(converter: BaseConverter):
+    """Type aliases to unions also work."""
+    type AOrB = A | B
+
+    configure_tagged_union(AOrB, converter)
+
+    assert converter.unstructure(A(1), AOrB) == {"_type": "A", "a": 1}
+    assert converter.unstructure(B("1"), AOrB) == {"_type": "B", "a": "1"}
+
+    assert converter.structure({"_type": "A", "a": 1}, AOrB) == A(1)
+    assert converter.structure({"_type": "B", "a": 1}, AOrB) == B("1")