Better documentation for new feature, fix tests

Author: Diego Argueta

changelog.d/140.change.rst

@@ -1,3 +1,30 @@
-It is now possible to use type-variant generics in your dataclasses, such as ``Sequence`` or ``MutableSequence`` instead of ``List``, ``Mapping`` instead of ``Dict``, etc.
+It is now possible to use `type-variant generics`_ in your dataclasses, such as ``Sequence``
+or ``MutableSequence`` instead of ``List``, ``Mapping`` instead of ``Dict``, etc.
 
-This doesn't change any behavior by Desert or Marshmallow. Rather, the primary benefit is getting more flexibility from type checkers. For example, by using ``Mapping`` or ``MutableMapping``, users can pass ``OrderedDict`` to an attribute without MyPy complaining.
+This allows you to hide implementation details from users of your dataclasses. If a field
+in your dataclass works just as fine with a tuple as a list, you no longer need to force
+your users to pass in a ``list`` just to satisfy type checkers.
+
+For example, by using ``Mapping`` or ``MutableMapping``, users can pass ``OrderedDict`` to
+a ``Dict`` attribute without MyPy complaining.
+
+.. code-block:: python
+
+    @dataclass
+    class OldWay:
+        str_list: List[str]
+        num_map: Dict[str, float]
+
+
+    # MyPy will reject this even though Marshmallow works just fine. If you use
+    # type-variant generics, MyPy will accept this code.
+    instance = OldClass([], collections.ChainMap(MY_DEFAULTS))
+
+
+    @dataclass
+    class NewWay:
+        str_list: List[str]                     # Type-invariants still work
+        num_map: MutableMapping[str, float]     # Now generics do too
+
+
+.. _type-variant generics: https://mypy.readthedocs.io/en/stable/generics.html

tests/test_make.py

@@ -525,12 +525,19 @@ class A:
         desert.schema_class(A)
 
 
+T = t.TypeVar("T")
+
+
+class UnknownGeneric(t.Generic[T]):
+    pass
+
+
 def test_raise_unknown_generic(module: DataclassModule) -> None:
     """Raise UnknownType for unknown generics."""
 
     @module.dataclass
     class A:
-        x: t.Iterable[int]
+        x: UnknownGeneric[int]
 
     with pytest.raises(desert.exceptions.UnknownType):
         desert.schema_class(A)