From 5342ffcfd7f4eda2322b1c19f854bdacd31e7391 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Wed, 31 Jan 2024 16:39:03 -0600 Subject: [PATCH 1/7] clean up Doc/c-api/exceptions.rst --- Doc/c-api/exceptions.rst | 12 ++++++------ Doc/c-api/sys.rst | 4 ++-- Doc/tools/.nitignore | 1 - 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index c7e3cd9463e5d7..26fed4d3242c3e 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -396,7 +396,7 @@ an error value). .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) Function similar to :c:func:`PyErr_WarnFormat`, but *category* is - :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`. + :exc:`ResourceWarning` and it passes *source* to :class:`!warnings.WarningMessage`. .. versionadded:: 3.6 @@ -732,7 +732,7 @@ Exception Classes This creates a class object derived from :exc:`Exception` (accessible in C as :c:data:`PyExc_Exception`). - The :attr:`__module__` attribute of the new class is set to the first part (up + The :attr:`!__module__` attribute of the new class is set to the first part (up to the last dot) of the *name* argument, and the class name is set to the last part (after the last dot). The *base* argument can be used to specify alternate base classes; it can either be only one class or a tuple of classes. The *dict* @@ -904,7 +904,7 @@ because the :ref:`call protocol ` takes care of recursion handling. Marks a point where a recursive C-level call is about to be performed. - If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS + If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it sets a :exc:`MemoryError` and returns a nonzero value. @@ -1158,11 +1158,11 @@ These are compatibility aliases to :c:data:`PyExc_OSError`: +-------------------------------------+----------+ | C Name | Notes | +=====================================+==========+ -| :c:data:`PyExc_EnvironmentError` | | +| :c:data:`!PyExc_EnvironmentError` | | +-------------------------------------+----------+ -| :c:data:`PyExc_IOError` | | +| :c:data:`!PyExc_IOError` | | +-------------------------------------+----------+ -| :c:data:`PyExc_WindowsError` | [2]_ | +| :c:data:`!PyExc_WindowsError` | [2]_ | +-------------------------------------+----------+ .. versionchanged:: 3.3 diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index e3c54b075114ff..6bbe0c815de5f8 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -98,9 +98,9 @@ Operating System Utilities .. c:function:: int PyOS_CheckStack() Return true when the interpreter runs out of stack space. This is a reliable - check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently + check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). - :c:macro:`USE_STACKCHECK` will be defined automatically; you should never + :c:macro:`!USE_STACKCHECK` will be defined automatically; you should never change the definition in your own code. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 7eacb46d6299b3..852542f3f961eb 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -3,7 +3,6 @@ # Keep lines sorted lexicographically to help avoid merge conflicts. Doc/c-api/descriptor.rst -Doc/c-api/exceptions.rst Doc/c-api/float.rst Doc/c-api/gcsupport.rst Doc/c-api/init.rst From d9a397a6cfbba1437fe4ae9e580aa8102f6f2783 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sun, 4 Feb 2024 10:40:43 -0600 Subject: [PATCH 2/7] suppress dangling Py_DEBUG refs ( reference already in the paragraph) --- Doc/c-api/intro.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 4dbca92b18b5cd..5d13f74de7bd6c 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -812,12 +812,12 @@ available that support tracing of reference counts, debugging the memory allocator, or low-level profiling of the main interpreter loop. Only the most frequently used builds will be described in the remainder of this section. -Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces +Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined produces what is generally meant by :ref:`a debug build of Python `. -:c:macro:`Py_DEBUG` is enabled in the Unix build by adding +:c:macro:`!Py_DEBUG` is enabled in the Unix build by adding :option:`--with-pydebug` to the :file:`./configure` command. It is also implied by the presence of the -not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled +not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`!Py_DEBUG` is enabled in the Unix build, compiler optimization is disabled. In addition to the reference count debugging described below, extra checks are @@ -832,4 +832,3 @@ after every statement run by the interpreter.) Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution for more detailed information. - From 4b475f270f57c1e22e1b087a1ccbeb4408e20836 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sun, 4 Feb 2024 10:41:43 -0600 Subject: [PATCH 3/7] suppress dangling Py_DEBUG ref ( reference already in the paragraph) --- Doc/library/test.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index cad1023021a512..26b7368aeac0a7 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -324,7 +324,7 @@ The :mod:`test.support` module defines the following constants: .. data:: Py_DEBUG - True if Python is built with the :c:macro:`Py_DEBUG` macro defined: if + True if Python is built with the :c:macro:`!Py_DEBUG` macro defined: if Python is :ref:`built in debug mode ` (:option:`./configure --with-pydebug <--with-pydebug>`). From 0501578704181a80ba4f96fc481035bb3387e0ab Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Sun, 4 Feb 2024 19:21:08 +0000 Subject: [PATCH 4/7] Revert "clean up Doc/c-api/exceptions.rst" This reverts commit 5342ffcfd7f4eda2322b1c19f854bdacd31e7391. --- Doc/c-api/exceptions.rst | 12 ++++++------ Doc/c-api/sys.rst | 4 ++-- Doc/tools/.nitignore | 1 + 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 26fed4d3242c3e..c7e3cd9463e5d7 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -396,7 +396,7 @@ an error value). .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) Function similar to :c:func:`PyErr_WarnFormat`, but *category* is - :exc:`ResourceWarning` and it passes *source* to :class:`!warnings.WarningMessage`. + :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`. .. versionadded:: 3.6 @@ -732,7 +732,7 @@ Exception Classes This creates a class object derived from :exc:`Exception` (accessible in C as :c:data:`PyExc_Exception`). - The :attr:`!__module__` attribute of the new class is set to the first part (up + The :attr:`__module__` attribute of the new class is set to the first part (up to the last dot) of the *name* argument, and the class name is set to the last part (after the last dot). The *base* argument can be used to specify alternate base classes; it can either be only one class or a tuple of classes. The *dict* @@ -904,7 +904,7 @@ because the :ref:`call protocol ` takes care of recursion handling. Marks a point where a recursive C-level call is about to be performed. - If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS + If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it sets a :exc:`MemoryError` and returns a nonzero value. @@ -1158,11 +1158,11 @@ These are compatibility aliases to :c:data:`PyExc_OSError`: +-------------------------------------+----------+ | C Name | Notes | +=====================================+==========+ -| :c:data:`!PyExc_EnvironmentError` | | +| :c:data:`PyExc_EnvironmentError` | | +-------------------------------------+----------+ -| :c:data:`!PyExc_IOError` | | +| :c:data:`PyExc_IOError` | | +-------------------------------------+----------+ -| :c:data:`!PyExc_WindowsError` | [2]_ | +| :c:data:`PyExc_WindowsError` | [2]_ | +-------------------------------------+----------+ .. versionchanged:: 3.3 diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 6bbe0c815de5f8..e3c54b075114ff 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -98,9 +98,9 @@ Operating System Utilities .. c:function:: int PyOS_CheckStack() Return true when the interpreter runs out of stack space. This is a reliable - check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently + check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). - :c:macro:`!USE_STACKCHECK` will be defined automatically; you should never + :c:macro:`USE_STACKCHECK` will be defined automatically; you should never change the definition in your own code. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 852542f3f961eb..7eacb46d6299b3 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -3,6 +3,7 @@ # Keep lines sorted lexicographically to help avoid merge conflicts. Doc/c-api/descriptor.rst +Doc/c-api/exceptions.rst Doc/c-api/float.rst Doc/c-api/gcsupport.rst Doc/c-api/init.rst From 93331070fb6c0217ab5e9c3ba8287bc232acdbb4 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sun, 4 Feb 2024 13:33:41 -0600 Subject: [PATCH 5/7] I think this is what the GitHub action was complaining about. --- Doc/c-api/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 5d13f74de7bd6c..e9058321c51638 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -817,7 +817,7 @@ what is generally meant by :ref:`a debug build of Python `. :c:macro:`!Py_DEBUG` is enabled in the Unix build by adding :option:`--with-pydebug` to the :file:`./configure` command. It is also implied by the presence of the -not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`!Py_DEBUG` is enabled +not-Python-specific :c:macro:`!_DEBUG` macro. When :c:macro:`!Py_DEBUG` is enabled in the Unix build, compiler optimization is disabled. In addition to the reference count debugging described below, extra checks are From bfba2a79119addfe4872df6e700adb3a83e46bd7 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Tue, 6 Feb 2024 11:16:41 -0600 Subject: [PATCH 6/7] Explicitly call out Py_DEBUG macro. This produces both a target for other references and an index entry. --- Doc/c-api/intro.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index e9058321c51638..dcda1071a58f35 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -148,7 +148,7 @@ complete listing. worse performances (due to increased code size for example). The compiler is usually smarter than the developer for the cost/benefit analysis. - If Python is :ref:`built in debug mode ` (if the ``Py_DEBUG`` + If Python is :ref:`built in debug mode ` (if the :c:macro:`Py_DEBUG` macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing. It must be specified before the function return type. Usage:: @@ -812,6 +812,8 @@ available that support tracing of reference counts, debugging the memory allocator, or low-level profiling of the main interpreter loop. Only the most frequently used builds will be described in the remainder of this section. +.. c:macro:: Py_DEBUG + Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined produces what is generally meant by :ref:`a debug build of Python `. :c:macro:`!Py_DEBUG` is enabled in the Unix build by adding From f7ea5d81eef0d82f5c6b5fd481120438e4de3520 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Tue, 6 Feb 2024 11:17:25 -0600 Subject: [PATCH 7/7] reference the new Py_DEBUG target and reduce configure script arg duplication --- Doc/library/test.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 26b7368aeac0a7..7d28f625345726 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -324,9 +324,9 @@ The :mod:`test.support` module defines the following constants: .. data:: Py_DEBUG - True if Python is built with the :c:macro:`!Py_DEBUG` macro defined: if - Python is :ref:`built in debug mode ` - (:option:`./configure --with-pydebug <--with-pydebug>`). + True if Python was built with the :c:macro:`Py_DEBUG` macro + defined, that is, if + Python was :ref:`built in debug mode `. .. versionadded:: 3.12