Document BaseException constructor

[xuhdev]

BPO	37225
Nosy	@brettcannon, @xuhdev

^{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:

assignee = None
closed_at = None
created_at = <Date 2019-06-11.07:11:42.495>
labels = ['3.7', '3.8', 'docs']
title = 'Document BaseException constructor'
updated_at = <Date 2019-06-12.17:56:35.874>
user = 'https://github.com/xuhdev'

bugs.python.org fields:

activity = <Date 2019-06-12.17:56:35.874>
actor = 'brett.cannon'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-06-11.07:11:42.495>
creator = 'Hong Xu'
dependencies = []
files = []
hgrepos = []
issue_num = 37225
keywords = []
message_count = 4.0
messages = ['345195', '345258', '345295', '345393']
nosy_count = 3.0
nosy_names = ['brett.cannon', 'docs@python', 'Hong Xu']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'resolved'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue37225'
versions = ['Python 3.7', 'Python 3.8']

[xuhdev]

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.

[brettcannon]

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".

[xuhdev]

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.

[brettcannon]

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.

[iritkatriel]

The doc for BaseException says also

   The base class for all built-in exceptions.  It is not meant to be directly
   inherited by user-defined classes (for that, use :exc:`Exception`).  If
   :func:`str` is called on an instance of this class, the representation of
   the argument(s) to the instance are returned, or the empty string when
   there were no arguments.

I don't think there is anything that can be added here that would make the situation clearer.