From af8b6dde94c950e6f4c624cb0e1a863108582f9c Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Tue, 4 Apr 2023 21:39:01 -0700 Subject: [PATCH 1/2] stubtest: improve allowlist documentation Could help with e.g. https://github.com/matplotlib/matplotlib/pull/24976 --- docs/source/stubtest.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index 5ec80f9c41de9..ae2e3435e8d11 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -122,14 +122,29 @@ The rest of this section documents the command line interface of stubtest. allowlists. Allowlists can be created with --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 + When introducing stubtest to an existing project, this is an easy way to + silence all existing errors. + .. option:: --ignore-unused-allowlist Ignore unused allowlist entries + By default, stubtest will complain if an allowlist entry is not necessary + for stubtest to pass successfully. + + 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 + ``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 From 9175eebee93b9302cec82d59c0de6b86139b600c Mon Sep 17 00:00:00 2001 From: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Date: Wed, 5 Apr 2023 10:42:43 -0700 Subject: [PATCH 2/2] Update docs/source/stubtest.rst Co-authored-by: Alex Waygood --- docs/source/stubtest.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index ae2e3435e8d11..59889252f0569 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -136,8 +136,8 @@ The rest of this section documents the command line interface of stubtest. Ignore unused allowlist entries - By default, stubtest will complain if an allowlist entry is not necessary - for stubtest to pass successfully. + Without this option enabled, the default is for stubtest to complain if an + allowlist entry is not necessary for stubtest to pass successfully. Note if an allowlist entry is a regex that matches the empty string, stubtest will never consider it unused. For example, to get