From 90b39105b768d6fed0a085ee77915b3cc8f95f3b Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 16 Jul 2025 16:10:46 +0200 Subject: [PATCH 1/2] Add a tutorial for external libraries --- docs/guides/writing_stubs.rst | 3 +- docs/index.rst | 11 +++++++ docs/tutorials/external_libraries.rst | 43 +++++++++++++++++++++++++++ docs/tutorials/index.rst | 15 ++++++++++ 4 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 docs/tutorials/external_libraries.rst create mode 100644 docs/tutorials/index.rst diff --git a/docs/guides/writing_stubs.rst b/docs/guides/writing_stubs.rst index 0cbf6a7c2..23966933a 100644 --- a/docs/guides/writing_stubs.rst +++ b/docs/guides/writing_stubs.rst @@ -5,7 +5,8 @@ Writing and Maintaining Stub Files ********************************** Stub files are a means of providing type information for Python modules. -For a full reference, refer to :ref:`stub-files`. +For a quick introduction, see :ref:`external_libraries`. For a full reference, +refer to :ref:`distributing-type`. Maintaining stubs can be a little cumbersome because they are separated from the implementation. This page lists some tools that make writing and maintaining diff --git a/docs/index.rst b/docs/index.rst index 0dfdf131d..235544880 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,17 @@ Static Typing with Python ************************* +Tutorials +========= + +.. + Keep in sync with tutorials/index.rst. + +.. toctree:: + :maxdepth: 1 + + tutorials/external_libraries + Guides ====== diff --git a/docs/tutorials/external_libraries.rst b/docs/tutorials/external_libraries.rst new file mode 100644 index 000000000..ef24097e0 --- /dev/null +++ b/docs/tutorials/external_libraries.rst @@ -0,0 +1,43 @@ +.. _external_libraries: + +************************ +Using External Libraries +************************ + +.. seealso:: + If you are looking for information on how to write type hints for + external libraries, see the :ref:`writing_stubs` guide. + +Many external libraries -- whether installed from the +`Python Package Index `_ (PyPI) or from other sources -- +provide their own type hints. This is indicated by the presence of a +``py.typed`` file in the library's root directory. If you install such a +library, you can use it with any type checker without any additional +configuration. + +Type hints can either be included in the library's source code the same way +as in your own code, or they can be provided in separate so-called +*stub files*. Stub files are named ``.pyi`` and contain only type +hints, without any implementation. + +For libraries that don't include their own type hints, a separate +*stub package* may provice them. These stub packages are often written by the +library authors themselves, by the contributors to the +`typeshed `_ project, or by third-party +contributors. These packages are usually named ``types-`` +or ``-stubs``, where ```` is the name of the library. These +packages can be installed from PyPI as usual, and they will be automatically +discovered by type checkers:: + + pip install requests types-requests + +.. warning:: + + The usual security considerations apply when installing third-party + packages. Only install packages from sources you trust. Stub packages + have the same security implications as any other package. + +.. + TODO: Once development dependencies are supported by pyproject.toml, + and described in https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ + we should recommend installing type stubs as a development dependency. diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..f84673dad --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,15 @@ +:orphan: + +********************* +Type System Tutorials +********************* + +.. + Keep in sync with docs/index.rst. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + external_libraries From 270ff68825473358862c7eb8b2fa43f4b663ddbe Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Mon, 11 Aug 2025 16:03:27 +0200 Subject: [PATCH 2/2] Copy editing --- docs/tutorials/external_libraries.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/external_libraries.rst b/docs/tutorials/external_libraries.rst index ef24097e0..66a1d5452 100644 --- a/docs/tutorials/external_libraries.rst +++ b/docs/tutorials/external_libraries.rst @@ -21,13 +21,12 @@ as in your own code, or they can be provided in separate so-called hints, without any implementation. For libraries that don't include their own type hints, a separate -*stub package* may provice them. These stub packages are often written by the +*stub package* may provide them. These stub packages are often written by the library authors themselves, by the contributors to the `typeshed `_ project, or by third-party contributors. These packages are usually named ``types-`` -or ``-stubs``, where ```` is the name of the library. These -packages can be installed from PyPI as usual, and they will be automatically -discovered by type checkers:: +or ``-stubs``. These packages can be installed from PyPI as usual, and +they will be automatically discovered by type checkers:: pip install requests types-requests