python / cpython

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

Document warnings.WarningMessage ? #84094

Open 1f7c169c-a6ad-45ae-b614-0d40d962c776 opened 4 years ago

1f7c169c-a6ad-45ae-b614-0d40d962c776 commented 4 years ago
BPO 39913
Nosy @vstinner, @blueyed, @remilapeyre

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['docs'] title = 'Document warnings.WarningMessage ?' updated_at = user = 'https://github.com/blueyed' ``` bugs.python.org fields: ```python activity = actor = 'remi.lapeyre' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'blueyed' dependencies = [] files = [] hgrepos = [] issue_num = 39913 keywords = [] message_count = 2.0 messages = ['363735', '363739'] nosy_count = 4.0 nosy_names = ['vstinner', 'blueyed', 'docs@python', 'remi.lapeyre'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = None url = 'https://bugs.python.org/issue39913' versions = [] ```

1f7c169c-a6ad-45ae-b614-0d40d962c776 commented 4 years ago

I've noticed that warnings.WarningMessage is not documented, i.e. it does not show up in the intersphinx object list.

I'm not sure how to document it best, but maybe just describing its attributes?

Ref: https://github.com/blueyed/cpython/blob/598d29c51c7b5a77f71eed0f615eb0b3865a4085/Lib/warnings.py#L398-L417

23982c60-ed6c-47d1-96c2-69d417bd81b3 commented 4 years ago

warnings.WarningMessage was added in https://bugs.python.org/issue26568 at the same time than _showwarnmsg_impl() and _formatwarnmsg_impl().

The goal was to have public functions that took them instead of multiple arguments so it could be easily extended in the future. It looks like it never happened and as of today there is no way to use warnings.WarningMessage in user code.

Maybe it is time to bikeshed the names and add them?