From aa307bf8cf47c6accce88139460b1f83e0df3ab2 Mon Sep 17 00:00:00 2001 From: decorator-factory <42166884+decorator-factory@users.noreply.github.com> Date: Mon, 8 Dec 2025 10:55:00 +0000 Subject: [PATCH 1/3] Change documentation to reflect the new docstring adjustments in 3.13 --- Doc/library/functions.rst | 13 +++++++++++-- Doc/tutorial/controlflow.rst | 13 ++----------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 8314fed80fa512..493e4398ad3cbc 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -340,8 +340,12 @@ are always available. They are listed here in alphabetical order. It is needed to unambiguous :ref:`filter ` syntax warnings by module name. - This function raises :exc:`SyntaxError` if the compiled source is invalid, - and :exc:`ValueError` if the source contains null bytes. + This function raises the following exceptions: + + - :exc:`SyntaxError` if the compiled source is invalid + - :exc:`ValueError` if the source contains null bytes + - :exc:`UnicodeDecodeError` if the source code contains docstrings that + cannot be encoded as UTF-8 and the optimization level is below ``2`` If you want to parse Python code into its AST representation, see :func:`ast.parse`. @@ -373,6 +377,11 @@ are always available. They are listed here in alphabetical order. Previously, :exc:`TypeError` was raised when null bytes were encountered in *source*. + .. versionchanged:: 3.13 + :exc:`UnicodeDecodeError` is now raised if any docstring in *source* + contains surrogates (like ``\ud800``) and therefore cannot be encoded + as UTF-8. + .. versionadded:: 3.8 ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable support for top-level ``await``, ``async for``, and ``async with``. diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 5ec8789f98c701..b44181b7072fd4 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -1039,17 +1039,8 @@ blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object's calling conventions, its side effects, etc. -The Python parser does not strip indentation from multi-line string literals in -Python, so tools that process documentation have to strip indentation if -desired. This is done using the following convention. The first non-blank line -*after* the first line of the string determines the amount of indentation for -the entire documentation string. (We can't use the first line since it is -generally adjacent to the string's opening quotes so its indentation is not -apparent in the string literal.) Whitespace "equivalent" to this indentation is -then stripped from the start of all lines of the string. Lines that are -indented less should not occur, but if they occur all their leading whitespace -should be stripped. Equivalence of whitespace should be tested after expansion -of tabs (to 8 spaces, normally). +The Python parser strips indentation from multi-line string literals when they +serve as module, class, or function docstrings. Here is an example of a multi-line docstring:: From 3b2c009312749cc916826a4132fd10741f0fc9b6 Mon Sep 17 00:00:00 2001 From: decorator-factory <42166884+decorator-factory@users.noreply.github.com> Date: Mon, 8 Dec 2025 11:04:44 +0000 Subject: [PATCH 2/3] Clarify in the example what "strip indentation" means --- Doc/tutorial/controlflow.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index b44181b7072fd4..f3e69756401b8b 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -1047,14 +1047,20 @@ Here is an example of a multi-line docstring:: >>> def my_function(): ... """Do nothing, but document it. ... - ... No, really, it doesn't do anything. + ... No, really, it doesn't do anything: + ... + ... >>> my_function() + ... >>> ... """ ... pass ... >>> print(my_function.__doc__) Do nothing, but document it. - No, really, it doesn't do anything. + No, really, it doesn't do anything: + + >>> my_function() + >>> .. _tut-annotations: From eeb1cebac1cbb356971d76d467ad8ce02475ef4a Mon Sep 17 00:00:00 2001 From: decorator-factory <42166884+decorator-factory@users.noreply.github.com> Date: Wed, 10 Dec 2025 14:14:42 +0000 Subject: [PATCH 3/3] Make `compile()` exception description more vague --- Doc/library/functions.rst | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 493e4398ad3cbc..6dd94acefbc17e 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -340,12 +340,8 @@ are always available. They are listed here in alphabetical order. It is needed to unambiguous :ref:`filter ` syntax warnings by module name. - This function raises the following exceptions: - - - :exc:`SyntaxError` if the compiled source is invalid - - :exc:`ValueError` if the source contains null bytes - - :exc:`UnicodeDecodeError` if the source code contains docstrings that - cannot be encoded as UTF-8 and the optimization level is below ``2`` + This function raises :exc:`SyntaxError` or :exc:`ValueError` if the compiled + source is invalid. If you want to parse Python code into its AST representation, see :func:`ast.parse`. @@ -377,11 +373,6 @@ are always available. They are listed here in alphabetical order. Previously, :exc:`TypeError` was raised when null bytes were encountered in *source*. - .. versionchanged:: 3.13 - :exc:`UnicodeDecodeError` is now raised if any docstring in *source* - contains surrogates (like ``\ud800``) and therefore cannot be encoded - as UTF-8. - .. versionadded:: 3.8 ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable support for top-level ``await``, ``async for``, and ``async with``.