Repository navigation
Read ReST types with spaces in field heads - #164
Merged
Merged
Conversation
A field's head was split on spaces and had to be at most a key, a type and a name, so :param Dict[str, int] x: and :raises A, B: raised ParseError. The words before the name now make one type when they hold together: inside brackets, after a comma, or around or, of and |. Other words in a row, as in :param with too many args:, are still no field.
rr-
force-pushed
the
rework/29-rest-spaced-types
branch
from
November 6, 2026 17:27
e1f2783 to
1f23c42
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A ReST field's head could hold at most a key, one type word and a name, so common real-world fields failed to parse:
Before,
parse()raisedParseError: Expected one or two arguments for a param keyword., andtry_parse()reportedwrong-argumentsand kept the field as text. Now the first gives a paramxwith typeDict[str, int], and the second one raises with typeValueError, TypeError.The words before the name make one type when they hold together: inside brackets (
Callable[[int], str]), after a comma (int, optional), or aroundor,ofand|(int or None,list of str). Other words in a row are still not a field, so:param with too many args:and:returns int str:keep raising, as before. This applies to every param-kind field (:param,:keyword, …), to raises fields, and to:returns/:yields. A single type word is read as before.Composing writes such a type in its own
:type x:or:rtype:field, which reads back the same, in all three renderings.Parity: 0 of 29,123 docstrings differ (case, stdlib and generated), since none of them has a spaced type in a field head. Four new case files cover the new inputs and the one that still fails.
Bench on 3.8: parse is 0.99 to 1.00x of main.