Skip to content

PEP 846: Clarify docstring placement and parser wording #5130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JelleZijlstra merged 1 commit into from
Sep 18, 2026
+9 −8
Merged

PEP 846: Clarify docstring placement and parser wording #5130

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions peps/pep-0846.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ docstrings". This PEP uses the same placement convention for
:py:keyword:`type` statements: a string literal immediately following the
statement becomes the alias's docstring.

If the next logical line after a :py:keyword:`type` statement in the same suite
If the next logical line after a :py:keyword:`type` statement in the same block
is an expression statement consisting of a string literal, that string is the
alias's docstring and is part of the :py:keyword:`type` statement. Comments and
blank lines may appear between the :py:keyword:`type` statement and its
Expand All @@ -90,8 +90,8 @@ semicolon, does not qualify.
"""This is not OtherTimeout's docstring."""

The rule applies wherever a :py:keyword:`type` statement is allowed, including
inside functions, classes, and control-flow suites. The string must be in the
same suite as the alias. A string in a nested or enclosing suite does not
inside functions, classes, and control-flow blocks. The string must be in the
same block as the alias. A string in a nested or enclosing block does not
qualify. Generic aliases follow the same rule:

.. code-block:: python
Expand Down Expand Up @@ -310,11 +310,12 @@ The grammar rule for the :py:keyword:`type` statement gains an optional
group that parses the expression statement on the following logical line.
The ``type_alias_docstring[expr_ty]`` rule uses an action helper that returns
the expression node if it is a string constant.
Otherwise it returns ``NULL`` without setting an error, the group fails, and
the parser backtracks to before the newline. Blank lines and comment-only
lines do not prevent the parser from recognizing the docstring. The string
must be in the same suite as the :py:keyword:`type` statement. The type alias
action extracts the constant's string value and stores it in the ``doc`` field.
Otherwise, the helper returns ``NULL`` without setting an error. This causes
the optional group to fail, so the parser backtracks to before the newline.
Blank lines and comment-only lines do not prevent the parser from recognizing
the docstring. The string must be in the same block as the :py:keyword:`type`
statement. The type alias action extracts the constant's string value and
stores it in the ``doc`` field.

The :py:mod:`pydoc` implementation requests the alias expression in string
format. This evaluation can trigger lazy imports. If evaluation raises an
Expand Down
Loading