Skip to content

google: read bare names and wrapped lines in items - #184

Merged
rr- merged 2 commits into
mainfrom
rework/42-google-items
Nov 7, 2026
Merged

rr- merged 2 commits into
mainfrom
rework/42-google-items

Conversation

@rr-

@rr- rr- commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Three changes to items in Google params sections (Args:, Attributes:, Keyword Args: and the like), and one to raises sections:

  • A param's name alone on its line, x or x (int), with its description indented below it or none, is now an item. It used to be a missing-colon problem.
  • A line at the items' indent that has no head, such as wrapped prose that wasn't indented, now goes on with the item before it instead of starting a bogus item or raising. This applies to raises sections too. A line counts as a head if it is names (no spaces, or a x, y list) with an optional (type), before a colon or alone on the line, or at most two words before a colon, as in total_attempts Optional[int]:, which google-auth writes. Only the first item of a section can still be a missing-colon problem.
  • A colon inside the brackets, as in x (int, default: 3): text, no longer ends the head, so that param gets type int and default 3.

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 on cell_position Offset in cells., which has no colon. That line now continues text's description.
  • google/google_typed_parameter_delimiters_05: value (int) followed by a line ): description is 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 parse raise. The stdlib diffs are mostly pydoc-style name -- text lists under Arguments:, 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.

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.
@rr-
rr- merged commit 75d41c8 into main Nov 7, 2026
25 checks passed
@rr-
rr- deleted the rework/42-google-items branch November 7, 2026 00:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant