Improve the assert statement documentation to clarify impact of -O and optimization

[davidlbaird]

Documentation

In https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement,

The existing documentation states, "The current code generator emits no code for an assert statement when optimization is requested at compile time." This could include more details that setting the -O flag on the Python executable, or setting the PYTHONOPTIMIZE environment variable, will disable all asserts statements in code. Another improvement is a reminder, especially for library code authors, that if their code logic depends on assert statements as part of their critical code logic, that logic could break when optimization is enabled from the command line or in the environment. Another risk is evaluating function variables with assert in order to avoid typing errors on the return value, like declaring the return type as -> int, and adding an assert x is not None before a return x statement.

Linked PRs

• gh-115177: Clarify impact of -O and optimization in assert statement documentation #119305
• gh-115177: Mention PYTHONOPTIMIZE in assert docs and add warning #151114

[Qua27]

Isn't this already in the docs?

https://docs.python.org/3/using/cmdline.html#cmdoption-O
https://docs.python.org/3/using/cmdline.html#envvar-PYTHONOPTIMIZE

I do agree, however, that it should be emphasized that assert statements shouldn't be used for non-debugging purposes (e.g. checking data type).

[gpshead]

The current simple_stmts.html#the-assert-statement text mentions -O as a tiny hyperlink over to #cmdoption-O but doesn't mention the PYTHONOPTIMIZE environment variable. Part of this is asking for that text to mention the envionment variable as well as the flag.

The bigger picture part of this issue is probably just asking for an additional paragraph warning against using assert statements for logic critical to the correct functionality of the code. Something currently implied to readers who already understand when reading the current text, but not directly called out.

[amingilani]

Another risk is evaluating function variables with assert in order to avoid typing errors on the return value, like declaring the return type as -> int, and adding an assert x is not None before a return x statement.

it should be emphasized that assert statements shouldn't be used for non-debugging purposes (e.g. checking data type).

I'm confused by why using assert statements for type narrowing as described in the mypy documentation is a concern. I understand that asserts are not meant to be used for production code. However, PEP 484 explicitly calls out that "Python will remain a dynamically typed language, and the authors have no desire to ever make type hints mandatory, even by convention".

To that effect, the use of assert to narrow types, can be thought of just another optional type hint.