From 0e24f4df1fd527a2e232d17741963fc5eb2105fd Mon Sep 17 00:00:00 2001 From: Neeraj P Yetheendran Date: Tue, 21 May 2024 13:40:51 +0200 Subject: [PATCH 1/4] gh-115177: Mention PYTHONOPTIMIZE environment variable disables asserts in assert statement documentation * 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. This commit adds a hyperlink to it. --- Doc/reference/simple_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a253482156d3b4..f3c35bd37693c6 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -404,7 +404,7 @@ 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 :const:`__debug__` is ``True`` under normal circumstances, -``False`` when optimization is requested (command line option :option:`-O`). The current +``False`` when optimization is requested (command line option :option:`-O` or environment variable :envvar:`PYTHONOPTIMIZE`). The current code generator emits no code for an 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 From 68f092cd28e4c0f01cf042c3006279bc5262fec7 Mon Sep 17 00:00:00 2001 From: Neeraj P Yetheendran Date: Tue, 21 May 2024 14:23:11 +0200 Subject: [PATCH 2/4] gh:115177: Add Note to assert statement docs warning about possible issues with code containng assert statements when optimization is enabled Added a remainder that logic could break when optimization is enabled when using assert statements in code. Mentioned that it's considered best practice to not use assert statements to evaluate function variables. --- Doc/reference/simple_stmts.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index f3c35bd37693c6..891c9b0c7b6c3f 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -410,6 +410,11 @@ 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. + .. note:: + + It is considered good practice to not use :keyword:`assert` statements in critical code logic while writing library code as enabling optimization will cause the statements to be ignored. + Evaluating function variables using :keyword:`assert` statements can also lead to unexpected behavior. + Assignments to :const:`__debug__` are illegal. The value for the built-in variable is determined when the interpreter starts. From 39f4a3a30022898b41137eeb0975b48b21485690 Mon Sep 17 00:00:00 2001 From: Neeraj P Yetheendran <46917698+NXPY123@users.noreply.github.com> Date: Tue, 21 May 2024 19:03:06 +0200 Subject: [PATCH 3/4] gh-115177: Add line break to align text in assert statement doc Co-authored-by: Nice Zombies --- Doc/reference/simple_stmts.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 891c9b0c7b6c3f..414d0de4f944b8 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -404,7 +404,8 @@ 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 :const:`__debug__` is ``True`` under normal circumstances, -``False`` when optimization is requested (command line option :option:`-O` or environment variable :envvar:`PYTHONOPTIMIZE`). The current +``False`` when optimization is requested (command line option :option:`-O` +or environment variable :envvar:`PYTHONOPTIMIZE`). The current code generator emits no code for an 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 From 82922f94e1656f8acc994db2d7a698e5e88201f6 Mon Sep 17 00:00:00 2001 From: Neeraj P Yetheendran <46917698+NXPY123@users.noreply.github.com> Date: Wed, 22 May 2024 11:20:00 +0200 Subject: [PATCH 4/4] gh-115177: Add line break to align text in assert statement doc Co-authored-by: Nice Zombies --- Doc/reference/simple_stmts.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 414d0de4f944b8..b5dd34ec61f78a 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -413,8 +413,10 @@ as part of the stack trace. .. note:: - It is considered good practice to not use :keyword:`assert` statements in critical code logic while writing library code as enabling optimization will cause the statements to be ignored. - Evaluating function variables using :keyword:`assert` statements can also lead to unexpected behavior. + It is considered good practice to not use :keyword:`assert` statements in + critical code logic while writing library code as enabling optimization will + cause the statements to be ignored. Evaluating function variables using + :keyword:`assert` statements can also lead to unexpected behavior. Assignments to :const:`__debug__` are illegal. The value for the built-in variable is determined when the interpreter starts.