From 34f3010cd7e990a38c0eb971ad64bc3ab2e397b5 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Thu, 1 Jun 2023 14:24:28 +0100 Subject: [PATCH 1/7] gh-84436: update docs on Py_None/Py_True/Py_False/Py_Ellipsis becoming immortal --- Doc/c-api/bool.rst | 21 +++++++++++---------- Doc/c-api/none.rst | 7 +++---- Doc/c-api/slice.rst | 8 +++++--- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index c197d447e9618c..097ac66f3097b3 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -19,29 +19,30 @@ are available, however. .. c:var:: PyObject* Py_False - The Python ``False`` object. This object has no methods. It needs to be - treated just like any other object with respect to reference counts. + The Python ``False`` object. This object has no methods and is immortal. + +.. versionchanged:: 3.12 + :const:`Py_False` is immortal. .. c:var:: PyObject* Py_True - The Python ``True`` object. This object has no methods. It needs to be treated - just like any other object with respect to reference counts. + The Python ``True`` object. This object has no methods and is immortal. + +.. versionchanged:: 3.12 + :const:`Py_True` is immortal. .. c:macro:: Py_RETURN_FALSE - Return :const:`Py_False` from a function, properly incrementing its reference - count. + Return :const:`Py_False` from a function. .. c:macro:: Py_RETURN_TRUE - Return :const:`Py_True` from a function, properly incrementing its reference - count. + Return :const:`Py_True` from a function. .. c:function:: PyObject* PyBool_FromLong(long v) - Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the - truth value of *v*. + Return :const:`Py_True` or :const:`Py_False`, depending on the truth value of *v*. diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index b84a16a28ead56..5f5bff84334384 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -16,11 +16,10 @@ same reason. .. c:var:: PyObject* Py_None The Python ``None`` object, denoting lack of value. This object has no methods. - It needs to be treated just like any other object with respect to reference - counts. +.. versionchanged:: 3.12 + :const:`Py_None` is immortal. .. c:macro:: Py_RETURN_NONE - Properly handle returning :c:data:`Py_None` from within a C function (that is, - increment the reference count of ``None`` and return it.) + Return :c:data:`Py_None` from a function. diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 8271d9acfb645e..176192ef98168c 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -118,6 +118,8 @@ Ellipsis Object .. c:var:: PyObject *Py_Ellipsis - The Python ``Ellipsis`` object. This object has no methods. It needs to be - treated just like any other object with respect to reference counts. Like - :c:data:`Py_None` it is a singleton object. + The Python ``Ellipsis`` object. This object has no methods. Like + :c:data:`Py_None` it is an immortal singleton object. + + .. versionchanged:: 3.12 + :const:`Py_Ellipsis` is immortal. From b0997c047cac3764d7992a6845b6291e16826e01 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Thu, 1 Jun 2023 15:01:57 +0100 Subject: [PATCH 2/7] use :c:data: instead of :const: --- Doc/c-api/slice.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 176192ef98168c..5fa2b6198f4b91 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -122,4 +122,4 @@ Ellipsis Object :c:data:`Py_None` it is an immortal singleton object. .. versionchanged:: 3.12 - :const:`Py_Ellipsis` is immortal. + :c:data:`Py_Ellipsis` is immortal. From 52a846b81332ef32a25f54e274004faf7a55ec32 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Mon, 5 Jun 2023 15:20:26 +0100 Subject: [PATCH 3/7] add link to the PEP --- Doc/c-api/bool.rst | 6 ++++-- Doc/c-api/none.rst | 3 ++- Doc/c-api/slice.rst | 3 ++- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index 097ac66f3097b3..ce8a168c62fa73 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -19,7 +19,8 @@ are available, however. .. c:var:: PyObject* Py_False - The Python ``False`` object. This object has no methods and is immortal. + The Python ``False`` object. This object has no methods and is + `immortal.`_ .. versionchanged:: 3.12 :const:`Py_False` is immortal. @@ -27,7 +28,8 @@ are available, however. .. c:var:: PyObject* Py_True - The Python ``True`` object. This object has no methods and is immortal. + The Python ``True`` object. This object has no methods and is + `immortal.`_ .. versionchanged:: 3.12 :const:`Py_True` is immortal. diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index 5f5bff84334384..d69b68f25dbfaf 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -15,7 +15,8 @@ same reason. .. c:var:: PyObject* Py_None - The Python ``None`` object, denoting lack of value. This object has no methods. + The Python ``None`` object, denoting lack of value. This object has no methods + and is `immortal.`_. .. versionchanged:: 3.12 :const:`Py_None` is immortal. diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 5fa2b6198f4b91..4ae8fced1d5d0f 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -119,7 +119,8 @@ Ellipsis Object .. c:var:: PyObject *Py_Ellipsis The Python ``Ellipsis`` object. This object has no methods. Like - :c:data:`Py_None` it is an immortal singleton object. + :c:data:`Py_None` it is an `immortal`_ + singleton object. .. versionchanged:: 3.12 :c:data:`Py_Ellipsis` is immortal. From 103aabb6e1a0141360ad37068ede7c2fcb704501 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Mon, 5 Jun 2023 15:22:30 +0100 Subject: [PATCH 4/7] use :c:data: --- Doc/c-api/bool.rst | 4 ++-- Doc/c-api/none.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index ce8a168c62fa73..ae765cdc7e1981 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -23,7 +23,7 @@ are available, however. `immortal.`_ .. versionchanged:: 3.12 - :const:`Py_False` is immortal. + :c:data:`Py_False` is immortal. .. c:var:: PyObject* Py_True @@ -32,7 +32,7 @@ are available, however. `immortal.`_ .. versionchanged:: 3.12 - :const:`Py_True` is immortal. + :c:data:`Py_True` is immortal. .. c:macro:: Py_RETURN_FALSE diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index d69b68f25dbfaf..958fd8f8fd04bc 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -19,7 +19,7 @@ same reason. and is `immortal.`_. .. versionchanged:: 3.12 - :const:`Py_None` is immortal. + :c:data:`Py_None` is immortal. .. c:macro:: Py_RETURN_NONE From 864ed5d40e37c9a15a3e85e982b6dd2fbbcf68cd Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Mon, 5 Jun 2023 18:44:10 +0100 Subject: [PATCH 5/7] Maybe fix the links. --- Doc/c-api/bool.rst | 4 ++-- Doc/c-api/none.rst | 2 +- Doc/c-api/slice.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index ae765cdc7e1981..9bea48cf567566 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -20,7 +20,7 @@ are available, however. .. c:var:: PyObject* Py_False The Python ``False`` object. This object has no methods and is - `immortal.`_ + `immortal `_. .. versionchanged:: 3.12 :c:data:`Py_False` is immortal. @@ -29,7 +29,7 @@ are available, however. .. c:var:: PyObject* Py_True The Python ``True`` object. This object has no methods and is - `immortal.`_ + `immortal `_. .. versionchanged:: 3.12 :c:data:`Py_True` is immortal. diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst index 958fd8f8fd04bc..1a497652ac5655 100644 --- a/Doc/c-api/none.rst +++ b/Doc/c-api/none.rst @@ -16,7 +16,7 @@ same reason. .. c:var:: PyObject* Py_None The Python ``None`` object, denoting lack of value. This object has no methods - and is `immortal.`_. + and is `immortal `_. .. versionchanged:: 3.12 :c:data:`Py_None` is immortal. diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 4ae8fced1d5d0f..2263c6ae710aa4 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -119,7 +119,7 @@ Ellipsis Object .. c:var:: PyObject *Py_Ellipsis The Python ``Ellipsis`` object. This object has no methods. Like - :c:data:`Py_None` it is an `immortal`_ + :c:data:`Py_None` it is an `immortal `_. singleton object. .. versionchanged:: 3.12 From 7330a7f225c1d216e33ac7df28df3ac3f3b3c5e9 Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Wed, 21 Jun 2023 19:12:17 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Carl Meyer --- Doc/c-api/bool.rst | 6 +++--- Doc/c-api/slice.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index 9bea48cf567566..398852a2427c68 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -37,14 +37,14 @@ are available, however. .. c:macro:: Py_RETURN_FALSE - Return :const:`Py_False` from a function. + Return :c:data:`Py_False` from a function. .. c:macro:: Py_RETURN_TRUE - Return :const:`Py_True` from a function. + Return :c:data:`Py_True` from a function. .. c:function:: PyObject* PyBool_FromLong(long v) - Return :const:`Py_True` or :const:`Py_False`, depending on the truth value of *v*. + Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value of *v*. diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index c3568dee8620fa..c54a659cf2ffd8 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -119,7 +119,7 @@ Ellipsis Object .. c:var:: PyObject *Py_Ellipsis The Python ``Ellipsis`` object. This object has no methods. Like - :c:data:`Py_None` it is an `immortal `_. + :c:data:`Py_None`, it is an `immortal `_. singleton object. .. versionchanged:: 3.12 From 4281b5be6a81ec5ad4dfc919daefe7bfea4b8f32 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Wed, 21 Jun 2023 19:13:40 +0100 Subject: [PATCH 7/7] fix :const:->:c:data: --- Doc/c-api/bool.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst index 398852a2427c68..b2d8f2124fc203 100644 --- a/Doc/c-api/bool.rst +++ b/Doc/c-api/bool.rst @@ -6,7 +6,7 @@ Boolean Objects --------------- Booleans in Python are implemented as a subclass of integers. There are only -two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal +two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the normal creation and deletion functions don't apply to booleans. The following macros are available, however.