[New-bugs-announce] [issue46972] Documentation: Reference says AssertionError is raised by `assert`, but not all AssertionErrors are.

[Thomas Fischbacher]

New submission from Thomas Fischbacher <tfish at google.com>:

The Python reference says:

(1) https://docs.python.org/3/library/exceptions.html#concrete-exceptions

exception AssertionError
Raised when an assert statement fails.

(2) https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement

"assert ..." is equivalent to "if __debug__: ..."

>From this, one can infer the guarantee "the -O flag will suppress AssertionError exceptions from being raised".

However, there is code in the Python standard library that does a direct "raise AssertionError" (strictly speaking, in violation of (1)), and it is just reasonable to assume that other code following the design of that would then also want to do a direct "raise AssertionError".

This happens e.g. in many methods defined in: unittest/mock.py

The most appropriate fix here may be to change the documentation to not say:

===
exception AssertionError
Raised when an assert statement fails.
===

but instead:

===
exception AssertionError
An assert[{add reference to `assert` definition}] statement fails, or a unit testing related assert{...}() callable detects an assertion violation.
===

----------
messages: 414837
nosy: tfish2
priority: normal
severity: normal
status: open
title: Documentation: Reference says AssertionError is raised by `assert`, but not all AssertionErrors are.

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue46972>
_______________________________________