Added include_subclasses documentation

Author: matmel

HISTORY.md

@@ -16,6 +16,8 @@
 - Add optional dependencies for `cattrs.preconf` third-party libraries. ([#337](https://github.com/python-attrs/cattrs/pull/337))
 - All preconf converters now allow overriding the default `unstruct_collection_overrides` in `make_converter`.
   ([#350](https://github.com/python-attrs/cattrs/issues/350) [#353](https://github.com/python-attrs/cattrs/pull/353))
+- Subclasses structuring and unstructuring is now supported via a custom `include_subclasses` strategy.
+  ([#312](https://github.com/python-attrs/cattrs/pull/312))
 
 ## 22.2.0 (2022-10-03)
 

docs/strategies.md

@@ -4,7 +4,7 @@ _cattrs_ ships with a number of _strategies_ for customizing un/structuring beha
 
 Strategies are prepackaged, high-level patterns for quickly and easily applying complex customizations to a converter.
 
-## Tagged Unions
+## Tagged Unions Strategy
 
 _Found at {py:func}`cattrs.strategies.configure_tagged_union`._
 
@@ -119,3 +119,134 @@ The converter is now ready to start structuring Apple notifications.
 ...         print("Can't handle this yet")
 
 ```
+
+## Include Subclasses Strategy
+
+_Found at {py:func}`cattrs.strategies.include_subclasses`._
+
+The _include subclass_ strategy allows the un/structuring of a base class to an instance of itself or one of its descendants.
+Conceptually with this strategy, each time an un/structure operation for the base class is asked, `cattrs` machinery replaces that operation as if the union of the base class and its descendants had been asked instead.
+
+```{doctest} include_subclass
+
+>>> from attrs import define
+>>> from cattrs.strategies import include_subclasses
+>>> from cattrs import Converter
+
+>>> @define
+... class Parent:
+...     a: int
+
+>>> @define
+... class Child(Parent):
+...     b: str
+
+>>> converter = Converter()
+>>> include_subclasses(Parent, converter)
+
+>>> converter.unstructure(Child(a=1, b="foo"), unstructure_as=Parent)
+{'a': 1, 'b': 'foo'}
+
+>>> converter.structure({'a': 1, 'b': 'foo'}, Parent)
+Child(a=1, b='foo')
+```
+
+In the example above, we asked to unstructure then structure a `Child` instance as the `Parent` class and in both cases we correctly obtained back the unstructured and structured versions of the `Child` instance.
+If we did not apply the `include_subclasses` strategy, this is what we would have obtained:
+
+```python
+>>> converter_no_subclasses = Converter()
+
+>>> converter_no_subclasses.unstructure(Child(a=1, b="foo"), unstructure_as=Parent)
+{'a': 1}
+
+>>> converter_no_subclasses.structure({'a': 1, 'b': 'foo'}, Parent)
+Parent(a=1)
+```
+
+Without the application of the strategy, in both unstructure and structure operations, we received a `Parent` instance.
+
+```{note}
+The handling of subclasses is an opt-in feature for two main reasons:
+- Performance. While small and probably negligeable in most cases the subclass handling incurs more function calls and has a performance impact. 
+- Customization. The specific handling of subclasses can be different from one situation to the other. In particular there is not apparent universal good defaults for disambiguating the union type. Consequently The decision is left to the `cattrs` user.
+```
+
+```{warning}
+To work properly, all subclasses must be defined when the `include_subclasses` strategy is applied to a `converter`. If subclasses types are defined later, for instance in the context of a plug-in mechanism using inheritance, then those late defined subclasses will not be part of the subclasses union type and will not be un/structured as expected.
+```
+
+### Customization
+
+In the example shown in the previous section, the default options for `include_subclasses` work well because the `Child` class has an attribute that do not exist in the `Parent` class (the `b` attribute).
+The automatic union type disambiguation function which is based on finding unique fields for each type of the union works as intended.
+
+Sometimes, more disambiguation customization is required.
+For instance, the unstructuring operation would have failed if `Child` did not have an extra attribute or if a sibling of `Child` had also a `b` attribute.
+For those cases, a callable of 2 positional arguments (a union type and a converter) defining a [tagged union strategy](strategies.md#tagged-unions-strategy) can be passed to the `include_subclasses` strategy.
+{py:func}`configure_tagged_union()<cattrs.strategies.configure_tagged_union>` can be used as-is, but if you want to change its defaults, the [partial](https://docs.python.org/3/library/functools.html#functools.partial) function from the `functools` module in the standard library can come in handy.
+
+```python
+
+>>> from functools import partial
+>>> from attrs import define
+>>> from cattrs.strategies import include_subclasses, configure_tagged_union
+>>> from cattrs import Converter
+
+>>> @define
+... class Parent:
+...     a: int
+
+>>> @define
+... class Child1(Parent):
+...     b: str
+
+>>> @define
+... class Child2(Parent):
+...     b: int
+
+>>> converter = Converter()
+>>> union_strategy = partial(configure_tagged_union, tag_name="type_name")
+>>> include_subclasses(Parent, converter, union_strategy=union_strategy)
+
+>>> converter.unstructure(Child1(a=1, b="foo"), unstructure_as=Parent)
+{'a': 1, 'b': 'foo', 'type_name': 'Child1'}
+
+>>> converter.structure({'a': 1, 'b': 1, 'type_name': 'Child2'}, Parent)
+Child2(a=1, b=1)
+```
+
+Other customizations available see are (see {py:func}`include_subclasses()<cattrs.strategies.include_subclasses>`):
+- The exact list of subclasses that should participate to the union with the `subclasses` argument.
+- Attribute overrides that permit the customization of attributes un/structuring like renaming an attribute.
+
+Here is an example involving both customizations:
+
+```python
+
+>>> from attrs import define
+>>> from cattrs.strategies import include_subclasses
+>>> from cattrs import Converter, override
+
+>>> @define
+... class Parent:
+...     a: int
+
+>>> @define
+... class Child(Parent):
+...     b: str
+
+>>> converter = Converter()
+>>> include_subclasses(
+...     Parent,
+...     converter,
+...     subclasses=(Parent, Child),
+...     overrides={"b": override(rename="c")}
+... )
+
+>>> converter.unstructure(Child(a=1, b="foo"), unstructure_as=Parent)
+{'a': 1, 'c': 'foo'}
+
+>>> converter.structure({'a': 1, 'c': 'foo'}, Parent)
+Child(a=1, b='foo')
+```

docs/structuring.md

@@ -280,7 +280,7 @@ the first time an appropriate union is structured.
 To support arbitrary unions, register a custom structuring hook for the union
 (see [Registering custom structuring hooks](structuring.md#registering-custom-structuring-hooks)).
 
-Another option is to use a custom tagged union strategy (see [Strategies - Tagged Unions](strategies.md#tagged-unions)).
+Another option is to use a custom tagged union strategy (see [Strategies - Tagged Unions](strategies.md#tagged-unions-strategy)).
 
 ### `typing.Final`
 
@@ -456,6 +456,8 @@ attributes holding `attrs` classes and dataclasses.
 B(b=A(a=1))
 ```
 
+Finally, if an `attrs` or `dataclass` class uses inheritance and as such has one or several subclasses, it can be structured automatically to its exact subtype by using the [include subclasses](strategies.md#include-subclasses-strategy) strategy.
+
 ## Registering Custom Structuring Hooks
 
 _cattrs_ doesn't know how to structure non-_attrs_ classes by default,

docs/unions.md

@@ -9,7 +9,7 @@ converter customization (since there are many ways of handling unions).
 ## Unstructuring unions with extra metadata
 
 ```{note}
-_cattrs_ comes with the [tagged unions strategy](strategies.md#tagged-unions) for handling this exact use-case since version 22.3.
+_cattrs_ comes with the [tagged unions strategy](strategies.md#tagged-unions-strategy) for handling this exact use-case since version 23.1.
 The example below has been left here for educational purposes, but you should prefer the strategy.
 ```
 

docs/unstructuring.md

@@ -161,7 +161,7 @@ _attrs_ classes and dataclasses are supported out of the box.
 
 ## Mixing and Matching Strategies
 
-Converters publicly expose two helper metods, {meth}`Converter.unstructure_attrs_asdict() <cattrs.BaseConverter.unstructure_attrs_asdict>`
+Converters publicly expose two helper methods, {meth}`Converter.unstructure_attrs_asdict() <cattrs.BaseConverter.unstructure_attrs_asdict>`
 and {meth}`Converter.unstructure_attrs_astuple() <cattrs.BaseConverter.unstructure_attrs_astuple>`.
 These methods can be used with custom unstructuring hooks to selectively apply one strategy to instances of particular classes.
 

src/cattrs/strategies/_subclasses.py

@@ -42,15 +42,26 @@ def include_subclasses(
     overrides: Optional[Dict[str, AttributeOverride]] = None,
 ) -> None:
     """
-    Modify the given converter so that the attrs/dataclass `cl` is un/structured as if
-    it was a union of itself and all its subclasses that are defined at the time when
-    this strategy is applied.
-
-    Subclasses are detected using the `__subclasses__` method, or they can be explicitly
-    provided.
-
-    overrides is a mapping of some or all the parent class field names to attribute
-    overrides instantiated with :func:`cattrs.gen.override`
+    Configure the converter so that the attrs/dataclass `cl` is un/structured as if it
+    was a union of itself and all its subclasses that are defined at the time when this
+    strategy is applied.
+
+    :param cl: A base `attrs` or `dataclass` class.
+    :param converter: The `Converter` on which this strategy is applied. Do note that
+        the strategy does not work for a :class:`cattrs.BaseConverter`.
+    :param subclasses: A tuple of sublcasses whose ancestor is `cl`. If left as `None`,
+        subclasses are detected using recursively the `__subclasses__` method of `cl`
+        and its descendents.
+    :param union_strategy: A callable of two arguments passed by position
+        (`subclass_union`, `converter`) that defines the union strategy to use to
+        disambiguate the subclasses union. If `None` (the default), the automatic unique
+        field disambiguation is used which means that every single subclass
+        participating in the union must have an attribute name that does not exist in
+        any other sibling class.
+    :param overrides: a mapping of `cl` attribute names to overrides (instantiated with
+        :func:`cattrs.gen.override`) to customize un/structuring.
+
+    .. versionadded:: 23.1.0
     """
     # Due to https://github.com/python-attrs/attrs/issues/1047
     collect()