Issue #24808: Update the documentation of some PyTypeObject fields

Patch by Joseph Weston.

Doc/c-api/typeobj.rst

@@ -94,7 +94,7 @@ type objects) *must* have the :attr:`ob_size` field.
    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 @@ type objects) *must* have the :attr:`ob_size` field.
    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 @@ type objects) *must* have the :attr:`ob_size` field.
       .. 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 @@ type objects) *must* have the :attr:`ob_size` field.
    +----------------+------------+
 
 
-.. 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 @@ type objects) *must* have the :attr:`ob_size` field.
    .. 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

Doc/extending/newtypes.rst

@@ -893,20 +893,20 @@ fields in the right order!  It's often easiest to find an example that includes
 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.

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 @@ typedef struct _typeobject {
     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 @@ typedef struct _typeobject {
     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 @@ typedef struct _typeobject {
     richcmpfunc tp_richcompare;
 
     /* weak reference enabler */
-    long tp_weaklistoffset;
+    Py_ssize_t tp_weaklistoffset;
 
     /* Iterators */
     getiterfunc tp_iter;
@@ -58,7 +58,7 @@ typedef struct _typeobject {
     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 @@ typedef struct _typeobject {
     PyObject *tp_cache;
     PyObject *tp_subclasses;
     PyObject *tp_weaklist;
-
     destructor tp_del;
 
     /* Type attribute cache version tag. Added in version 2.6 */

Misc/ACKS

@@ -1473,6 +1473,7 @@ Bob Weiner
 Edward Welbourne
 Cliff Wells
 Rickard Westman
+Joseph Weston
 Jeff Wheeler
 Christopher White
 David White

Misc/NEWS

@@ -449,6 +449,9 @@ C API
 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.