cpython: 50711c80ff76 (original) (raw)

Mercurial > cpython

changeset 99504:50711c80ff76 3.5

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. [#25701]

line wrap: on

line diff

--- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -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.

--- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -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)

--- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -208,12 +208,13 @@ type objects) must have the :attr:`ob_ .. 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_

.. 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_ typedef struct PyGetSetDef { char name; / attribute name / getter get; / C function to get the attribute */

•      setter set;    /* C function to set the attribute */[](#l3.36)

•      setter set;    /* C function to set or delete the attribute */[](#l3.37)
       char *doc;     /* optional doc string */[](#l3.38)
       void *closure; /* optional additional data for getter and setter */[](#l3.39)
   } PyGetSetDef;[](#l3.40)

@@ -775,12 +777,14 @@ type objects) must have the :attr:`ob_ .. 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

--- a/Include/abstract.h +++ b/Include/abstract.h @@ -192,8 +192,8 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 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[](#l4.7)

• the equivalent of the Python statement: o.attr_name=v.[](#l4.8)

• to the value v. Raise an exception and return -1 on failure; return 0 on[](#l4.9)

• success.  This is the equivalent of the Python statement o.attr_name=v.[](#l4.10)

*/ @@ -202,8 +202,8 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 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[](#l4.18)

• the equivalent of the Python statement: o.attr_name=v.[](#l4.19)

• to the value v. Raise an exception and return -1 on failure; return 0 on[](#l4.20)

• success.  This is the equivalent of the Python statement o.attr_name=v.[](#l4.21)

*/ @@ -435,9 +435,9 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject v); /

• Map the object, key, to the value, v.  Returns[](#l4.29)

• -1 on failure.  This is the equivalent of the Python[](#l4.30)

• statement: o[key]=v.[](#l4.31)

• Map the object key to the value v.  Raise an exception and return -1[](#l4.32)

• on failure; return 0 on success.  This is the equivalent of the Python[](#l4.33)

• statement o[key]=v.[](#l4.34)
    */[](#l4.35)

PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key); @@ -993,9 +993,9 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject v); /

• Assign object v to the ith element of o.  Returns[](#l4.42)

• -1 on failure.  This is the equivalent of the Python[](#l4.43)

• statement: o[i]=v.[](#l4.44)

• Assign object v to the ith element of o.  Raise an exception and return[](#l4.45)

• -1 on failure; return 0 on success.  This is the equivalent of the[](#l4.46)

• Python statement o[i]=v.[](#l4.47)
    */[](#l4.48)

PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);