mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Improve some C API documentation (GH-108768)

Browse source 
* 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.
This commit is contained in:
Serhiy Storchaka 2023-09-01 22:21:39 +03:00 • committed by GitHub
parent 45b9e6a61f
commit 6f97eeec22
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 51 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

16
Doc/c-api/dict.rst
View file

@ -79,12 +79,9 @@ Dictionary Objects
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:expr:`const char*` UTF-8 encoded bytes string. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*.
This is the same as :c:func:`PyDict_SetItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
@ -97,10 +94,9 @@ Dictionary Objects
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
Remove the entry in dictionary *p* which has a key specified by the UTF-8
encoded bytes string *key*.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
This is the same as :c:func:`PyDict_DelItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)

57
Doc/c-api/mapping.rst
View file

@ -28,9 +28,9 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
Return element of *o* corresponding to the string *key* or ``NULL`` on failure.
This is the equivalent of the Python expression ``o[key]``.
See also :c:func:`PyObject_GetItem`.
This is the same as :c:func:`PyObject_GetItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)
@ -50,38 +50,30 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
.. c:function:: int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)
Variant of :c:func:`PyMapping_GetItemString` which doesn't raise
:exc:`KeyError` if the key is not found.
If the key is found, return ``1`` and set *\*result* to a new
:term:`strong reference` to the corresponding value.
If the key is not found, return ``0`` and set *\*result* to ``NULL``;
the :exc:`KeyError` is silenced.
If an error other than :exc:`KeyError` is raised, return ``-1`` and
set *\*result* to ``NULL``.
This is the same as :c:func:`PyMapping_GetOptionalItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. versionadded:: 3.13
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``o[key] = v``.
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
reference to *v*.
This is the same as :c:func:`PyObject_SetItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
Remove the mapping for the object *key* from the object *o*. Return ``-1``
on failure. This is equivalent to the Python statement ``del o[key]``.
This is an alias of :c:func:`PyObject_DelItem`.
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
Remove the mapping for the string *key* from the object *o*. Return ``-1``
on failure. This is equivalent to the Python statement ``del o[key]``.
This is the same as :c:func:`PyObject_DelItem`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
@ -90,20 +82,27 @@ 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 exceptions which occur while calling the :meth:`~object.__getitem__`
method will get suppressed.
To get error reporting use :c:func:`PyObject_GetItem()` instead.
.. note::
Exceptions which occur when this calls :meth:`~object.__getitem__`
method are silently ignored.
For proper error handling, use :c:func:`PyMapping_GetOptionalItem` or
:c:func:`PyObject_GetItem()` instead.
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
This is equivalent to the Python expression ``key in o``.
This function always succeeds.
This is the same as :c:func:`PyMapping_HasKey`, but *key* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
Note that exceptions which occur while calling the :meth:`~object.__getitem__`
method and creating a temporary string object will get suppressed.
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
.. note::
Exceptions that occur when this calls :meth:`~object.__getitem__`
method or while creating the temporary :class:`str`
object are silently ignored.
For proper error handling, use :c:func:`PyMapping_GetOptionalItemString` or
:c:func:`PyMapping_GetItemString` instead.
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)

40
Doc/c-api/object.rst
View file

@ -43,15 +43,15 @@ Object Protocol
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. note::
Exceptions that occur when this calls :meth:`~object.__getattr__` and
:meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
object are silently ignored.
:meth:`~object.__getattribute__` methods or while creating the temporary
:class:`str` object are silently ignored.
For proper error handling, use :c:func:`PyObject_GetOptionalAttrString`
or :c:func:`PyObject_GetAttrString` instead.
@ -68,9 +68,9 @@ Object Protocol
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or ``NULL`` on failure. This is the equivalent of the Python
expression ``o.attr_name``.
This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
If the missing attribute should not be treated as a failure, you can use
:c:func:`PyObject_GetOptionalAttrString` instead.
@ -93,15 +93,9 @@ Object Protocol
.. c:function:: int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);
Variant of :c:func:`PyObject_GetAttrString` which doesn't raise
:exc:`AttributeError` if the attribute is not found.
If the attribute is found, return ``1`` and set *\*result* to a new
:term:`strong reference` to the attribute.
If the attribute is not found, return ``0`` and set *\*result* to ``NULL``;
the :exc:`AttributeError` is silenced.
If an error other than :exc:`AttributeError` is raised, return ``-1`` and
set *\*result* to ``NULL``.
This is the same as :c:func:`PyObject_GetOptionalAttr`, but *attr_name* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. versionadded:: 3.13
@ -129,10 +123,9 @@ Object Protocol
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
*v*. Raise an exception and return ``-1`` on failure;
return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``.
This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
If *v* is ``NULL``, the attribute is deleted, but this feature is
deprecated in favour of using :c:func:`PyObject_DelAttrString`.
@ -158,8 +151,9 @@ Object Protocol
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``del o.attr_name``.
This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)