[docs] Document that tp_setattro and tp_setattr are used for deleting attributes (issue 25701)
storchaka at gmail.com
storchaka at gmail.com
Tue Dec 1 10:50:59 EST 2015
Reviewers: haypo, vadmium,
http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst
File Doc/c-api/object.rst (right):
http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode71
Doc/c-api/object.rst:71: object *o*. If *v* is *NULL*, delete the value
(``del o.attr_name``),
May be refer to PyObject_DelAttr if v is NULL?
http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode72
Doc/c-api/object.rst:72: otherwise set it to *v* (``o.attr_name = v``).
Raises an exception and
It looks to me that "Return" and "Raise" are more preferable to
"Returns" and "Raises" in the documentation.
Please review this at http://bugs.python.org/review/25701/
Affected files:
Doc/c-api/object.rst
Doc/c-api/sequence.rst
Doc/c-api/typeobj.rst
Include/abstract.h
# HG changeset patch
# Parent ebec1a98ab81d19245e4bde2da03ccb489b9eb5f
Issue #25701: Document C API functions that both set and delete objects
diff -r ebec1a98ab81 Doc/c-api/object.rst
--- a/Doc/c-api/object.rst Mon Nov 23 16:44:30 2015 +0200
+++ b/Doc/c-api/object.rst Mon Nov 30 05:38:20 2015 +0000
@@ -67,26 +67,29 @@
.. 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
- ``o.attr_name = v``.
+ Set or delete the value of the attribute named *attr_name*, for
+ object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``),
+ otherwise set it to *v* (``o.attr_name = v``). Raises an exception and
+ returns ``-1`` on failure; returns ``0`` on success.
.. 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
- ``o.attr_name = v``.
+ Set or delete the value of the attribute named *attr_name*, for
+ object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``),
+ otherwise set it to *v* (``o.attr_name = v``). Raises an exception and
+ returns ``-1`` on failure; returns ``0`` on success.
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
- Generic attribute setter function that is meant to be put into a type
+ Generic attribute setter and deleter function that is meant to be put into a type
object's ``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 +381,8 @@
.. 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*. Raises an exception and
+ returns ``-1`` on failure; returns ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``.
diff -r ebec1a98ab81 Doc/c-api/sequence.rst
--- a/Doc/c-api/sequence.rst Mon Nov 23 16:44:30 2015 +0200
+++ b/Doc/c-api/sequence.rst Mon Nov 30 05:38:20 2015 +0000
@@ -62,8 +62,10 @@
.. 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
- is the equivalent of the Python statement ``o[i] = v``. This function *does
+ Assign object *v* to the *i*\ th element of *o*, or delete the
+ element if *v* is *NULL*. Raises an exception and returns ``-1`` on
+ failure; returns ``0`` on success. This is the equivalent of the
+ Python statements ``o[i] = v`` and ``del o[i]``. This function *does
not* steal a reference to *v*.
diff -r ebec1a98ab81 Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst Mon Nov 23 16:44:30 2015 +0200
+++ b/Doc/c-api/typeobj.rst Mon Nov 30 05:38:20 2015 +0000
@@ -208,7 +208,7 @@
.. 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
@@ -351,7 +351,7 @@
.. 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
convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which
@@ -724,7 +724,7 @@
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,7 +775,8 @@
.. 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 ::
@@ -1171,9 +1172,11 @@
.. 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 +1225,7 @@
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
diff -r ebec1a98ab81 Include/abstract.h
--- a/Include/abstract.h Mon Nov 23 16:44:30 2015 +0200
+++ b/Include/abstract.h Mon Nov 30 05:38:20 2015 +0000
@@ -191,9 +191,10 @@
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.
+ Set or delete the value of the attribute named attr_name, for object o.
+ If v is NULL, delete the value (del o.attr_name), otherwise set it to v
+ (o.attr_name=v). Raises an exception and returns -1 on failure; returns
+ 0 on success.
*/
@@ -201,9 +202,10 @@
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.
+ Set or delete the value of the attribute named attr_name, for object o.
+ If v is NULL, delete the value (del o.attr_name), otherwise set it to v
+ (o.attr_name=v). Raises an exception and returns -1 on failure; returns
+ 0 on success.
*/
@@ -993,9 +995,10 @@
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, or delete the element if v is
+ NULL. Raises an exception and returns -1 on failure; returns 0 on
+ success. This is the equivalent of the Python statements: "o[i]=v" and
+ "del o[i]".
*/
PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
More information about the docs
mailing list