From 40cb8ae2cf043c404d2e668400a65c09e560699e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 29 Oct 2021 08:51:29 -0400 Subject: [PATCH 1/7] DOC: local py.typed for development and users --- .gitignore | 2 ++ doc/source/development/contributing_environment.rst | 13 +++++++++++++ doc/source/getting_started/install.rst | 13 +++++++++++++ 3 files changed, 28 insertions(+) diff --git a/.gitignore b/.gitignore index 2c337be60e94e..87224f1d6060f 100644 --- a/.gitignore +++ b/.gitignore @@ -50,6 +50,8 @@ dist *.egg-info .eggs .pypirc +# type checkers +pandas/py.typed # tox testing tool .tox diff --git a/doc/source/development/contributing_environment.rst b/doc/source/development/contributing_environment.rst index 4ea3701dec029..498b96ff47cc8 100644 --- a/doc/source/development/contributing_environment.rst +++ b/doc/source/development/contributing_environment.rst @@ -259,3 +259,16 @@ should already exist. # Build and install pandas python setup.py build_ext -j 4 python -m pip install -e . --no-build-isolation --no-use-pep517 + + +VSCode Integration +------------------ + +Since pandas is not a py.typed library, pyright ships with its own type annotations for pandas. +This break "Go to definition" in VSCode for the pandas code base. You can create an empty py.typed +file to claim that pandas is a py.typed library to make type checkers (including pyright) prioritize +pandas's own type annotations. This makes "Go to definition" work as expected in VSCode. + +.. code-block:: none + + python -c "import pathlib; pathlib.Path('pandas/py.typed').touch()" diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index c054153fe4a43..79dc86b38688c 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -402,3 +402,16 @@ qtpy Clipboard I/O xclip Clipboard I/O on linux xsel Clipboard I/O on linux ========================= ================== ============================================================= + +Type annotations +---------------- + +.. warning:: + + * Pandas is not yet a py.typed library (see `PEP 561 `)! + +To make type checkers aware of pandas's own type annotations, you can create an empty py.typed. + +.. code-block:: none + + python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" From cc95463f1df63f8cbb9acdae74a2a30be7526788 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 29 Oct 2021 09:10:21 -0400 Subject: [PATCH 2/7] fix heading --- doc/source/development/contributing_environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/development/contributing_environment.rst b/doc/source/development/contributing_environment.rst index 498b96ff47cc8..c92c2ad5c019e 100644 --- a/doc/source/development/contributing_environment.rst +++ b/doc/source/development/contributing_environment.rst @@ -261,7 +261,7 @@ should already exist. python -m pip install -e . --no-build-isolation --no-use-pep517 -VSCode Integration +VSCode integration ------------------ Since pandas is not a py.typed library, pyright ships with its own type annotations for pandas. From fea9d1cba11d79fbf4c6f3bc51ddc6938aeff4b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 29 Oct 2021 10:40:50 -0400 Subject: [PATCH 3/7] remove incorrect VSCode integration comment --- doc/source/development/contributing_environment.rst | 13 ------------- doc/source/getting_started/install.rst | 3 ++- 2 files changed, 2 insertions(+), 14 deletions(-) diff --git a/doc/source/development/contributing_environment.rst b/doc/source/development/contributing_environment.rst index c92c2ad5c019e..4ea3701dec029 100644 --- a/doc/source/development/contributing_environment.rst +++ b/doc/source/development/contributing_environment.rst @@ -259,16 +259,3 @@ should already exist. # Build and install pandas python setup.py build_ext -j 4 python -m pip install -e . --no-build-isolation --no-use-pep517 - - -VSCode integration ------------------- - -Since pandas is not a py.typed library, pyright ships with its own type annotations for pandas. -This break "Go to definition" in VSCode for the pandas code base. You can create an empty py.typed -file to claim that pandas is a py.typed library to make type checkers (including pyright) prioritize -pandas's own type annotations. This makes "Go to definition" work as expected in VSCode. - -.. code-block:: none - - python -c "import pathlib; pathlib.Path('pandas/py.typed').touch()" diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index 79dc86b38688c..b95b0e5e3c440 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -410,7 +410,8 @@ Type annotations * Pandas is not yet a py.typed library (see `PEP 561 `)! -To make type checkers aware of pandas's own type annotations, you can create an empty py.typed. +To make type checkers aware of pandas's own type annotations, you can create an empty py.typed file. +This signals to type checkers that pandas is a py.typed library. .. code-block:: none From dd6d1d494dde0e2052d9d25cf2ed2ea08b20cd5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Sat, 30 Oct 2021 23:02:15 -0400 Subject: [PATCH 4/7] re-pharse note and add the same note to whatsnew --- doc/source/getting_started/install.rst | 14 +++++++++----- doc/source/whatsnew/v1.4.0.rst | 17 +++++++++++++++++ 2 files changed, 26 insertions(+), 5 deletions(-) diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index b95b0e5e3c440..a296d519c4685 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -403,16 +403,20 @@ xclip Clipboard I/O on linux xsel Clipboard I/O on linux ========================= ================== ============================================================= -Type annotations ----------------- +Experimenting with type annotations +----------------------------------- .. warning:: - * Pandas is not yet a py.typed library (see `PEP 561 `)! + * Pandas is not yet a `py.typed library `! -To make type checkers aware of pandas's own type annotations, you can create an empty py.typed file. -This signals to type checkers that pandas is a py.typed library. +Until pandas becomes a py.typed library, it is possible to easily experiment with the type +annotations shipped with pandas by creating an empty file named "py.typed" in the pandas +installation folder: .. code-block:: none python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" + +The existance of the py.typed file signals to type checkers that pandas is already a py.typed +library. This makes type checkers aware of the type annotations shipped with pandas. diff --git a/doc/source/whatsnew/v1.4.0.rst b/doc/source/whatsnew/v1.4.0.rst index 7cf8c07683514..b153782bc59b6 100644 --- a/doc/source/whatsnew/v1.4.0.rst +++ b/doc/source/whatsnew/v1.4.0.rst @@ -194,6 +194,23 @@ representation of :class:`DataFrame` objects (:issue:`4889`). df df.to_dict(orient='tight') +.. _whatsnew_140.typing: + +Experimenting with type annotations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pandas is not yet a `py.typed library `! Until +pandas becomes a py.typed library, it is possible to easily experiment with the type +annotations shipped with pandas by creating an empty file named "py.typed" in the pandas +installation folder: + +.. code-block:: none + + python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" + +The existance of the py.typed file signals to type checkers that pandas is already a py.typed +library. This makes type checkers aware of the type annotations shipped with pandas. + .. _whatsnew_140.enhancements.other: Other enhancements From 26d3e89841d4c38d04fadd6b57381333e9052225 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Sat, 30 Oct 2021 23:29:30 -0400 Subject: [PATCH 5/7] fix urls --- doc/source/getting_started/install.rst | 4 ++-- doc/source/whatsnew/v1.4.0.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index a296d519c4685..500f6a09c2550 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -408,7 +408,7 @@ Experimenting with type annotations .. warning:: - * Pandas is not yet a `py.typed library `! + * Pandas is not yet a `py.typed library `_! Until pandas becomes a py.typed library, it is possible to easily experiment with the type annotations shipped with pandas by creating an empty file named "py.typed" in the pandas @@ -418,5 +418,5 @@ installation folder: python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" -The existance of the py.typed file signals to type checkers that pandas is already a py.typed +The existence of the py.typed file signals to type checkers that pandas is already a py.typed library. This makes type checkers aware of the type annotations shipped with pandas. diff --git a/doc/source/whatsnew/v1.4.0.rst b/doc/source/whatsnew/v1.4.0.rst index b153782bc59b6..21c7e68c05723 100644 --- a/doc/source/whatsnew/v1.4.0.rst +++ b/doc/source/whatsnew/v1.4.0.rst @@ -199,7 +199,7 @@ representation of :class:`DataFrame` objects (:issue:`4889`). Experimenting with type annotations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Pandas is not yet a `py.typed library `! Until +Pandas is not yet a `py.typed library `_! Until pandas becomes a py.typed library, it is possible to easily experiment with the type annotations shipped with pandas by creating an empty file named "py.typed" in the pandas installation folder: @@ -208,7 +208,7 @@ installation folder: python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" -The existance of the py.typed file signals to type checkers that pandas is already a py.typed +The existence of the py.typed file signals to type checkers that pandas is already a py.typed library. This makes type checkers aware of the type annotations shipped with pandas. .. _whatsnew_140.enhancements.other: From c4b6f3c04f9606e123eb2636b7f8ee062af695f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Sat, 11 Dec 2021 18:20:39 -0500 Subject: [PATCH 6/7] hedging --- doc/source/getting_started/install.rst | 2 ++ doc/source/whatsnew/v1.4.0.rst | 17 ----------------- 2 files changed, 2 insertions(+), 17 deletions(-) diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index 500f6a09c2550..e6c1a6747ebce 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -409,6 +409,8 @@ Experimenting with type annotations .. warning:: * Pandas is not yet a `py.typed library `_! + The primary purpose of locally declaring pandas as a py.typed library is to test and + improve the builtin type annotations. Until pandas becomes a py.typed library, it is possible to easily experiment with the type annotations shipped with pandas by creating an empty file named "py.typed" in the pandas diff --git a/doc/source/whatsnew/v1.4.0.rst b/doc/source/whatsnew/v1.4.0.rst index 21c7e68c05723..7cf8c07683514 100644 --- a/doc/source/whatsnew/v1.4.0.rst +++ b/doc/source/whatsnew/v1.4.0.rst @@ -194,23 +194,6 @@ representation of :class:`DataFrame` objects (:issue:`4889`). df df.to_dict(orient='tight') -.. _whatsnew_140.typing: - -Experimenting with type annotations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pandas is not yet a `py.typed library `_! Until -pandas becomes a py.typed library, it is possible to easily experiment with the type -annotations shipped with pandas by creating an empty file named "py.typed" in the pandas -installation folder: - -.. code-block:: none - - python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" - -The existence of the py.typed file signals to type checkers that pandas is already a py.typed -library. This makes type checkers aware of the type annotations shipped with pandas. - .. _whatsnew_140.enhancements.other: Other enhancements From 81f5f183da626117d7586bafc8a0cfbe32e0eaf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torsten=20W=C3=B6rtwein?= Date: Fri, 17 Dec 2021 15:18:57 -0500 Subject: [PATCH 7/7] move to contributing_codebase --- .../development/contributing_codebase.rst | 20 +++++++++++++++++++ doc/source/getting_started/install.rst | 20 ------------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index 4cea030546635..8baf103369a13 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -410,6 +410,26 @@ A recent version of ``numpy`` (>=1.21.0) is required for type validation. .. _contributing.ci: +Testing type hints in code using pandas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + * Pandas is not yet a py.typed library (:pep:`561`)! + The primary purpose of locally declaring pandas as a py.typed library is to test and + improve the pandas-builtin type annotations. + +Until pandas becomes a py.typed library, it is possible to easily experiment with the type +annotations shipped with pandas by creating an empty file named "py.typed" in the pandas +installation folder: + +.. code-block:: none + + python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" + +The existence of the py.typed file signals to type checkers that pandas is already a py.typed +library. This makes type checkers aware of the type annotations shipped with pandas. + Testing with continuous integration ----------------------------------- diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index e6c1a6747ebce..c054153fe4a43 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -402,23 +402,3 @@ qtpy Clipboard I/O xclip Clipboard I/O on linux xsel Clipboard I/O on linux ========================= ================== ============================================================= - -Experimenting with type annotations ------------------------------------ - -.. warning:: - - * Pandas is not yet a `py.typed library `_! - The primary purpose of locally declaring pandas as a py.typed library is to test and - improve the builtin type annotations. - -Until pandas becomes a py.typed library, it is possible to easily experiment with the type -annotations shipped with pandas by creating an empty file named "py.typed" in the pandas -installation folder: - -.. code-block:: none - - python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()" - -The existence of the py.typed file signals to type checkers that pandas is already a py.typed -library. This makes type checkers aware of the type annotations shipped with pandas.