[rr-]

Each Problem from try_parse() now has a code, a short name that says what is wrong. Tools built on top, such as a linter, can match on it or let users silence one by name. Messages may change between versions. Codes don't.

>>> try_parse("Short.\n\nArgs:\n    x: X.\n    no colon here\n", "google").problems
[Problem(line=5, code='missing-colon', message="Expected a colon in 'no colon here'.")]

The codes, documented on the Problem class:

Code	Meaning
bad-field	A ReST or Epydoc field that cannot be read, like :param x with no closing colon
wrong-arguments	A field head with too many or too few words, like :param a b c d:
mixed-returns-and-yields	An Epydoc docstring with both @return and @yield
missing-colon	A Google item with no colon, in a section of several items
missing-name	A Google params section holding text and no named item
no-items	A Google section whose items cannot be told apart by indent

ParseError is unchanged. The code of what it reports is on error.problems[0].code.

This also checks that parsing fails only with problems or a ParseError. A new test mutates every case input in every style and fails on any other exception, on a code the docs don't list, or on a line outside the docstring. Fuzzing turned up no crashes in the parsers themselves: about 190k stdlib, generated and whitespace-variant docstrings plus 180k mutated ones. It did find two in parse_from_object(), fixed in their own commit:

• parse_from_object(int) and parse_from_object(sys) raised TypeError, because built-ins have no source to read attribute docstrings from. They now parse without them.
• An object whose __doc__ is not a string, such as collections._tuplegetter, whose __doc__ is a descriptor, raised TypeError from inside the parser. It now parses as having no docstring.

Exceptions raised by a user's parse_item hook still propagate from both parse() and try_parse(). That's the user's code, not docstring text.

Parity against main: 0 of 29,074 docstrings differ. Codes aren't part of what the tool compares, and no message changed. Bench on 3.8: every workload is 0.98–1.03x of main.