From 31941c54198ce326fee7177b3f6a9912f797f9d8 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 5 Oct 2025 10:14:23 +0300 Subject: [PATCH 1/4] [stubtest] Improve `allowlist` docs with better example Also fix markup in several places. --- docs/source/stubtest.rst | 65 +++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 7 deletions(-) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index 59889252f056..c52b153a2a08 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -99,8 +99,59 @@ to mypy build errors". In this case, you will need to mitigate those errors before stubtest will run. Despite potential overlap in errors here, stubtest is not intended as a substitute for running mypy directly. +Allowlist +********* + If you wish to ignore some of stubtest's complaints, stubtest supports a -pretty handy allowlist system. +pretty handy :option:`--allowlist` system. + +Let's say that you have this python module called ``ex``: + +.. code-block:: python + + try: + import optional_expensive_dep + except ImportError: + optional_expensive_dep = None + + first = 1 + if optional_expensive_dep: + second = 2 + +Let's say that you can't install ``optional_expensive_dep`` in CI for some reason, +but you still want to include ``second: int`` in the stub file: + +.. code-block:: python + + first: int + second: int + +In this case stubtest will correctly complain: + +.. code-block:: shell + + error: ex.second is not present at runtime + Stub: in file /.../ex.pyi:2 + builtins.int + Runtime: + MISSING + + Found 1 error (checked 1 module) + +To fix this, you can add an ``allowlist`` entry: + +.. code-block: ini + + # Allowlist entries in `allowlist.txt` file: + + # Does not exist if `optional_expensive_dep` is not installed: + ex.second + +And now when running stubtest with ``--allowlist=allowlist.txt``, +no errors will be generated anymore. + +CLI +*** The rest of this section documents the command line interface of stubtest. @@ -119,15 +170,15 @@ The rest of this section documents the command line interface of stubtest. .. option:: --allowlist FILE Use file as an allowlist. Can be passed multiple times to combine multiple - allowlists. Allowlists can be created with --generate-allowlist. Allowlists - support regular expressions. + allowlists. Allowlists can be created with :option:`--generate-allowlist`. + Allowlists support regular expressions. The presence of an entry in the allowlist means stubtest will not generate any errors for the corresponding definition. .. option:: --generate-allowlist - Print an allowlist (to stdout) to be used with --allowlist + Print an allowlist (to stdout) to be used with :option:`--allowlist`. When introducing stubtest to an existing project, this is an easy way to silence all existing errors. @@ -141,17 +192,17 @@ The rest of this section documents the command line interface of stubtest. Note if an allowlist entry is a regex that matches the empty string, stubtest will never consider it unused. For example, to get - `--ignore-unused-allowlist` behaviour for a single allowlist entry like + ``--ignore-unused-allowlist`` behaviour for a single allowlist entry like ``foo.bar`` you could add an allowlist entry ``(foo\.bar)?``. This can be useful when an error only occurs on a specific platform. .. option:: --mypy-config-file FILE - Use specified mypy config file to determine mypy plugins and mypy path + Use specified mypy config *file* to determine mypy plugins and mypy path .. option:: --custom-typeshed-dir DIR - Use the custom typeshed in DIR + Use the custom typeshed in *DIR* .. option:: --check-typeshed From 2ce35525e6bdd47727377c53de03cbcba74ab28a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 5 Oct 2025 07:16:14 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/stubtest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index c52b153a2a08..58c8b71fb37a 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -135,7 +135,7 @@ In this case stubtest will correctly complain: builtins.int Runtime: MISSING - + Found 1 error (checked 1 module) To fix this, you can add an ``allowlist`` entry: From 7eae60f20acdd4b2e063708033caa71f48195ce3 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 5 Oct 2025 13:50:48 +0300 Subject: [PATCH 3/4] Update stubtest.rst --- docs/source/stubtest.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index 58c8b71fb37a..bd3e4c3f5ced 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -150,6 +150,18 @@ To fix this, you can add an ``allowlist`` entry: And now when running stubtest with ``--allowlist=allowlist.txt``, no errors will be generated anymore. +Allowlists also support regular expressions. +They might be useful to ignore many similar errors at once. +If some CI workers have ``optional_expensive_dep`` installed stubtest will complain: + +.. code-block: ini + + note: unused allowlist entry ex.second + Found 1 error (checked 1 module) + +Changing ``ex.second`` to be ``(ex\.second)?`` will make this error optional. +And stubtest will not fail with and without ``optional_expensive_dep``. + CLI *** From ba99258a19a97d5ff664f0b69bf3d73c4a5f8ae7 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 5 Oct 2025 21:32:08 +0300 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Alex Waygood --- docs/source/stubtest.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index bd3e4c3f5ced..e7ea69290b78 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -140,7 +140,7 @@ In this case stubtest will correctly complain: To fix this, you can add an ``allowlist`` entry: -.. code-block: ini +.. code-block:: ini # Allowlist entries in `allowlist.txt` file: @@ -150,17 +150,21 @@ To fix this, you can add an ``allowlist`` entry: And now when running stubtest with ``--allowlist=allowlist.txt``, no errors will be generated anymore. -Allowlists also support regular expressions. -They might be useful to ignore many similar errors at once. -If some CI workers have ``optional_expensive_dep`` installed stubtest will complain: +Allowlists also support regular expressions, +which can be useful to ignore many similar errors at once. +They can also be useful for suppressing stubtest errors that occur sometimes, +but not on every CI run. For example, if some CI workers have +``optional_expensive_dep`` installed, stubtest might complain with this message +on those workers if you had the ``ex.second`` allowlist entry: -.. code-block: ini +.. code-block:: ini note: unused allowlist entry ex.second Found 1 error (checked 1 module) -Changing ``ex.second`` to be ``(ex\.second)?`` will make this error optional. -And stubtest will not fail with and without ``optional_expensive_dep``. +Changing ``ex.second`` to be ``(ex\.second)?`` will make this error optional, +meaning that stubtest will pass whether or not a CI runner +has``optional_expensive_dep`` installed. CLI ***