From e478b10f6df0e23ae9660626f404be6805637ff9 Mon Sep 17 00:00:00 2001 From: pctablet505 Date: Wed, 15 Jul 2026 18:01:53 +0000 Subject: [PATCH] docs: document that stubtest ignores private stub names Add a section to the stubtest documentation explaining that names beginning with a leading underscore are treated as private to the stub and will not be flagged if missing at runtime. Fixes #15414 --- docs/source/stubtest.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst index 79265ac5029d8..ecdf76fe314d5 100644 --- a/docs/source/stubtest.rst +++ b/docs/source/stubtest.rst @@ -45,6 +45,29 @@ test Python's official collection of library stubs, stubtest will import and execute Python code from the packages it checks. +Private stub names +****************** + +Stubtest treats names in stubs that begin with a leading underscore (e.g., +``_T``) as private to the stub. If such a name does not exist at runtime, +stubtest will not report an error. This is commonly used for :py:class:`TypeVar +` definitions and other type-checking-only helpers that do not +need to be present at runtime. + +For example, the following stub will not produce a "not present at runtime" +error, even though ``_T`` is missing from the implementation: + +.. code-block:: python + + from typing import Generic, TypeVar + + _T = TypeVar("_T") + + class SomeClass(Generic[_T]): ... + +Note that dunder names (such as ``__init__``) are not treated as private by +this rule. + Example *******