gh-47146: Soft-deprecate structmember.h, expose its contents via Python.h (GH-99014)

The ``structmember.h`` header is deprecated, though it continues to be available
and there are no plans to remove it. There are no deprecation warnings. Old code
can stay unchanged (unless the extra include and non-namespaced macros bother
you greatly). Specifically, no uses in CPython are updated -- that would just be
unnecessary churn.
The ``structmember.h`` header is deprecated, though it continues to be
available and there are no plans to remove it.

Its contents are now available just by including ``Python.h``,
with a ``Py`` prefix added if it was missing:

- `PyMemberDef`, `PyMember_GetOne` and`PyMember_SetOne`
- Type macros like `Py_T_INT`, `Py_T_DOUBLE`, etc.
  (previously ``T_INT``, ``T_DOUBLE``, etc.)
- The flags `Py_READONLY` (previously ``READONLY``) and
  `Py_AUDIT_READ` (previously all uppercase)

Several items are not exposed from ``Python.h``:

- `T_OBJECT` (use `Py_T_OBJECT_EX`)
- `T_NONE` (previously undocumented, and pretty quirky)
- The macro ``WRITE_RESTRICTED`` which does nothing.
- The macros ``RESTRICTED`` and ``READ_RESTRICTED``, equivalents of
  `Py_AUDIT_READ`.
- In some configurations, ``<stddef.h>`` is not included from ``Python.h``.
  It should be included manually when using ``offsetof()``.

The deprecated header continues to provide its original
contents under the original names.
Your old code can stay unchanged, unless the extra include and non-namespaced
macros bother you greatly.

There is discussion on the issue to rename `T_PYSSIZET` to `PY_T_SSIZE` or
similar. I chose not to do that -- users will probably copy/paste that with any
spelling, and not renaming it makes migration docs simpler.


Co-Authored-By: Alexander Belopolsky <abalkin@users.noreply.github.com>
Co-Authored-By: Matthias Braun <MatzeB@users.noreply.github.com>

2 files changed, 93 insertions, 57 deletions

diff --git a/Include/descrobject.h b/Include/descrobject.h
index 77f221d..0a420b8 100644
--- a/Include/descrobject.h
+++ b/Include/descrobject.h
@@ -32,6 +32,61 @@ PyAPI_FUNC(PyObject *) PyDescr_NewGetSet(PyTypeObject *, PyGetSetDef *);
 PyAPI_FUNC(PyObject *) PyDictProxy_New(PyObject *);
 PyAPI_FUNC(PyObject *) PyWrapper_New(PyObject *, PyObject *);
 
+
+/* An array of PyMemberDef structures defines the name, type and offset
+   of selected members of a C structure.  These can be read by
+   PyMember_GetOne() and set by PyMember_SetOne() (except if their READONLY
+   flag is set).  The array must be terminated with an entry whose name
+   pointer is NULL. */
+struct PyMemberDef {
+    const char *name;
+    int type;
+    Py_ssize_t offset;
+    int flags;
+    const char *doc;
+};
+
+// These constants used to be in structmember.h, not prefixed by Py_.
+// (structmember.h now has aliases to the new names.)
+
+/* Types */
+#define Py_T_SHORT     0
+#define Py_T_INT       1
+#define Py_T_LONG      2
+#define Py_T_FLOAT     3
+#define Py_T_DOUBLE    4
+#define Py_T_STRING    5
+#define _Py_T_OBJECT   6  // Deprecated, use Py_T_OBJECT_EX instead
+/* the ordering here is weird for binary compatibility */
+#define Py_T_CHAR      7   /* 1-character string */
+#define Py_T_BYTE      8   /* 8-bit signed int */
+/* unsigned variants: */
+#define Py_T_UBYTE     9
+#define Py_T_USHORT    10
+#define Py_T_UINT      11
+#define Py_T_ULONG     12
+
+/* Added by Jack: strings contained in the structure */
+#define Py_T_STRING_INPLACE    13
+
+/* Added by Lillo: bools contained in the structure (assumed char) */
+#define Py_T_BOOL      14
+
+#define Py_T_OBJECT_EX 16
+#define Py_T_LONGLONG  17
+#define Py_T_ULONGLONG 18
+
+#define Py_T_PYSSIZET  19      /* Py_ssize_t */
+#define _Py_T_NONE     20 // Deprecated. Value is always None.
+
+/* Flags */
+#define Py_READONLY            1
+#define Py_AUDIT_READ          2 // Added in 3.10, harmless no-op before that
+#define _Py_WRITE_RESTRICTED   4 // Deprecated, no-op. Do not reuse the value.
+
+PyAPI_FUNC(PyObject *) PyMember_GetOne(const char *, PyMemberDef *);
+PyAPI_FUNC(int) PyMember_SetOne(char *, PyMemberDef *, PyObject *);
+
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_DESCROBJECT_H
 #  include "cpython/descrobject.h"
