Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
lebigot opened this issue Aug 22, 2024 · 4 comments
Closed
Labels
docs Documentation in the Doc dir easy

Comments

@lebigot
Copy link
Contributor

lebigot commented Aug 22, 2024

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

@lebigot lebigot added the docs Documentation in the Doc dir label Aug 22, 2024
@lebigot lebigot changed the title warnings.catch_warnings: undocumented argument warnings.catch_warnings: undocumented arguments (category, lineno, append) Aug 22, 2024
@picnixz
Copy link
Contributor

picnixz commented Aug 22, 2024

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.

@picnixz picnixz added the easy label Aug 22, 2024
@lebigot
Copy link
Contributor Author

lebigot commented Aug 22, 2024

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
Copy link
Contributor

Fixed in the attached merged PR

miss-islington pushed a commit to miss-islington/cpython that referenced this issue Sep 25, 2024
…ngs: (pythonGH-123231)

* Adding hyperlink of argument

* Modify as reviewer suggested
(cherry picked from commit 828583a)

Co-authored-by: Damien <81557462+Damien-Chen@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Sep 25, 2024
…ngs: (pythonGH-123231)

* Adding hyperlink of argument

* Modify as reviewer suggested
(cherry picked from commit 828583a)

Co-authored-by: Damien <81557462+Damien-Chen@users.noreply.github.com>
@lebigot
Copy link
Contributor Author

lebigot commented Sep 25, 2024

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.

Yhg1s pushed a commit that referenced this issue Sep 26, 2024
…ings: (GH-123231) (#124528)

gh-123223: Adding hyperlink of argument in warnings.catch_warnings: (GH-123231)

* Adding hyperlink of argument

* Modify as reviewer suggested
(cherry picked from commit 828583a)

Co-authored-by: Damien <81557462+Damien-Chen@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir easy
Projects
None yet
Development

No branches or pull requests

3 participants