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

[Thomas Fischbacher]

Thomas Fischbacher <tfish at google.com> added the comment:

Addendum

Serhiy, I agree that my assessment was incorrect.
It actually is unittest/mock.py that has quite a few 'raise AssertionError' that are not coming from an 'assert' keyword statement.

At a deeper level, the problem here is as follows:

Every programming language has to make an awkward choice: either it excludes some authors ("must be forklift certified"), or it adds a lot of bureaucratic scaffolding to have some mechanisms that allow code authors to enforce API contracts (as if this would help to "keep out the tide" of unprincipled code authors), or it takes a more relaxed perspective - as also Perl did - of "we are all responsible users" / "do not do this because you are not invited, not because the owner has a shotgun". I'd call this third approach quite reasonable overall, but then the understanding is that "everybody treats documentation as binding and knows how to write good documentation".

After all, we need to be able to reason about code, and in order to do that, it matters to have guarantees such as for example: "Looking up a nonexistent key for a mapping by evaluating the_mapping[the_key] can raise an exception, and when it does, that exception is guaranteed to be an instance of KeyError".

Unfortunately, Python on the one hand emphasizes "responsible behavior" - i.e. "people know how to write and read documentation, and the written documentation creates a shared understanding between its author and reader", but on the other hand is often really bad at properly documenting its interfaces. If I had to name one thing that really needs fixing with Python, it would be this.

----------

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