Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3fcc1e0

Browse files
bpo-35461: Document C API functions which suppress exceptions. (GH-11119)
1 parent 62a68b7 commit 3fcc1e0

7 files changed

Lines changed: 35 additions & 4 deletions

File tree

Doc/c-api/buffer.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -429,7 +429,7 @@ Buffer-related functions
429429
430430
Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
431431
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
432-
succeed.
432+
succeed. This function always succeeds.
433433
434434
435435
.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
@@ -470,7 +470,7 @@ Buffer-related functions
470470
471471
Return ``1`` if the memory defined by the *view* is C-style (*order* is
472472
``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
473-
(*order* is ``'A'``). Return ``0`` otherwise.
473+
(*order* is ``'A'``). Return ``0`` otherwise. This function always succeeds.
474474
475475
476476
.. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)

Doc/c-api/codec.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Codec registry and support functions
1313
.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
1414
1515
Return ``1`` or ``0`` depending on whether there is a registered codec for
16-
the given *encoding*.
16+
the given *encoding*. This function always succeeds.
1717
1818
.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
1919

Doc/c-api/dict.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@ Dictionary Objects
9595
Return the object from dictionary *p* which has a key *key*. Return *NULL*
9696
if the key *key* is not present, but *without* setting an exception.
9797
98+
Note that exceptions which occur while calling :meth:`__hash__` and
99+
:meth:`__eq__` methods will get suppressed.
100+
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
101+
98102
99103
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
100104
@@ -109,6 +113,11 @@ Dictionary Objects
109113
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
110114
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
111115
116+
Note that exceptions which occur while calling :meth:`__hash__` and
117+
:meth:`__eq__` methods and creating a temporary string object
118+
will get suppressed.
119+
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
120+
112121
113122
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
114123

Doc/c-api/mapping.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,21 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
6060
This is equivalent to the Python expression ``key in o``.
6161
This function always succeeds.
6262
63+
Note that exceptions which occur while calling the :meth:`__getitem__`
64+
method will get suppressed.
65+
To get error reporting use :c:func:`PyObject_GetItem()` instead.
66+
6367
6468
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
6569
6670
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
6771
This is equivalent to the Python expression ``key in o``.
6872
This function always succeeds.
6973
74+
Note that exceptions which occur while calling the :meth:`__getitem__`
75+
method and creating a temporary string object will get suppressed.
76+
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
77+
7078
7179
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
7280

Doc/c-api/number.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,3 +280,4 @@ Number Protocol
280280
281281
Returns ``1`` if *o* is an index integer (has the nb_index slot of the
282282
tp_as_number structure filled in), and ``0`` otherwise.
283+
This function always succeeds.

Doc/c-api/objbuffer.rst

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,11 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
3939
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
4040
4141
Returns ``1`` if *o* supports the single-segment readable buffer interface.
42-
Otherwise returns ``0``.
42+
Otherwise returns ``0``. This function always succeeds.
43+
44+
Note that this function tries to get and release a buffer, and exceptions
45+
which occur while calling correspoding functions will get suppressed.
46+
To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
4347
4448
4549
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

Doc/c-api/object.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,22 @@ Object Protocol
3333
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
3434
always succeeds.
3535
36+
Note that exceptions which occur while calling :meth:`__getattr__` and
37+
:meth:`__getattribute__` methods will get suppressed.
38+
To get error reporting use :c:func:`PyObject_GetAttr()` instead.
39+
3640
3741
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
3842
3943
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
4044
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
4145
always succeeds.
4246
47+
Note that exceptions which occur while calling :meth:`__getattr__` and
48+
:meth:`__getattribute__` methods and creating a temporary string object
49+
will get suppressed.
50+
To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
51+
4352
4453
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
4554

0 commit comments

Comments
 (0)