Repository navigation
google: read bare names and wrapped lines in items - #184
Merged
Merged
Conversation
In a params or raises section, a line at the items' indent with no head, such as wrapped prose that was not indented, went on as an item of its own, or a missing-colon problem. It now goes on with the item before. A param's name alone on its line, as in "x" or "x (int)", with its description indented below or none, is now an item instead of a missing-colon problem. A colon inside the parentheses, as in "x (int, default: 3): text", no longer ends the head. A description whose first line is indented further than the rest is composed below its head, so that it reads back the same.
Under Returns or Yields, a type of several words before the colon, as in "list of str: text" or "int or None: text", was read as part of the description. Two or three type words joined by "of", "or" or "|" are now the return's type. Words in a row with no joiner between them, as in "The value: text", are still a sentence.
This was referenced Nov 7, 2026
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.
Three changes to items in Google params sections (
Args:,Attributes:,Keyword Args:and the like), and one to raises sections:xorx (int), with its description indented below it or none, is now an item. It used to be amissing-colonproblem.x, ylist) with an optional(type), before a colon or alone on the line, or at most two words before a colon, as intotal_attempts Optional[int]:, which google-auth writes. Only the first item of a section can still be amissing-colonproblem.x (int, default: 3): text, no longer ends the head, so that param gets typeintand default3.To keep round trips, compose now writes a description whose first line is indented further than the rest on the line below its head.
Case diffs:
corpus/google-auth/..._get_cert_config_path: used to raise on a wrapped line, and now parses, with the wrapped line in the description. Auto now picks Google for it instead of ReST.corpus/rich/rich.cells._split_text: used to raise oncell_position Offset in cells., which has no colon. That line now continuestext's description.google/google_typed_parameter_delimiters_05:value (int)followed by a line): descriptionis now a bare item with description): description, instead of a head wrapped over three lines. This one is open to question, though the text is all still there.google/long_parse_error_01: the input was a single long word, which is now a bare name. I changed it to long words with spaces, so it still tests the error excerpt.test_try_parse: the two Google problem tests now put the line with no colon first, since a later one continues the item before it.test_invariants: generated 166 and 378 (Google, BODY) round trip now and leave the exclusion list.Parity against origin/main: 854 of 29183 docstrings differ, case 3, stdlib 17, generated 834. 683 parse only in this tree (case 2, stdlib 9, generated 672), mostly bare names that used to be problems. None parse only in base, so no stdlib docstring newly makes strict
parseraise. The stdlib diffs are mostly pydoc-stylename -- textlists underArguments:, which are now one item (or one problem) instead of one per line. Auto parsing changes for 589 docstrings, nearly all generated, because Google now parses them.