From f7083f2a7a9c146405e8a5ce03e17df4fd952a08 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 19:33:42 +0000 Subject: [PATCH 01/15] [docs] Improve C API GetItem & HasAttr notes. This should format the notes and call out the preferred APIs to use in a more visible manner. --- Doc/c-api/dict.rst | 19 ++++++++++++------- Doc/c-api/object.rst | 18 +++++++++++------- 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 0ca8ad624b2034..28c212a2f8df97 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -98,9 +98,11 @@ Dictionary Objects Return the object from dictionary *p* which has a key *key*. Return ``NULL`` if the key *key* is not present, but *without* setting an exception. - Note that exceptions which occur while calling :meth:`__hash__` and - :meth:`__eq__` methods will get suppressed. - To get error reporting use :c:func:`PyDict_GetItemWithError()` instead. + .. note:: + + Exceptions that occur while this calls :meth:`__hash__` and + :meth:`__eq__` methods are silently ignored. + Prefer the :c:func:`PyDict_GetItemWithError` function instead. .. versionchanged:: 3.10 Calling this API without :term:`GIL` held had been allowed for historical @@ -120,10 +122,13 @@ Dictionary Objects This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:expr:`const char*`, rather than a :c:expr:`PyObject*`. - Note that exceptions which occur while calling :meth:`__hash__` and - :meth:`__eq__` methods and creating a temporary string object - will get suppressed. - To get error reporting use :c:func:`PyDict_GetItemWithError()` instead. + .. note:: + + Exceptions that occur while this calls :meth:`__hash__` and + :meth:`__eq__` methods or while creating the temporary ``str`` + object are silently ignored. + Prefer using the :c:func:`PyDict_GetItemWithError` function with your own + :c:func:`PyUnicode_FromString` *key* instead. .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index a25ff244c9f07c..4bc01eed6c5e8c 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -33,9 +33,11 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - Note that exceptions which occur while calling :meth:`__getattr__` and - :meth:`__getattribute__` methods will get suppressed. - To get error reporting use :c:func:`PyObject_GetAttr()` instead. + .. note:: + + Exceptions that occur when this calls :meth:`__getattr__` and + :meth:`__getattribute__` methods are silently ignored. + For proper error handling, use :c:func:`PyObject_GetAttr` instead. .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name) @@ -44,10 +46,12 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - Note that exceptions which occur while calling :meth:`__getattr__` and - :meth:`__getattribute__` methods and creating a temporary string object - will get suppressed. - To get error reporting use :c:func:`PyObject_GetAttrString()` instead. + .. note:: + + Exceptions that occur when this calls :meth:`__getattr__` and + :meth:`__getattribute__` methods or while creating the temporary ``str`` + object are silently ignored. + For proper error handling, use :c:func:`PyObject_GetAttrString` instead. .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name) From 1e2d9610ad29b7db3b754a4b874615e36d2b1411 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:08:34 -0700 Subject: [PATCH 02/15] ~object. Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 4bc01eed6c5e8c..194fbe5f3f20ba 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -48,7 +48,7 @@ Object Protocol .. note:: - Exceptions that occur when this calls :meth:`__getattr__` and + Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:`__getattribute__` methods or while creating the temporary ``str`` object are silently ignored. For proper error handling, use :c:func:`PyObject_GetAttrString` instead. From e4c34f2a9ec9b12c016a0ff42ca17866059f8aaa Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:08:49 -0700 Subject: [PATCH 03/15] more ~object. Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 194fbe5f3f20ba..dd90d69fe6b770 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -49,7 +49,7 @@ Object Protocol .. note:: Exceptions that occur when this calls :meth:`~object.__getattr__` and - :meth:`__getattribute__` methods or while creating the temporary ``str`` + :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str` object are silently ignored. For proper error handling, use :c:func:`PyObject_GetAttrString` instead. From 8c15463d313f5011326f087fda0679a048a9c63f Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:12:00 -0700 Subject: [PATCH 04/15] caution rather than note ironically stands out less than note, but the bold caution: is still sufficient and better than what we had. warning would stand out too much. Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index dd90d69fe6b770..6ea9805697dbe9 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -33,7 +33,7 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - .. note:: + .. caution:: Exceptions that occur when this calls :meth:`__getattr__` and :meth:`__getattribute__` methods are silently ignored. From 1840e2b4136808cc1a1ba1ef88237246f8bcc845 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:12:23 -0700 Subject: [PATCH 05/15] caution rather than note ironically stands out less than note, but the bold caution: is still sufficient and better than what we had. warning would stand out too much. Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 6ea9805697dbe9..888b49a542d2a9 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -46,7 +46,7 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - .. note:: + .. caution:: Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str` From 97ead385f0484cb405dec5eaf5428c980d458e68 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:12:42 -0700 Subject: [PATCH 06/15] ~object Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 888b49a542d2a9..78d3ba32074c0e 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -36,7 +36,7 @@ Object Protocol .. caution:: Exceptions that occur when this calls :meth:`__getattr__` and - :meth:`__getattribute__` methods are silently ignored. + :meth:`~object.__getattribute__` methods are silently ignored. For proper error handling, use :c:func:`PyObject_GetAttr` instead. From b83c9a2b39b348214d5be4e293a56f99a5892f86 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:12:59 -0700 Subject: [PATCH 07/15] ~object Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 28c212a2f8df97..3781c15b58b832 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -125,7 +125,7 @@ Dictionary Objects .. note:: Exceptions that occur while this calls :meth:`__hash__` and - :meth:`__eq__` methods or while creating the temporary ``str`` + :meth:`~object.__eq__` methods or while creating the temporary :class:`str` object are silently ignored. Prefer using the :c:func:`PyDict_GetItemWithError` function with your own :c:func:`PyUnicode_FromString` *key* instead. From 702ff45ea489eb6a758faff2b1b88b226e9a0ffc Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:13:15 -0700 Subject: [PATCH 08/15] ~object Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 3781c15b58b832..76f1776e748275 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -124,7 +124,7 @@ Dictionary Objects .. note:: - Exceptions that occur while this calls :meth:`__hash__` and + Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:`~object.__eq__` methods or while creating the temporary :class:`str` object are silently ignored. Prefer using the :c:func:`PyDict_GetItemWithError` function with your own From cfa054bb100154f092d2a59f1e7dd084768832a4 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:13:30 -0700 Subject: [PATCH 09/15] Update Doc/c-api/dict.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 76f1776e748275..81c15a9decccce 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -122,7 +122,7 @@ Dictionary Objects This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:expr:`const char*`, rather than a :c:expr:`PyObject*`. - .. note:: + .. caution:: Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:`~object.__eq__` methods or while creating the temporary :class:`str` From 42beeb4c2e1542bd1259a2790435ec52114b8008 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:13:39 -0700 Subject: [PATCH 10/15] Update Doc/c-api/dict.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 81c15a9decccce..6cd7661fbb69ad 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -98,7 +98,7 @@ Dictionary Objects Return the object from dictionary *p* which has a key *key*. Return ``NULL`` if the key *key* is not present, but *without* setting an exception. - .. note:: + .. caution:: Exceptions that occur while this calls :meth:`__hash__` and :meth:`__eq__` methods are silently ignored. From b24b019c31c8d3d4ca9c17526a1cacdf3575ae24 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:13:57 -0700 Subject: [PATCH 11/15] Update Doc/c-api/dict.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 6cd7661fbb69ad..f1c1273c449df1 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -100,7 +100,7 @@ Dictionary Objects .. caution:: - Exceptions that occur while this calls :meth:`__hash__` and + Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:`__eq__` methods are silently ignored. Prefer the :c:func:`PyDict_GetItemWithError` function instead. From 302c387b338e89bb55613cd1968434b92fafa7cf Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:14:04 -0700 Subject: [PATCH 12/15] Update Doc/c-api/dict.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index f1c1273c449df1..d23d94daebc628 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -101,7 +101,7 @@ Dictionary Objects .. caution:: Exceptions that occur while this calls :meth:`~object.__hash__` and - :meth:`__eq__` methods are silently ignored. + :meth:`~object.__eq__` methods are silently ignored. Prefer the :c:func:`PyDict_GetItemWithError` function instead. .. versionchanged:: 3.10 From badc02769dc68d86dbf8c81ae8f681291a657c9a Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Fri, 23 Jun 2023 17:14:15 -0700 Subject: [PATCH 13/15] Update Doc/c-api/object.rst Co-authored-by: C.A.M. Gerlach --- Doc/c-api/object.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 78d3ba32074c0e..2261010ffc319d 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -35,7 +35,7 @@ Object Protocol .. caution:: - Exceptions that occur when this calls :meth:`__getattr__` and + Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:`~object.__getattribute__` methods are silently ignored. For proper error handling, use :c:func:`PyObject_GetAttr` instead. From 9aa6924c2c093d759a71f8d715eac7b4ae53317e Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 24 Jun 2023 16:15:29 -0700 Subject: [PATCH 14/15] back to note --- Doc/c-api/dict.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index d23d94daebc628..bd0c36a217e2ce 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -98,7 +98,7 @@ Dictionary Objects Return the object from dictionary *p* which has a key *key*. Return ``NULL`` if the key *key* is not present, but *without* setting an exception. - .. caution:: + .. note:: Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:`~object.__eq__` methods are silently ignored. @@ -122,7 +122,7 @@ Dictionary Objects This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:expr:`const char*`, rather than a :c:expr:`PyObject*`. - .. caution:: + .. note:: Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:`~object.__eq__` methods or while creating the temporary :class:`str` From 76d43efa772eccfbc54d8b12f9ac90a181df5105 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 24 Jun 2023 16:16:02 -0700 Subject: [PATCH 15/15] back to note --- Doc/c-api/object.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 2261010ffc319d..22e7458013fb3d 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -33,7 +33,7 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - .. caution:: + .. note:: Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:`~object.__getattribute__` methods are silently ignored. @@ -46,7 +46,7 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - .. caution:: + .. note:: Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`