This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Fix documentation for truth testing
Type: Stage:
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, steven.daprano, terry.reedy
Priority: normal Keywords:

Created on 2021-08-24 03:33 by steven.daprano, last changed 2022-04-11 14:59 by admin.

Messages (2)
msg400196 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-08-24 03:33
Truth testing states that "Any object can be tested for truth value" but from 3.9 onwards, doing so with NotImplemented is deprecated and will be made a TypeError.

https://docs.python.org/3/library/stdtypes.html#truth-value-testing

It is also not true for third-party objects such as numpy arrays (which raise ValueError) and pandas dataframes.

I think that truth testing should have been considered a fundamental operation that (in the absence of bugs) always succeeds, but #35712 says different. Not that I'm bitter *wink*

In any case, at the very least the exception for NotImplemented should be documented.
msg400443 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-08-27 21:22
I think that this proposal is either premature or not needed.  (But did you have anything specific in mind.)  As you indicated, there are two separate subissues here.

1. NotImplemented: Issue 35712 added "It should not be evaluated in a boolean context" to its entry in Library/constant.rst, followed by the notice of deprecation and intended removal. I don't think we should document the possible future change a second time elsewhere.

I agree that if and when NotImplemented becomes an exception and 'bool(NotImplemented)' fails, then the exception should be added sentence you quoted.  But I think it possible that the warning will be left indefinitely (and think it should be) and would instead propose that the claim of future removal be removed.

2. 2nd and 3rd party invalidation:  I believe that several claims can be invalidated if one used special methods in ways not intended.  The all have the unwritten caveat 'as long as special methods are not abused'.  We have so far intentionally not added special mention of all such possible breakages.
History
Date User Action Args
2022-04-11 14:59:49adminsetgithub: 89152
2021-08-27 21:22:02terry.reedysetnosy: + terry.reedy
messages: + msg400443
2021-08-24 03:33:20steven.dapranocreate