Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Issue #25701: Document C API functions that both set and delete objects 

Also document that the separate functions that delete objects are preferred;
using PyObject_SetAttr(), _SetAttrString(), and PySequence_SetItem() to
delete is deprecated.
This commit is contained in:
Martin Panter 2015-12-08 00:03:20 +00:00
parent f17468961f
commit 45be8d67be
4 changed files with 50 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Doc/c-api/object.rst
View File

@ -68,25 +68,35 @@ Object Protocol
.. 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)
@ -378,7 +388,8 @@ Object Protocol
.. 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``.

6
Doc/c-api/sequence.rst
View File

@ -62,10 +62,14 @@ Sequence Protocol
.. 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`.
.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)

26
Doc/c-api/typeobj.rst
View File

@ -208,12 +208,13 @@ type objects) *must* have the :attr:`ob_size` field.
.. 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
@ -351,9 +352,10 @@ type objects) *must* have the :attr:`ob_size` field.
.. 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.
@ -724,7 +726,7 @@ type objects) *must* have the :attr:`ob_size` field.
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;
@ -775,12 +777,14 @@ type objects) *must* have the :attr:`ob_size` field.
.. 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.
@ -1171,9 +1175,11 @@ Mapping Object Structures
.. 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:
@ -1222,7 +1228,7 @@ Sequence Object Structures
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

20
Include/abstract.h
View File

@ -192,8 +192,8 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
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: 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.
*/
@ -202,8 +202,8 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
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.
*/
@ -435,9 +435,9 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
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, const char *key);
@ -993,9 +993,9 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
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);