diff --git a/Include/structmember.h b/Include/structmember.h
index 65a777d..f6e8fd8 100644
--- a/Include/structmember.h
+++ b/Include/structmember.h
@@ -5,69 +5,50 @@ extern "C" {
 #endif
 
 
-/* Interface to map C struct members to Python object attributes */
-
-#include <stddef.h> /* For offsetof */
-
-/* An array of PyMemberDef structures defines the name, type and offset
-   of selected members of a C structure.  These can be read by
-   PyMember_GetOne() and set by PyMember_SetOne() (except if their READONLY
-   flag is set).  The array must be terminated with an entry whose name
-   pointer is NULL. */
-
-struct PyMemberDef {
-    const char *name;
-    int type;
-    Py_ssize_t offset;
-    int flags;
-    const char *doc;
-};
+/* Interface to map C struct members to Python object attributes
+ *
+ * This header is deprecated: new code should not use stuff from here.
+ * New definitions are in descrobject.h.
+ *
+ * However, there's nothing wrong with old code continuing to use it,
+ * and there's not much mainenance overhead in maintaining a few aliases.
+ * So, don't be too eager to convert old code.
+ *
+ * It uses names not prefixed with Py_.
+ * It is also *not* included from Python.h and must be included individually.
+ */
+
+#include <stddef.h> /* For offsetof (not always provided by Python.h) */
 
 /* Types */
-#define T_SHORT     0
-#define T_INT       1
-#define T_LONG      2
-#define T_FLOAT     3
-#define T_DOUBLE    4
-#define T_STRING    5
-#define T_OBJECT    6
-/* XXX the ordering here is weird for binary compatibility */
-#define T_CHAR      7   /* 1-character string */
-#define T_BYTE      8   /* 8-bit signed int */
-/* unsigned variants: */
-#define T_UBYTE     9
-#define T_USHORT    10
-#define T_UINT      11
-#define T_ULONG     12
-
-/* Added by Jack: strings contained in the structure */
-#define T_STRING_INPLACE    13
-
-/* Added by Lillo: bools contained in the structure (assumed char) */
-#define T_BOOL      14
-
-#define T_OBJECT_EX 16  /* Like T_OBJECT, but raises AttributeError
-                           when the value is NULL, instead of
-                           converting to None. */
-#define T_LONGLONG      17
-#define T_ULONGLONG     18
-
-#define T_PYSSIZET      19      /* Py_ssize_t */
-#define T_NONE          20      /* Value is always None */
-
+#define T_SHORT     Py_T_SHORT
+#define T_INT       Py_T_INT
+#define T_LONG      Py_T_LONG
+#define T_FLOAT     Py_T_FLOAT
+#define T_DOUBLE    Py_T_DOUBLE
+#define T_STRING    Py_T_STRING
+#define T_OBJECT    _Py_T_OBJECT
+#define T_CHAR      Py_T_CHAR
+#define T_BYTE      Py_T_BYTE
+#define T_UBYTE     Py_T_UBYTE
+#define T_USHORT    Py_T_USHORT
+#define T_UINT      Py_T_UINT
+#define T_ULONG     Py_T_ULONG
+#define T_STRING_INPLACE    Py_T_STRING_INPLACE
+#define T_BOOL      Py_T_BOOL
+#define T_OBJECT_EX Py_T_OBJECT_EX
+#define T_LONGLONG  Py_T_LONGLONG
+#define T_ULONGLONG Py_T_ULONGLONG
+#define T_PYSSIZET  Py_T_PYSSIZET
+#define T_NONE      _Py_T_NONE
 
 /* Flags */
-#define READONLY            1
-#define READ_RESTRICTED     2
-#define PY_WRITE_RESTRICTED 4
+#define READONLY            Py_READONLY
+#define PY_AUDIT_READ        Py_AUDIT_READ
+#define READ_RESTRICTED     Py_AUDIT_READ
+#define PY_WRITE_RESTRICTED _Py_WRITE_RESTRICTED
 #define RESTRICTED          (READ_RESTRICTED | PY_WRITE_RESTRICTED)
 
-#define PY_AUDIT_READ       READ_RESTRICTED
-
-/* Current API, use this */
-PyAPI_FUNC(PyObject *) PyMember_GetOne(const char *, PyMemberDef *);
-PyAPI_FUNC(int) PyMember_SetOne(char *, PyMemberDef *, PyObject *);
-
 
 #ifdef __cplusplus
 }