python / cpython

The Python programming language
https://www.python.org
Other
63.26k stars 30.29k forks source link

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

Closed lebigot closed 1 month ago

lebigot commented 2 months ago

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

picnixz commented 2 months ago

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 commented 2 months ago

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 commented 1 month ago

Fixed in the attached merged PR

lebigot commented 1 month ago

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.