From b5fffa444f97294e55004fa770e6d8e38b9968c3 Mon Sep 17 00:00:00 2001 From: quartox Date: Tue, 23 May 2017 14:18:24 -0700 Subject: [PATCH 1/4] Move variance docs to new page --- docs/source/common_issues.rst | 46 ----------------------------------- docs/source/index.rst | 1 + docs/source/variance.rst | 45 ++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 46 deletions(-) create mode 100644 docs/source/variance.rst diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst index 2501acd28fc0..3477d906bc46 100644 --- a/docs/source/common_issues.rst +++ b/docs/source/common_issues.rst @@ -180,52 +180,6 @@ not support ``sort()``) as a list and sort it in-place: # Type of x is List[int] here. x.sort() # Okay! -.. _invariance-vs-covariance: - -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 -unexpected errors when combined with type inference. For example: - -.. code-block:: python - - class A: ... - class B(A): ... - - lst = [A(), A()] # Inferred type is List[A] - new_lst = [B(), B()] # inferred type is List[B] - lst = new_lst # mypy will complain about this, because List is invariant - -Possible strategies in such situations are: - -* Use an explicit type annotation: - - .. code-block:: python - - new_lst: List[A] = [B(), B()] - lst = new_lst # OK - -* Make a copy of the right hand side: - - .. code-block:: python - - lst = list(new_lst) # Also OK - -* Use immutable collections as annotations whenever possible: - - .. code-block:: python - - def f_bad(x: List[A]) -> A: - return x[0] - f_bad(new_lst) # Fails - - def f_good(x: Sequence[A]) -> A: - return x[0] - f_good(new_lst) # OK - Declaring a supertype as variable type -------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 90cc74941da8..1106053e2822 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,6 +25,7 @@ Mypy is a static type checker for Python. duck_type_compatibility common_issues generics + variance supported_python_features additional_features command_line diff --git a/docs/source/variance.rst b/docs/source/variance.rst new file mode 100644 index 000000000000..4ce2584ccb3d --- /dev/null +++ b/docs/source/variance.rst @@ -0,0 +1,45 @@ +.. _invariance-vs-covariance: + +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 +unexpected errors when combined with type inference. For example: + +.. code-block:: python + + class A: ... + class B(A): ... + + lst = [A(), A()] # Inferred type is List[A] + new_lst = [B(), B()] # inferred type is List[B] + lst = new_lst # mypy will complain about this, because List is invariant + +Possible strategies in such situations are: + +* Use an explicit type annotation: + + .. code-block:: python + + new_lst: List[A] = [B(), B()] + lst = new_lst # OK + +* Make a copy of the right hand side: + + .. code-block:: python + + lst = list(new_lst) # Also OK + +* Use immutable collections as annotations whenever possible: + + .. code-block:: python + + def f_bad(x: List[A]) -> A: + return x[0] + f_bad(new_lst) # Fails + + def f_good(x: Sequence[A]) -> A: + return x[0] + f_good(new_lst) # OK From cdfd1627766ee8370ccef23611733a898d9bf0dc Mon Sep 17 00:00:00 2001 From: Jesse Lord Date: Tue, 23 May 2017 14:39:11 -0700 Subject: [PATCH 2/4] Update variance.rst --- docs/source/variance.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/variance.rst b/docs/source/variance.rst index 4ce2584ccb3d..3e79bbcb22aa 100644 --- a/docs/source/variance.rst +++ b/docs/source/variance.rst @@ -1,4 +1,3 @@ -.. _invariance-vs-covariance: Invariance vs covariance ======================== From 9ad1698f77af89312679e259a3612c3bedfcfd7f Mon Sep 17 00:00:00 2001 From: quartox Date: Tue, 23 May 2017 14:51:11 -0700 Subject: [PATCH 3/4] Revert and change variance anchor --- docs/source/common_issues.rst | 46 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 - docs/source/variance.rst | 45 ---------------------------------- 3 files changed, 46 insertions(+), 46 deletions(-) delete mode 100644 docs/source/variance.rst diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst index 3477d906bc46..d26b049daf51 100644 --- a/docs/source/common_issues.rst +++ b/docs/source/common_issues.rst @@ -180,6 +180,52 @@ not support ``sort()``) as a list and sort it in-place: # Type of x is List[int] here. x.sort() # Okay! +.. _variance + +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 +unexpected errors when combined with type inference. For example: + +.. code-block:: python + + class A: ... + class B(A): ... + + lst = [A(), A()] # Inferred type is List[A] + new_lst = [B(), B()] # inferred type is List[B] + lst = new_lst # mypy will complain about this, because List is invariant + +Possible strategies in such situations are: + +* Use an explicit type annotation: + + .. code-block:: python + + new_lst: List[A] = [B(), B()] + lst = new_lst # OK + +* Make a copy of the right hand side: + + .. code-block:: python + + lst = list(new_lst) # Also OK + +* Use immutable collections as annotations whenever possible: + + .. code-block:: python + + def f_bad(x: List[A]) -> A: + return x[0] + f_bad(new_lst) # Fails + + def f_good(x: Sequence[A]) -> A: + return x[0] + f_good(new_lst) # OK + Declaring a supertype as variable type -------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 1106053e2822..90cc74941da8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,7 +25,6 @@ Mypy is a static type checker for Python. duck_type_compatibility common_issues generics - variance supported_python_features additional_features command_line diff --git a/docs/source/variance.rst b/docs/source/variance.rst deleted file mode 100644 index 4ce2584ccb3d..000000000000 --- a/docs/source/variance.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _invariance-vs-covariance: - -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 -unexpected errors when combined with type inference. For example: - -.. code-block:: python - - class A: ... - class B(A): ... - - lst = [A(), A()] # Inferred type is List[A] - new_lst = [B(), B()] # inferred type is List[B] - lst = new_lst # mypy will complain about this, because List is invariant - -Possible strategies in such situations are: - -* Use an explicit type annotation: - - .. code-block:: python - - new_lst: List[A] = [B(), B()] - lst = new_lst # OK - -* Make a copy of the right hand side: - - .. code-block:: python - - lst = list(new_lst) # Also OK - -* Use immutable collections as annotations whenever possible: - - .. code-block:: python - - def f_bad(x: List[A]) -> A: - return x[0] - f_bad(new_lst) # Fails - - def f_good(x: Sequence[A]) -> A: - return x[0] - f_good(new_lst) # OK From e45913024a1ebb0cd33e616fe0cdd6cd1d63bec3 Mon Sep 17 00:00:00 2001 From: Jesse Lord Date: Fri, 26 May 2017 15:00:03 -0700 Subject: [PATCH 4/4] Update revision_history.rst --- docs/source/revision_history.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/revision_history.rst b/docs/source/revision_history.rst index dd74dadd244e..98f6495dd188 100644 --- a/docs/source/revision_history.rst +++ b/docs/source/revision_history.rst @@ -31,7 +31,7 @@ List of major changes: * Add :ref:`variance-of-generics`. - * Add :ref:`invariance-vs-covariance`. + * Add :ref:`variance`. * Updates to :ref:`python-36`.