From 2ed11e367d6b8672cbd95f91adf59dbb44dbe6ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 17 Dec 2021 15:09:51 -0500 Subject: [PATCH 1/3] DOC: update documentation of type annotation (PEP 585) --- .../development/contributing_codebase.rst | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index 4cea030546635..62891730d218b 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -303,7 +303,7 @@ pandas strongly encourages the use of :pep:`484` style type hints. New developme Style guidelines ~~~~~~~~~~~~~~~~ -Types imports should follow the ``from typing import ...`` convention. So rather than +Type imports should follow the ``from typing import ...`` convention. Some types do not need to be imported since :pep:`585` as some builtin constructs, such as ``list`` and ``tuple``, can directly be used for type annotations. So rather than .. code-block:: python @@ -315,21 +315,31 @@ You should write .. code-block:: python - from typing import List, Optional, Union + primes: list[int] = [] - primes: List[int] = [] +``Optional`` should be avoided in favor of the shorter ``| None``, so instead of -``Optional`` should be used where applicable, so instead of +.. code-block:: python + + from typing import Union + + maybe_primes: list[Union[int, None]] = [] + +or .. code-block:: python - maybe_primes: List[Union[int, None]] = [] + from typing import Optional + + maybe_primes: list[Optional[int]] = [] You should write .. code-block:: python - maybe_primes: List[Optional[int]] = [] + from __future__ import annotations + + maybe_primes: list[int | None] = [] In some cases in the code base classes may define class variables that shadow builtins. This causes an issue as described in `Mypy 1775 `_. The defensive solution here is to create an unambiguous alias of the builtin and use that without your annotation. For example, if you come across a definition like From e1419cfe83825f88b55c8feea0d7c57c72759ed5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 17 Dec 2021 17:55:03 -0500 Subject: [PATCH 2/3] pre-commit --- doc/source/development/contributing_codebase.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index 62891730d218b..da1539e0f4aab 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -325,7 +325,7 @@ You should write maybe_primes: list[Union[int, None]] = [] -or +or .. code-block:: python @@ -338,7 +338,7 @@ You should write .. code-block:: python from __future__ import annotations - + maybe_primes: list[int | None] = [] In some cases in the code base classes may define class variables that shadow builtins. This causes an issue as described in `Mypy 1775 `_. The defensive solution here is to create an unambiguous alias of the builtin and use that without your annotation. For example, if you come across a definition like From f9518b4333da2191b6dbc441ba28084d96d2facf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 17 Dec 2021 21:59:39 -0500 Subject: [PATCH 3/3] ignore flake8; remove 'as' --- doc/source/development/contributing_codebase.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index da1539e0f4aab..5d00e514e253e 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -303,7 +303,7 @@ pandas strongly encourages the use of :pep:`484` style type hints. New developme Style guidelines ~~~~~~~~~~~~~~~~ -Type imports should follow the ``from typing import ...`` convention. Some types do not need to be imported since :pep:`585` as some builtin constructs, such as ``list`` and ``tuple``, can directly be used for type annotations. So rather than +Type imports should follow the ``from typing import ...`` convention. Some types do not need to be imported since :pep:`585` some builtin constructs, such as ``list`` and ``tuple``, can directly be used for type annotations. So rather than .. code-block:: python @@ -337,7 +337,7 @@ You should write .. code-block:: python - from __future__ import annotations + from __future__ import annotations # noqa: F404 maybe_primes: list[int | None] = []