From 0c82ee1a005b5ffd8ab00c7eb7644d68ec870938 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 11 Dec 2018 15:28:08 +0200 Subject: [PATCH 1/2] bpo-35461: Document C API functions which suppress exceptions. --- Doc/c-api/buffer.rst | 4 ++-- Doc/c-api/codec.rst | 2 +- Doc/c-api/dict.rst | 9 +++++++++ Doc/c-api/mapping.rst | 9 +++++++++ Doc/c-api/number.rst | 1 + Doc/c-api/objbuffer.rst | 6 +++++- Doc/c-api/object.rst | 9 +++++++++ 7 files changed, 36 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 33abb5bb94d9de..c7c1e3cc745ac4 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -429,7 +429,7 @@ Buffer-related functions Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will - succeed. + succeed. This function always succeeds. .. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags) @@ -470,7 +470,7 @@ Buffer-related functions Return ``1`` if the memory defined by the *view* is C-style (*order* is ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one - (*order* is ``'A'``). Return ``0`` otherwise. + (*order* is ``'A'``). Return ``0`` otherwise. This function always succeeds. .. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order) diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst index dfe3d436e5f4b7..c55f19970e125d 100644 --- a/Doc/c-api/codec.rst +++ b/Doc/c-api/codec.rst @@ -13,7 +13,7 @@ Codec registry and support functions .. c:function:: int PyCodec_KnownEncoding(const char *encoding) Return ``1`` or ``0`` depending on whether there is a registered codec for - the given *encoding*. + the given *encoding*. This function always succeeds. .. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index b7225faf408ca0..a09b13703e08ab 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -95,6 +95,10 @@ 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 errors raised in :meth:`__hash__` and :meth:`__eq__` methods + will get suppressed. To get error reporting use + :c:func:`PyDict_GetItemWithError()` instead. + .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key) @@ -109,6 +113,11 @@ Dictionary Objects This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:type:`const char\*`, rather than a :c:type:`PyObject\*`. + Note that errors raised in :meth:`__hash__` and :meth:`__eq__` methods, + as well as errors raised when fail to create a temporary string object, + will get suppressed. To get error reporting use + :c:func:`PyDict_GetItemWithError()` instead. + .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default) diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index b8eaadbd702c10..372de85876c7a3 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -60,6 +60,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and This is equivalent to the Python expression ``key in o``. This function always succeeds. + Note that errors raised in the :meth:`__getitem__` method + will get suppressed. To get error reporting use + :c:func:`PyObject_GetItem()` instead. + .. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) @@ -67,6 +71,11 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and This is equivalent to the Python expression ``key in o``. This function always succeeds. + Note that errors raised in the :meth:`__getitem__` method, + as well as errors raised when fail to create a temporary string object, + will get suppressed. To get error reporting use + :c:func:`PyMapping_GetItemString()` instead. + .. c:function:: PyObject* PyMapping_Keys(PyObject *o) diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst index 3c7605a67fa226..296b21c132b79a 100644 --- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -280,3 +280,4 @@ Number Protocol Returns ``1`` if *o* is an index integer (has the nb_index slot of the tp_as_number structure filled in), and ``0`` otherwise. + This function always succeeds. diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst index e7f4fde00256db..3f51334e3f540c 100644 --- a/Doc/c-api/objbuffer.rst +++ b/Doc/c-api/objbuffer.rst @@ -39,7 +39,11 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released. .. c:function:: int PyObject_CheckReadBuffer(PyObject *o) Returns ``1`` if *o* supports the single-segment readable buffer interface. - Otherwise returns ``0``. + Otherwise returns ``0``. This function always succeeds. + + Note that this function tries to get and release a buffer, and errors + raised when get a buffer will get suppressed. To get error reporting use + :c:func:`PyObject_GetBuffer()` instead. .. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index f0b2005f2d12cc..84aea27ce652a5 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -33,6 +33,10 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. + Note that errors raised in :meth:`__getattr__` and :meth:`__getattribute__` methods + will get suppressed. To get error reporting use + :c:func:`PyObject_GetAttr()` instead. + .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name) @@ -40,6 +44,11 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. + Note that errors raised in :meth:`__getattr__` and :meth:`__getattribute__` methods, + as well as errors raised when fail to create a temporary string object, + will get suppressed. To get error reporting use + :c:func:`PyObject_GetAttrString()` instead. + .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name) From 650ed79e9dcd6f12b2cd0adcc9d6e3fd1ea929d0 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 17 Dec 2018 17:26:45 +0200 Subject: [PATCH 2/2] Change wording. --- Doc/c-api/dict.rst | 14 +++++++------- Doc/c-api/mapping.rst | 13 ++++++------- Doc/c-api/objbuffer.rst | 6 +++--- Doc/c-api/object.rst | 14 +++++++------- 4 files changed, 23 insertions(+), 24 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index a09b13703e08ab..4e55c1a977cefb 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -95,9 +95,9 @@ 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 errors raised in :meth:`__hash__` and :meth:`__eq__` methods - will get suppressed. To get error reporting use - :c:func:`PyDict_GetItemWithError()` instead. + 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. .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key) @@ -113,10 +113,10 @@ Dictionary Objects This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:type:`const char\*`, rather than a :c:type:`PyObject\*`. - Note that errors raised in :meth:`__hash__` and :meth:`__eq__` methods, - as well as errors raised when fail to create a temporary string object, - will get suppressed. To get error reporting use - :c:func:`PyDict_GetItemWithError()` instead. + 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. .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default) diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 372de85876c7a3..e37dec9949ab68 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -60,9 +60,9 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and This is equivalent to the Python expression ``key in o``. This function always succeeds. - Note that errors raised in the :meth:`__getitem__` method - will get suppressed. To get error reporting use - :c:func:`PyObject_GetItem()` instead. + Note that exceptions which occur while calling the :meth:`__getitem__` + method will get suppressed. + To get error reporting use :c:func:`PyObject_GetItem()` instead. .. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) @@ -71,10 +71,9 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and This is equivalent to the Python expression ``key in o``. This function always succeeds. - Note that errors raised in the :meth:`__getitem__` method, - as well as errors raised when fail to create a temporary string object, - will get suppressed. To get error reporting use - :c:func:`PyMapping_GetItemString()` instead. + Note that exceptions which occur while calling the :meth:`__getitem__` + method and creating a temporary string object will get suppressed. + To get error reporting use :c:func:`PyMapping_GetItemString()` instead. .. c:function:: PyObject* PyMapping_Keys(PyObject *o) diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst index 3f51334e3f540c..9ad7c571c4d8c1 100644 --- a/Doc/c-api/objbuffer.rst +++ b/Doc/c-api/objbuffer.rst @@ -41,9 +41,9 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released. Returns ``1`` if *o* supports the single-segment readable buffer interface. Otherwise returns ``0``. This function always succeeds. - Note that this function tries to get and release a buffer, and errors - raised when get a buffer will get suppressed. To get error reporting use - :c:func:`PyObject_GetBuffer()` instead. + Note that this function tries to get and release a buffer, and exceptions + which occur while calling correspoding functions will get suppressed. + To get error reporting use :c:func:`PyObject_GetBuffer()` instead. .. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 84aea27ce652a5..a64ff2e6b58b4c 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -33,9 +33,9 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - Note that errors raised in :meth:`__getattr__` and :meth:`__getattribute__` methods - will get suppressed. To get error reporting use - :c:func:`PyObject_GetAttr()` instead. + 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. .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name) @@ -44,10 +44,10 @@ Object Protocol is equivalent to the Python expression ``hasattr(o, attr_name)``. This function always succeeds. - Note that errors raised in :meth:`__getattr__` and :meth:`__getattribute__` methods, - as well as errors raised when fail to create a temporary string object, - will get suppressed. To get error reporting use - :c:func:`PyObject_GetAttrString()` instead. + 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. .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)