Add optional docstrings to member descriptors. For backwards
compatibility, this required all places where an array of "struct
memberlist" structures was declared that is referenced from a type's
tp_members slot to change the type of the structure to PyMemberDef;
"struct memberlist" is now only used by old code that still calls
PyMember_Get/Set. The code in PyObject_GenericGetAttr/SetAttr now
calls the new APIs PyMember_GetOne/SetOne, which take a PyMemberDef
argument.
As examples, I added actual docstrings to the attributes of a few
types: file, complex, instance method, super, and xxsubtype.spamlist.
Also converted the symtable to new style getattr.
diff --git a/Objects/classobject.c b/Objects/classobject.c
index 3845dfc..f8ee6fd 100644
--- a/Objects/classobject.c
+++ b/Objects/classobject.c
@@ -2006,10 +2006,13 @@
#define OFF(x) offsetof(PyMethodObject, x)
-static struct memberlist instancemethod_memberlist[] = {
- {"im_class", T_OBJECT, OFF(im_class), READONLY|RESTRICTED},
- {"im_func", T_OBJECT, OFF(im_func), READONLY|RESTRICTED},
- {"im_self", T_OBJECT, OFF(im_self), READONLY|RESTRICTED},
+static PyMemberDef instancemethod_memberlist[] = {
+ {"im_class", T_OBJECT, OFF(im_class), READONLY|RESTRICTED,
+ "the class associated with a method"},
+ {"im_func", T_OBJECT, OFF(im_func), READONLY|RESTRICTED,
+ "the function (or other callable) implementing a method"},
+ {"im_self", T_OBJECT, OFF(im_self), READONLY|RESTRICTED,
+ "the instance to which a method is bound; None for unbound methods"},
{NULL} /* Sentinel */
};
diff --git a/Objects/complexobject.c b/Objects/complexobject.c
index a2ccadb..191dcba 100644
--- a/Objects/complexobject.c
+++ b/Objects/complexobject.c
@@ -625,9 +625,11 @@
{NULL, NULL} /* sentinel */
};
-static struct memberlist complex_members[] = {
- {"real", T_DOUBLE, offsetof(PyComplexObject, cval.real), 0},
- {"imag", T_DOUBLE, offsetof(PyComplexObject, cval.imag), 0},
+static PyMemberDef complex_members[] = {
+ {"real", T_DOUBLE, offsetof(PyComplexObject, cval.real), 0,
+ "the real part of a complex number"},
+ {"imag", T_DOUBLE, offsetof(PyComplexObject, cval.imag), 0,
+ "the imaginary part of a complex number"},
{0},
};
diff --git a/Objects/descrobject.c b/Objects/descrobject.c
index e5b08c3..dfbb3b6 100644
--- a/Objects/descrobject.c
+++ b/Objects/descrobject.c
@@ -21,7 +21,7 @@
typedef struct {
COMMON;
- struct memberlist *d_member;
+ PyMemberDef *d_member;
} PyMemberDescrObject;
typedef struct {
@@ -126,8 +126,7 @@
if (descr_check((PyDescrObject *)descr, obj, type, &res))
return res;
- return PyMember_Get((char *)obj, descr->d_member,
- descr->d_member->name);
+ return PyMember_GetOne((char *)obj, descr->d_member);
}
static PyObject *
@@ -181,8 +180,7 @@
if (descr_setcheck((PyDescrObject *)descr, obj, value, &res))
return res;
- return PyMember_Set((char *)obj, descr->d_member,
- descr->d_member->name, value);
+ return PyMember_SetOne((char *)obj, descr->d_member, value);
}
static int
@@ -289,7 +287,7 @@
}
static PyObject *
-member_get_doc(PyMethodDescrObject *descr, void *closure)
+method_get_doc(PyMethodDescrObject *descr, void *closure)
{
if (descr->d_method->ml_doc == NULL) {
Py_INCREF(Py_None);
@@ -298,12 +296,27 @@
return PyString_FromString(descr->d_method->ml_doc);
}
-static struct memberlist descr_members[] = {
+static PyMemberDef descr_members[] = {
{"__objclass__", T_OBJECT, offsetof(PyDescrObject, d_type), READONLY},
{"__name__", T_OBJECT, offsetof(PyDescrObject, d_name), READONLY},
{0}
};
+static struct getsetlist method_getset[] = {
+ {"__doc__", (getter)method_get_doc},
+ {0}
+};
+
+static PyObject *
+member_get_doc(PyMemberDescrObject *descr, void *closure)
+{
+ if (descr->d_member->doc == NULL) {
+ Py_INCREF(Py_None);
+ return Py_None;
+ }
+ return PyString_FromString(descr->d_member->doc);
+}
+
static struct getsetlist member_getset[] = {
{"__doc__", (getter)member_get_doc},
{0}
@@ -355,7 +368,7 @@
0, /* tp_iternext */
0, /* tp_methods */
descr_members, /* tp_members */
- member_getset, /* tp_getset */
+ method_getset, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
(descrgetfunc)method_get, /* tp_descr_get */
@@ -393,7 +406,7 @@
0, /* tp_iternext */
0, /* tp_methods */
descr_members, /* tp_members */
- 0, /* tp_getset */
+ member_getset, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
(descrgetfunc)member_get, /* tp_descr_get */
@@ -507,7 +520,7 @@
}
PyObject *
-PyDescr_NewMember(PyTypeObject *type, struct memberlist *member)
+PyDescr_NewMember(PyTypeObject *type, PyMemberDef *member)
{
PyMemberDescrObject *descr;
diff --git a/Objects/fileobject.c b/Objects/fileobject.c
index 6ceb83c..5c879ff 100644
--- a/Objects/fileobject.c
+++ b/Objects/fileobject.c
@@ -1383,10 +1383,13 @@
#define OFF(x) offsetof(PyFileObject, x)
-static struct memberlist file_memberlist[] = {
- {"softspace", T_INT, OFF(f_softspace)},
- {"mode", T_OBJECT, OFF(f_mode), RO},
- {"name", T_OBJECT, OFF(f_name), RO},
+static PyMemberDef file_memberlist[] = {
+ {"softspace", T_INT, OFF(f_softspace), 0,
+ "flag indicating that a space needs to be printed; used by print"},
+ {"mode", T_OBJECT, OFF(f_mode), RO,
+ "file mode ('r', 'w', 'a', possibly with 'b' or '+' added)"},
+ {"name", T_OBJECT, OFF(f_name), RO,
+ "file name"},
/* getattr(f, "closed") is implemented without this table */
{NULL} /* Sentinel */
};
diff --git a/Objects/frameobject.c b/Objects/frameobject.c
index fd9a4e2..cb7e80a 100644
--- a/Objects/frameobject.c
+++ b/Objects/frameobject.c
@@ -10,7 +10,7 @@
#define OFF(x) offsetof(PyFrameObject, x)
-static struct memberlist frame_memberlist[] = {
+static PyMemberDef frame_memberlist[] = {
{"f_back", T_OBJECT, OFF(f_back), RO},
{"f_code", T_OBJECT, OFF(f_code), RO},
{"f_builtins", T_OBJECT, OFF(f_builtins),RO},
diff --git a/Objects/funcobject.c b/Objects/funcobject.c
index 91a3127..e1cf080 100644
--- a/Objects/funcobject.c
+++ b/Objects/funcobject.c
@@ -129,7 +129,7 @@
#define RR ()
-static struct memberlist func_memberlist[] = {
+static PyMemberDef func_memberlist[] = {
{"func_closure", T_OBJECT, OFF(func_closure),
RESTRICTED|READONLY},
{"func_doc", T_OBJECT, OFF(func_doc), WRITE_RESTRICTED},
diff --git a/Objects/moduleobject.c b/Objects/moduleobject.c
index 6d91ecc..586785c 100644
--- a/Objects/moduleobject.c
+++ b/Objects/moduleobject.c
@@ -9,7 +9,7 @@
PyObject *md_dict;
} PyModuleObject;
-struct memberlist module_members[] = {
+PyMemberDef module_members[] = {
{"__dict__", T_OBJECT, offsetof(PyModuleObject, md_dict), READONLY},
{0}
};
diff --git a/Objects/sliceobject.c b/Objects/sliceobject.c
index 8f52f9e..81517a8 100644
--- a/Objects/sliceobject.c
+++ b/Objects/sliceobject.c
@@ -129,7 +129,7 @@
return s;
}
-static struct memberlist slice_members[] = {
+static PyMemberDef slice_members[] = {
{"start", T_OBJECT, offsetof(PySliceObject, start), READONLY},
{"stop", T_OBJECT, offsetof(PySliceObject, stop), READONLY},
{"step", T_OBJECT, offsetof(PySliceObject, step), READONLY},
diff --git a/Objects/typeobject.c b/Objects/typeobject.c
index 26ddabe..b53555d 100644
--- a/Objects/typeobject.c
+++ b/Objects/typeobject.c
@@ -4,7 +4,7 @@
#include "Python.h"
#include "structmember.h"
-static struct memberlist type_members[] = {
+static PyMemberDef type_members[] = {
{"__basicsize__", T_INT, offsetof(PyTypeObject,tp_basicsize),READONLY},
{"__itemsize__", T_INT, offsetof(PyTypeObject, tp_itemsize), READONLY},
{"__flags__", T_LONG, offsetof(PyTypeObject, tp_flags), READONLY},
@@ -263,7 +263,7 @@
PyMappingMethods as_mapping;
PyBufferProcs as_buffer;
PyObject *name, *slots;
- struct memberlist members[1];
+ PyMemberDef members[1];
} etype;
/* type test with subclassing support */
@@ -672,7 +672,7 @@
PyObject *slots, *tmp;
PyTypeObject *type, *base, *tmptype, *winner;
etype *et;
- struct memberlist *mp;
+ PyMemberDef *mp;
int i, nbases, nslots, slotoffset, dynamic, add_dict, add_weak;
/* Special case: type(x) should return x->ob_type */
@@ -1087,7 +1087,7 @@
0, /* ob_size */
"type", /* tp_name */
sizeof(etype), /* tp_basicsize */
- sizeof(struct memberlist), /* tp_itemsize */
+ sizeof(PyMemberDef), /* tp_itemsize */
(destructor)type_dealloc, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
@@ -1192,7 +1192,7 @@
PyObject_Del(self);
}
-static struct memberlist object_members[] = {
+static PyMemberDef object_members[] = {
{"__class__", T_OBJECT, offsetof(PyObject, ob_type), READONLY},
{0}
};
@@ -1263,7 +1263,7 @@
}
static int
-add_members(PyTypeObject *type, struct memberlist *memb)
+add_members(PyTypeObject *type, PyMemberDef *memb)
{
PyObject *dict = type->tp_defined;
@@ -3221,9 +3221,11 @@
PyObject *obj;
} superobject;
-static struct memberlist super_members[] = {
- {"__type__", T_OBJECT, offsetof(superobject, type), READONLY},
- {"__obj__", T_OBJECT, offsetof(superobject, obj), READONLY},
+static PyMemberDef super_members[] = {
+ {"__thisclass__", T_OBJECT, offsetof(superobject, type), READONLY,
+ "the class invoking super()"},
+ {"__self__", T_OBJECT, offsetof(superobject, obj), READONLY,
+ "the instance invoking super(); may be None"},
{0}
};