From 3a57764c73648651dc220ef52275f4285e0a0515 Mon Sep 17 00:00:00 2001 From: nahcmon Date: Mon, 8 Jun 2026 23:41:14 +0200 Subject: [PATCH] gh-115177: Mention PYTHONOPTIMIZE in assert statement docs and add warning Add a cross-reference to the PYTHONOPTIMIZE environment variable alongside the existing -O flag mention, and add a warning advising against using assert for production data validation or interface enforcement. --- Doc/reference/simple_stmts.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a964b43ebee174..6c0e81ac6ee39a 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -404,11 +404,18 @@ The extended form, ``assert expression1, expression2``, is equivalent to :: These equivalences assume that :const:`__debug__` and :exc:`AssertionError` refer to the built-in variables with those names. In the current implementation, the built-in variable ``__debug__`` is ``True`` under normal circumstances, -``False`` when optimization is requested (command line option :option:`-O`). The current -code generator emits no code for an :keyword:`assert` statement when optimization is -requested at compile time. Note that it is unnecessary to include the source -code for the expression that failed in the error message; it will be displayed -as part of the stack trace. +``False`` when optimization is requested (command line option :option:`-O` or the +:envvar:`PYTHONOPTIMIZE` environment variable). The current code generator emits +no code for an :keyword:`assert` statement when optimization is requested at +compile time. Note that it is unnecessary to include the source code for the +expression that failed in the error message; it will be displayed as part of the +stack trace. + +.. warning:: + + Since :keyword:`assert` statements are removed when optimization is enabled, + do not use them to enforce interface constraints or validate data in + production code — use :keyword:`if` statements and raise exceptions instead. Assignments to :const:`__debug__` are illegal. The value for the built-in variable is determined when the interpreter starts.