warnings.catch_warnings: undocumented arguments (category, lineno, append)

[lebigot]

Documentation

The documentation for warnings.catch_warnings (Python 3.12.5) does not describe what its category, lineno and append arguments do.

Documenting what these arguments do would arguably allow users to use them, or to use it in a more robust way (than by trial and error, and by making assumptions that may turn incorrect in the future).

Thanks!

Linked PRs

• gh-123230
• gh-123231
• gh-124527
• gh-124528

[picnixz]

The category and lineno are documented at the top of the file: https://docs.python.org/3.12/library/warnings.html#the-warnings-filter and I assume that they would have the same meanings. The append is documented in https://docs.python.org/3.12/library/warnings.html#warnings.filterwarnings and I believe this also has the same meanings. The catch_warnings is just below so I believe it was decided not to duplicate the docs. We could however add a note saying that the parameters have the same meaning as in XXX function, or something like that.

[lebigot]

Thanks for the follow up!

I would also assume that they have the same meaning, but without any explicit mention this is only guesswork that leaves users with the fear of writing code based on some incorrect assumption.

Also, arguably, users looking for a quick reference currently have to parse the whole document, which makes a lot of people waste time (and leaves them guessing anyway).

Pointers to the semantics of these arguments would thus indeed be very useful!

[nanjekyejoannah]

Fixed in the attached merged PR

[lebigot]

Thanks for making explicit the semantics of category and lineno.

Again, it would be nice if the semantics of append could be defined too—if I'm not mistaken, the pull requests currently linked to this issue don't address this point.