Python: Clarify if order of docstring sections is fixed

[hassec]

The python style guide mentions the docstring sections Args, Returns/Yields and Raises but does not clearly specify whether their order is enforced.

All examples show

Args: ...

Returns: ...

Raises: ...

Should this be taken as the only acceptable order? Or would e.g. Raises: before Returns: be allowed?

Question arose in danymat/neogen#194

[hassec]

@gpshead, even just a confirmation whether google tooling currently enforces a specific order would be useful.

[vapier]

yes, Args should always come before Returns/Yields. Raises should be after those.

[hassec]

Thank you @vapier 😊

[ColinKennedy]

Out of curiosity I'd like to ask a couple things

1. Does GoogleDocstringChecker explicitly enforce this section order?
2. If so, what is the underlying reason for placing Raises: after Returns:? To me the more appropriate thing would be Args: -> [Raises: ->] Returns: because the start of a function is the input, args, and a raise interrupts a return, so Raises: is "between" the input arguments and its expected return.

[vapier]

GoogleDocstringChecker does not check ordering. we prob should add that. CrOS's docstring checker does and has for ages fwiw.

while not explicitly stated, you can see example docstrings using this order in the style guide. as with the first rule, be consistent, it follows that this order is what the guide assumes.

wrt Raises ordering, i understand your point about docs reflecting code flow, but i would argue that:

1. functions not raising exceptions explicitly is pretty common which means many docstrings would be Args -> Returns (or just Args or just Returns), so putting Raises at the end is a bit more consistent.
2. the docstring content is for programmers to understand how to use the API, and it should focus on common usage, and raising exceptions is ... exceptional. programmers would primarily care about Args ("how do i call this thing"), then secondarily care about Returns ("how do i use the result"). only sometimes would specific exceptions be handled by the caller to do something else (and not be a lame log+re-raise trampoline), at which point people would look at Raises. so sticking the uncommon content right between the two most common blocks doesn't make sense.

[ColinKennedy]

As long as it's an enforced expectation that makes me more comfortable recommending this order to others as it comes up in future PRs. And the reasoning is understandable (preferring the most common case). Thank you!