[Python-checkins] cpython (3.4): Issue #24808: Update the documentation of some PyTypeObject fields

[martin.panter]

https://hg.python.org/cpython/rev/54a9c649281d
changeset:   97487:54a9c649281d
branch:      3.4
parent:      97481:71b59d01eea5
user:        Martin Panter <vadmium>
date:        Tue Aug 25 05:06:39 2015 +0000
summary:
  Issue #24808: Update the documentation of some PyTypeObject fields

Patch by Joseph Weston.

files:
  Doc/c-api/typeobj.rst      |  10 +++++-----
  Doc/extending/newtypes.rst |   6 +++---
  Doc/includes/typestruct.h  |  15 +++++++--------
  Misc/ACKS                  |   1 +
  Misc/NEWS                  |   3 +++
  5 files changed, 19 insertions(+), 16 deletions(-)


diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -94,7 +94,7 @@
    This field is not inherited by subtypes.
 
 
-.. c:member:: char* PyTypeObject.tp_name
+.. c:member:: const char* PyTypeObject.tp_name
 
    Pointer to a NUL-terminated string containing the name of the type. For types
    that are accessible as module globals, the string should be the full module
@@ -367,7 +367,7 @@
    inherited individually.
 
 
-.. c:member:: long PyTypeObject.tp_flags
+.. c:member:: unsigned long PyTypeObject.tp_flags
 
    This field is a bit mask of various flags.  Some flags indicate variant
    semantics for certain situations; others are used to indicate that certain
@@ -467,7 +467,7 @@
       .. versionadded:: 3.4
 
 
-.. c:member:: char* PyTypeObject.tp_doc
+.. c:member:: const char* PyTypeObject.tp_doc
 
    An optional pointer to a NUL-terminated C string giving the docstring for this
    type object.  This is exposed as the :attr:`__doc__` attribute on the type and
@@ -614,7 +614,7 @@
    +----------------+------------+
 
 
-.. c:member:: long PyTypeObject.tp_weaklistoffset
+.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
 
    If the instances of this type are weakly referenceable, this field is greater
    than zero and contains the offset in the instance structure of the weak
@@ -781,7 +781,7 @@
    .. XXX explain.
 
 
-.. c:member:: long PyTypeObject.tp_dictoffset
+.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset
 
    If the instances of this type have a dictionary containing instance variables,
    this field is non-zero and contains the offset in the instances of the type of
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -893,20 +893,20 @@
 all the fields you need (even if they're initialized to ``0``) and then change
 the values to suit your new type. ::
 
-   char *tp_name; /* For printing */
+   const char *tp_name; /* For printing */
 
 The name of the type - as mentioned in the last section, this will appear in
 various places, almost entirely for diagnostic purposes. Try to choose something
 that will be helpful in such a situation! ::
 
-   int tp_basicsize, tp_itemsize; /* For allocation */
+   Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
 
 These fields tell the runtime how much memory to allocate when new objects of
 this type are created.  Python has some built-in support for variable length
 structures (think: strings, lists) which is where the :c:member:`~PyTypeObject.tp_itemsize` field
 comes in.  This will be dealt with later. ::
 
-   char *tp_doc;
+   const char *tp_doc;
 
 Here you can put a string (or its address) that you want returned when the
 Python script references ``obj.__doc__`` to retrieve the doc string.
diff --git a/Doc/includes/typestruct.h b/Doc/includes/typestruct.h
--- a/Doc/includes/typestruct.h
+++ b/Doc/includes/typestruct.h
@@ -1,7 +1,7 @@
 typedef struct _typeobject {
     PyObject_VAR_HEAD
-    char *tp_name; /* For printing, in format "<module>.<name>" */
-    int tp_basicsize, tp_itemsize; /* For allocation */
+    const char *tp_name; /* For printing, in format "<module>.<name>" */
+    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
 
     /* Methods to implement standard operations */
 
@@ -9,7 +9,7 @@
     printfunc tp_print;
     getattrfunc tp_getattr;
     setattrfunc tp_setattr;
-    void *tp_reserved;
+    void *tp_reserved; /* formerly known as tp_compare */
     reprfunc tp_repr;
 
     /* Method suites for standard classes */
@@ -30,9 +30,9 @@
     PyBufferProcs *tp_as_buffer;
 
     /* Flags to define presence of optional/expanded features */
-    long tp_flags;
+    unsigned long tp_flags;
 
-    char *tp_doc; /* Documentation string */
+    const char *tp_doc; /* Documentation string */
 
     /* call function for all accessible objects */
     traverseproc tp_traverse;
@@ -44,7 +44,7 @@
     richcmpfunc tp_richcompare;
 
     /* weak reference enabler */
-    long tp_weaklistoffset;
+    Py_ssize_t tp_weaklistoffset;
 
     /* Iterators */
     getiterfunc tp_iter;
@@ -58,7 +58,7 @@
     PyObject *tp_dict;
     descrgetfunc tp_descr_get;
     descrsetfunc tp_descr_set;
-    long tp_dictoffset;
+    Py_ssize_t tp_dictoffset;
     initproc tp_init;
     allocfunc tp_alloc;
     newfunc tp_new;
@@ -69,7 +69,6 @@
     PyObject *tp_cache;
     PyObject *tp_subclasses;
     PyObject *tp_weaklist;
-
     destructor tp_del;
 
     /* Type attribute cache version tag. Added in version 2.6 */
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1473,6 +1473,7 @@
 Edward Welbourne
 Cliff Wells
 Rickard Westman
+Joseph Weston
 Jeff Wheeler
 Christopher White
 David White
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -449,6 +449,9 @@
 Documentation
 -------------
 
+- Issue #24808: Update the types of some PyTypeObject fields. Patch by
+  Joseph Weston.
+
 - Issue #22812: Fix unittest discovery examples.
   Patch from Pam McA'Nulty.
 

-- 
Repository URL: https://hg.python.org/cpython