classification
Title: Document BaseException constructor
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Hong Xu, brett.cannon, docs@python
Priority: normal Keywords:

Created on 2019-06-11 07:11 by Hong Xu, last changed 2019-06-12 17:56 by brett.cannon.

Messages (4)
msg345195 - (view) Author: Hong Xu (Hong Xu) * Date: 2019-06-11 07:11
The "Builtin Exceptions" page does not document the constructors of the listed exception classes. All it says is

> The tuple of arguments given to the exception constructor. Some built-in exceptions (like OSError) expect a certain number of arguments and assign a special meaning to the elements of this tuple, while others are usually called only with a single string giving an error message.

This is quite vague and does not really guide users for individual exception classes.
msg345258 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-06-11 18:09
OSError does have its constructor documented at https://docs.python.org/3/library/exceptions.html#OSError (farther down the page I think you're reading; you didn't provide the URL you're referring to so I'm somewhat guessing). It is specifically vague because it varies from exception to exception and you need to check the exception you're using to see if it differs from BaseException.

Thanks for letting us know about your concerns, but I'm closing as "not a bug".
msg345295 - (view) Author: Hong Xu (Hong Xu) * Date: 2019-06-12 01:12
Thanks for your answer, but I believe this is a real document bug. OSError does have its signature documented, but the majority of other exception classes do not do so, neither does BaseException explains a default behavior clearly (see my quote above).

As an example, ValueError accepts multiple arguments and makes use of all of them when given, but from the document, I can barely guess this out.
msg345393 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-06-12 17:56
Fair enough. I've changed the title to point out only BaseException needs its constructor documented as every other extension inherits from it and so its cascades down.
History
Date User Action Args
2019-06-12 17:56:35brett.cannonsetstatus: closed -> open
versions: + Python 3.8
title: Signatures of Exceptions not documented -> Document BaseException constructor
messages: + msg345393

resolution: not a bug ->
2019-06-12 01:12:14Hong Xusetmessages: + msg345295
2019-06-11 18:09:20brett.cannonsetstatus: open -> closed

nosy: + brett.cannon
messages: + msg345258

resolution: not a bug
stage: resolved
2019-06-11 07:11:42Hong Xucreate