diff --git a/docs/guides/writing_stubs.rst b/docs/guides/writing_stubs.rst index 0cbf6a7c..23966933 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 7bd07ba3..7f59e7b6 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 00000000..66a1d545 --- /dev/null +++ b/docs/tutorials/external_libraries.rst @@ -0,0 +1,42 @@ +.. _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 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``. 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 00000000..f84673da --- /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