.. 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)
.. 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)
.. 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)
.. 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)
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::
- 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.
+ 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)
.. 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.
.. 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.
.. 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
.. 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`.
.. 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)
projects / thirdparty / Python / cpython.git / commitdiff
