diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst index e674132280357..a48c4405084ec 100644 --- a/docs/source/common_issues.rst +++ b/docs/source/common_issues.rst @@ -303,9 +303,13 @@ See :ref:`type-narrowing` for more information. Invariance vs covariance ------------------------ -Most mutable generic collections are invariant, and mypy considers all -user-defined generic classes invariant by default -(see :ref:`variance-of-generics` for motivation). This could lead to some +Most mutable generic collections are invariant. When using the legacy +``TypeVar`` syntax, mypy considers all user-defined generic classes invariant +by default (see :ref:`variance-of-generics` for motivation). When using the +:pep:`695` syntax (``class MyClass[T]: ...``), variance is inferred from +usage rather than defaulting to invariant. + +The fact that mutable sequences are usually invariant can lead to some unexpected errors when combined with type inference. For example: .. code-block:: python