.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
- *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ *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``.
+ If *v* is *NULL*, the attribute is deleted, however this feature is
+ deprecated in favour of using :c:func:`PyObject_DelAttr`.
+
.. 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*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ *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``.
+ If *v* is *NULL*, the attribute is deleted, however this feature is
+ deprecated in favour of using :c:func:`PyObject_DelAttrString`.
+
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
- Generic attribute setter function that is meant to be put into a type
- object's ``tp_setattro`` slot. It looks for a data descriptor in the
+ Generic attribute setter and deleter function that is meant
+ to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
+ slot. It looks for a data descriptor in the
dictionary of classes in the object's MRO, and if found it takes preference
- over setting the attribute in the instance dictionary. Otherwise, the
- attribute is set in the object's :attr:`~object.__dict__` (if present).
- Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned.
+ over setting or deleting the attribute in the instance dictionary. Otherwise, the
+ attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
+ On success, ``0`` is returned, otherwise an :exc:`AttributeError`
+ is raised and ``-1`` is returned.
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
- Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
+ Map the object *key* 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[key] = v``.
.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
- Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This
+ Assign object *v* to the *i*\ th element of *o*. Raise an exception
+ and return ``-1`` on failure; return ``0`` on success. This
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
+ If *v* is *NULL*, the element is deleted, however this feature is
+ deprecated in favour of using :c:func:`PySequence_DelItem`.
+
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
- *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
+ *i2*. Raise an exception and return ``-1`` on failure; return ``0`` on success.
+ This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+ If *v* is *NULL*, the slice is deleted, however this feature is
+ deprecated in favour of using :c:func:`PySequence_DelSlice`.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
.. c:member:: setattrfunc PyTypeObject.tp_setattr
- An optional pointer to the set-attribute-string function.
+ An optional pointer to the function for setting and deleting attributes.
This field is deprecated. When it is defined, it should point to a function
that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string
instead of a Python string object to give the attribute name. The signature is
- the same as for :c:func:`PyObject_SetAttrString`.
+ the same as for :c:func:`PyObject_SetAttrString`, but setting
+ *v* to *NULL* to delete an attribute must be supported.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
.. c:member:: setattrofunc PyTypeObject.tp_setattro
- An optional pointer to the set-attribute function.
+ An optional pointer to the function for setting and deleting attributes.
- The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually
+ The signature is the same as for :c:func:`PyObject_SetAttr`, but setting
+ *v* to *NULL* to delete an attribute must be supported. It is usually
convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which
implements the normal way of setting object attributes.
typedef struct PyGetSetDef {
char *name; /* attribute name */
getter get; /* C function to get the attribute */
- setter set; /* C function to set the attribute */
+ setter set; /* C function to set or delete the attribute */
char *doc; /* optional doc string */
void *closure; /* optional additional data for getter and setter */
} PyGetSetDef;
.. c:member:: descrsetfunc PyTypeObject.tp_descr_set
- An optional pointer to a "descriptor set" function.
+ An optional pointer to a function for setting and deleting
+ a descriptor's value.
The function signature is ::
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
+ The *value* argument is set to *NULL* to delete the value.
This field is inherited by subtypes.
.. XXX explain.
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
- This function is used by :c:func:`PyObject_SetItem` and has the same
- signature. If this slot is *NULL*, the object does not support item
- assignment.
+ This function is used by :c:func:`PyObject_SetItem` and
+ :c:func:`PyObject_DelItem`. It has the same signature as
+ :c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete
+ an item. If this slot is *NULL*, the object does not support item
+ assignment and deletion.
.. _sequence-structs:
This function is used by :c:func:`PySequence_SetItem` and has the same
signature. This slot may be left to *NULL* if the object does not support
- item assignment.
+ item assignment and deletion.
.. c:member:: objobjproc PySequenceMethods.sq_contains
int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);
Set the value of the attribute named attr_name, for object o,
- to the value, v. Returns -1 on failure. This is
- the equivalent of the Python statement: o.attr_name=v.
+ 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.
*/
int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
Set the value of the attribute named attr_name, for object o,
- to the value, v. Returns -1 on failure. This is
- the equivalent of the Python statement: o.attr_name=v.
+ 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.
*/
PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
/*
- Map the object, key, to the value, v. Returns
- -1 on failure. This is the equivalent of the Python
- statement: o[key]=v.
+ Map the object key 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[key]=v.
*/
PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
/*
- Assign object v to the ith element of o. Returns
- -1 on failure. This is the equivalent of the Python
- statement: o[i]=v.
-
+ Assign object v to the ith element of o. Raise an exception and return
+ -1 on failure; return 0 on success. This is the equivalent of the
+ Python statement o[i]=v.
*/
PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
/*
Assign the sequence object, v, to the slice in sequence
- object, o, from i1 to i2. Returns -1 on failure. This is the
+ object, o, from i1 to i2. Raise an exception and return
+ -1 on failure; return 0 on success. This is the
equivalent of the Python statement: o[i1:i2]=v.
*/