diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index e04fc8a8b..9c3773c7f 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -11,6 +11,7 @@ Development workflow lang-changes development-cycle stdlib + type-annotations extension-modules c-api grammar diff --git a/developer-workflow/type-annotations.rst b/developer-workflow/type-annotations.rst new file mode 100644 index 000000000..30c42264a --- /dev/null +++ b/developer-workflow/type-annotations.rst @@ -0,0 +1,28 @@ +.. _type-annotations: + +================= +Type annotations +================= + +CPython does not generally add type annotations to modules in the standard +library's ``Lib`` directory. Static type checkers use the stubs maintained in +`typeshed `__ for standard-library APIs. +Keeping those stubs separate lets typing tools update their descriptions +independently of Python's release cycle. + +There are exceptions. Some standard-library modules and CPython development +tools already contain annotations. When adding or changing annotated code, +make sure the annotations are checked by the project's type-checking tools; +unchecked annotations can become misleading or invalid. Do not add annotations +to a standard-library module solely to provide type information to users. + +This guidance describes the current practice, rather than a rule that every +existing annotation must be removed. The practice and rationale are discussed +in `Static type annotations in CPython +`__. + +CPython's user-facing documentation is maintained separately from the Python +source code. When a type is useful to readers, include a clear, readable type +description in the documentation following the usual :ref:`documentation +guidelines `; do not copy complex checker-oriented annotations +without considering whether they help the reader.