Advice for writing and maintaining stub files (#1167)

Author: hauntsaninja

docs/source/guides.rst

@@ -7,4 +7,5 @@ Type System Guides
    :caption: Contents:
 
    libraries
+   writing_stubs
    unreachable

docs/source/libraries.rst

@@ -41,10 +41,8 @@ library:
 
 Inline type annotations simply refers to the use of annotations within your
 ``.py`` files. In contrast, with type stub files, type information lives in
-separate ``.pyi`` files; see :ref:`stubs` for more details.
-
-..
-   TODO: link to a guide for writing stubs above
+separate ``.pyi`` files; see :ref:`stubs` and :ref:`writing_stubs` for more
+details.
 
 We recommend using the inline type annotations approach, since it has the
 following benefits:

docs/source/quality.rst

@@ -1,4 +1,4 @@
-.. _tools:
+.. _testing:
 
 ********************************************
 Testing and Ensuring Type Annotation Quality

docs/source/writing_stubs.rst

@@ -0,0 +1,108 @@
+.. _writing_stubs:
+
+**********************************
+Writing and Maintaining Stub Files
+**********************************
+
+Stub files are a means of providing type information for Python modules.
+For a full reference, refer to :ref:`stubs`.
+
+Maintaining stubs can be a little cumbersome because they are separated from the
+implementation. This page lists some tools that make writing and maintaining
+stubs less painful.
+
+Tools for generating stubs
+==========================
+
+stubgen
+-------
+
+stubgen is a tool bundled with `mypy <https://github.com/python/mypy>`__
+that can be used to generate basic stubs. These stubs serve as a
+basic starting point; most types will default to ``Any``.
+
+.. code-block:: console
+
+    stubgen -p my_great_package
+
+For more details, see `stubgen docs <https://mypy.readthedocs.io/en/stable/stubgen.html>`__.
+
+pyright
+-------
+
+pyright contains a tool that generates basic stubs. Like stubgen, these generated
+stubs serve more as a starting point.
+
+.. code-block:: console
+
+    pyright --createstub my_great_package
+
+For more details, see `pyright docs <https://github.com/microsoft/pyright/blob/main/docs/type-stubs.md#generating-type-stubs-from-command-line>`__.
+
+monkeytype
+----------
+
+monkeytype takes a slightly different approach — you run your code (perhaps via
+your tests) and monkeytype collects the types it observes at runtime to generate
+stubs.
+
+.. code-block:: console
+
+    monkeytype run script.py
+    monkeytype stub my_great_package
+
+For more details, see `monkeytype docs <https://monkeytype.readthedocs.io/en/latest/>`__.
+
+Tools for maintaining stubs
+===========================
+
+stubtest
+--------
+
+stubtest is a tool bundled with `mypy <https://github.com/python/mypy>`__.
+
+stubtest finds inconsistencies between stub files and the implementation. It
+does this by comparing stub definitions to what it finds from importing your
+code and using runtime introspection (via the ``inspect`` module).
+
+.. code-block:: console
+
+    stubtest my_great_package
+
+For more details, see `stubtest docs <https://mypy.readthedocs.io/en/stable/stubtest.html>`__.
+
+flake8-pyi
+----------
+
+flake8-pyi is a `flake8 <https://flake8.pycqa.org/en/latest/>`__ plugin that
+lints common issues in stub files.
+
+.. code-block:: console
+
+    flake8 my_great_package
+
+For more details, see `flake8-pyi docs <https://github.com/PyCQA/flake8-pyi>`__.
+
+Running a type checker on the stubs
+-----------------------------------
+
+Simply running a type checker on the stubs can catch several issues, from simple
+things like detecting missing annotations to more complex things like ensuring
+Liskov substitutability or detecting problematic overloads.
+
+It may be instructive to examine `typeshed <https://github.com/python/typeshed/>`__'s
+`setup for testing stubs <https://github.com/python/typeshed/blob/master/tests/README.md>`__.
+
+..
+   TODO: consider adding examples and configurations for specific type checkers
+
+Type checking usage of your package
+-----------------------------------
+
+If you have access to a codebase that uses your package — perhaps tests for your
+package — running a type checker against it can help you detect issues,
+particularly with false positives.
+
+If your package has some particularly complex aspects, you could even consider
+writing dedicated typing tests for tricky definitions. For more details, see
+:ref:`testing`.