Skip to content

Read bare types and prose under Google Raises - #165

Merged
rr- merged 1 commit into
mainfrom
rework/28-google-raises
Nov 6, 2026
Merged

rr- merged 1 commit into
mainfrom
rework/28-google-raises

Conversation

@rr-

@rr- rr- commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Google Raises: sections written without the Type: text form made parse() raise ParseError:

>>> parse("Short.\n\nRaises:\n    ValueError\n", "google")
ParseError: Expected a colon in 'ValueError'.
>>> parse("Short.\n\nRaises:\n    Something may go wrong if the input\n    is not what we expect.\n", "google")
ParseError: Expected a colon in 'Something may go wrong if the input'.

Now:

  • A type alone on its line is a raises with that type and no description. Several types work too (KeyError, TypeError, os.error or IOError), as do Sphinx-marked ones (~pkg.Error). A description indented below the type belongs to it, as Numpydoc writes it.
  • A section in which no item starts with a type is one raises with no type, holding the prose. A sentence with a colon in it (If the input is bad: a ValueError.) counts as prose, because the text before its colon has spaces.
  • Mixed sections work item by item: ValueError: Bad. then TypeError gives two raises.
  • : text, with nothing before the colon, gives a raises with no type instead of type_name=''.

Compose writes a type with no description without the colon, and a lone raises with no type as its prose, so both read back the same. A raises with no type among typed ones still composes as : text.

Parity against main: 381 of 29,127 docstrings differ, and every one is about raises.

  • Docstrings with a Google raises section (Raises:, Exceptions:, Except:): 6 case inputs, 1 stdlib and 263 generated. 163 of them used to raise ParseError in parse google and now parse, including the real google-auth docstring OnDemandCredentials.refresh. Some others had garbage types like - TypeError from a bullet list, which is now one raises holding the list. In auto mode these can now pick Google, as for OnDemandCredentials.refresh and the stdlib ssl module docstring, whose Exceptions: section now reads as one typeless raises.
  • The other 3 case inputs and 108 generated docstrings differ only when composed as Google: a raises with a type and no description loses its trailing colon, and a lone typeless raises is written as prose.

Bench on 3.8: parse 0.99–1.01x of main, compose google 1.01–1.02x.

@rr- rr- self-assigned this Nov 6, 2026
A Raises item that was a type alone, such as ValueError, raised
ParseError for its missing colon, and so did a Raises section of plain
prose. A type alone on its line is now a raises with that type, its
description indented below it if any. A section in which no item starts
with a type is one raises with no type, holding the prose. An item
with a colon and nothing before it is a raises with no type.

Compose writes a type with no description without a colon, and a lone
raises with no type as its prose, so both read back the same.
@rr-
rr- force-pushed the rework/28-google-raises branch from 1e60c46 to bd9687d Compare November 6, 2026 17:30
@rr-
rr- merged commit 1db7e3c into main Nov 6, 2026
25 checks passed
@rr-
rr- deleted the rework/28-google-raises branch November 6, 2026 23:51
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