8000 [3.12] Improve some C API documentation (GH-108768) (#108785) · python/cpython@246cb64 · GitHub
[go: up one dir, main page]
Skip to content

Commit 246cb64

Browse files
serhiy-storchakaserhiy-storchaka
authored
[3.12] Improve some C API documentation (GH-108768) (#108785)* Express functions which take argument as a C string in terms of functions which take Python object. * Use "note" directive for PyMapping_HasKey() and PyMapping_HasKeyString() notes.. (cherry picked from commit 6f97eee)
1 parent ba7e06b commit 246cb64

File tree

3 files changed

+43
-44
lines changed

3 files changed

+43
-44
lines changed

‎Doc/c-api/dict.rst

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -70,12 +70,9 @@ Dictionary Objects
7070
7171
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
7272
73-
.. index:: single: PyUnicode_FromString()
74-
75-
Insert *val* into the dictionary *p* using *key* as a key. *key* should
76-
be a :c:expr:`const char*` UTF-8 encoded bytes string. The key object is created using
77-
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
78-
failure. This function *does not* steal a reference to *val*.
73+
This is the same as :c:func:`PyDict_SetItem`, but *key* is
74+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
75+
rather than a :c:expr:`PyObject*`.
7976
8077
8178
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
@@ -88,10 +85,9 @@ Dictionary Objects
8885
8986
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
9087
91-
Remove the entry in dictionary *p* which has a key specified by the UTF-8
92-
encoded bytes string *key*.
93-
If *key* is not in the dictionary, :exc:`KeyError` is raised.
94-
Return ``0`` on success or ``-1`` on failure.
88+
This is the same as :c:func:`PyDict_DelItem`, but *key* is
89+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
90+
rather than a :c:expr:`PyObject*`.
9591
9692
9793
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

‎Doc/c-api/mapping.rst

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -28,30 +28,28 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
2828
2929
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
3030
31-
Return element of *o* corresponding to the string *key* or ``NULL`` on failure.
32-
This is the equivalent of the Python expression ``o[key]``.
33-
See also :c:func:`PyObject_GetItem`.
31+
This is the same as :c:func:`PyObject_GetItem`, but *key* is
32+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
33+
rather than a :c:expr:`PyObject*`.
3434
3535
3636
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
3737
38-
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
39-
failure. This is the equivalent of the Python statement ``o[key] = v``.
40-
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
41-
reference to *v*.
38+
This is the same as :c:func:`PyObject_SetItem`, but *key* is
39+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
40+
rather than a :c:expr:`PyObject*`.
4241
4342
4443
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
4544
46-
Remove the mapping for the object *key* from the object *o*. Return ``-1``
47-
on failure. This is equivalent to the Python statement ``del o[key]``.
4845
This is an alias of :c:func:`PyObject_DelItem`.
4946
5047
5148
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
5249
53-
Remove the mapping for the string *key* from the object *o*. Return ``-1``
54-
on failure. This is equivalent to the Python statement ``del o[key]``.
50+
This is the same as :c:func:`PyObject_DelItem`, but *key* is
51+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
52+
rather than a :c:expr:`PyObject*`.
5553
5654
5755
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
@@ -60,20 +58,25 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
6058
This is equivalent to the Python expression ``key in o``.
6159
This function always succeeds.
6260
63-
Note that exceptions which occur while calling the :meth:`~object.__getitem__`
64-
method will get suppressed.
65-
To get error reporting use :c:func:`PyObject_GetItem()` instead.
61+
.. note::
62+
63+
Exceptions which occur when this calls :meth:`~object.__getitem__`
64+
method are silently ignored.
65+
For proper error handling, use :c:func:`PyObject_GetItem()` instead.
6666
6767
6868
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
6969
70-
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
71-
This is equivalent to the Python expression ``key in o``.
72-
This function always succeeds.
70+
This is the same as :c:func:`PyMapping_HasKey`, but *key* is
71+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
72+
rather than a :c:expr:`PyObject*`.
73+
74+
.. note::
7375
74-
Note that exceptions which occur while calling the :meth:`~object.__getitem__`
75-
method and creating a temporary string object will get suppressed.
76-
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
76+
Exceptions that occur when this calls :meth:`~object.__getitem__`
77+
method or while creating the temporary :class:`str`
78+
object are silently ignored.
79+
For proper error handling, use :c:func:`PyMapping_GetItemString` instead.
7780
7881
7982
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)

‎Doc/c-api/object.rst

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,15 @@ Object Protocol
4242
4343
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
4444
45-
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
46-
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
47-
always succeeds.
45+
This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is
46+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
47+
rather than a :c:expr:`PyObject*`.
4848
4949
.. note::
5050
5151
Exceptions that occur when this calls :meth:`~object.__getattr__` and
52-
:meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
53-
object are silently ignored.
52+
:meth:`~object.__getattribute__` methods or while creating the temporary
53+
:class:`str` object are silently ignored.
5454
For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
5555
5656
@@ -63,9 +63,9 @@ Object Protocol
6363
6464
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
6565
66-
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
67-
value on success, or ``NULL`` on failure. This is the equivalent of the Python
68-
expression ``o.attr_name``.
66+
This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is
67+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
68+
rather than a :c:expr:`PyObject*`.
6969
7070
7171
.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
@@ -92,10 +92,9 @@ Object Protocol
9292
9393
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
9494
95-
Set the value of the attribute named *attr_name*, for object *o*, to the value
96-
*v*. Raise an exception and return ``-1`` on failure;
97-
return ``0`` on success. This is the equivalent of the Python statement
98-
``o.attr_name = v``.
95+
This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is
96+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
97+
rather than a :c:expr:`PyObject*`.
9998
10099
If *v* is ``NULL``, the attribute is deleted, but this feature is
101100
deprecated in favour of using :c:func:`PyObject_DelAttrString`.
@@ -121,8 +120,9 @@ Object Protocol
121120
122121
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
123122
124-
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
125-
This is the equivalent of the Python statement ``del o.attr_name``.
123+
This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is
124+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
125+
rather than a :c:expr:`PyObject*`.
126126
127127
128128
.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)

0 commit comments

Comments
 (0)
0