[3.10] gh-91118: Fix docstrings that do not honor --without-doc-strings (GH-31769)

Doc/c-api/typeobj.rst

@@ -2596,7 +2596,7 @@ A basic :ref:`static type <static-types>`::
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "mymod.MyObject",
  .tp_basicsize = sizeof(MyObject),
- .tp_doc = "My objects",
+ .tp_doc = PyDoc_STR("My objects"),
  .tp_new = myobj_new,
  .tp_dealloc = (destructor)myobj_dealloc,
  .tp_repr = (reprfunc)myobj_repr,
@@ -2626,7 +2626,7 @@ with a more verbose initializer::
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  0, /* tp_flags */
- "My objects",  /* tp_doc */
+PyDoc_STR("My objects"), /* tp_doc */
  0, /* tp_traverse */
  0, /* tp_clear */
  0, /* tp_richcompare */
@@ -2659,7 +2659,7 @@ A type that supports weakrefs, instance dicts, and hashing::
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "mymod.MyObject",
  .tp_basicsize = sizeof(MyObject),
- .tp_doc = "My objects",
+ .tp_doc = PyDoc_STR("My objects"),
  .tp_weaklistoffset = offsetof(MyObject, weakreflist),
  .tp_dictoffset = offsetof(MyObject, inst_dict),
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@@ -2687,7 +2687,7 @@ to create instances (e.g. uses a separate factory func) using
  .tp_name = "mymod.MyStr",
  .tp_basicsize = sizeof(MyStr),
  .tp_base = NULL, // set to &PyUnicode_Type in module init
- .tp_doc = "my custom str",
+ .tp_doc = PyDoc_STR("my custom str"),
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,
  .tp_repr = (reprfunc)myobj_repr,
  };

Doc/extending/newtypes_tutorial.rst

@@ -90,7 +90,7 @@ The second bit is the definition of the type object. ::
  static PyTypeObject CustomType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "custom.Custom",
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
  .tp_basicsize = sizeof(CustomObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT,
@@ -161,7 +161,7 @@ you will need to OR the corresponding flags.
 
 We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
 
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
 
 To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
 handler. This is the equivalent of the Python method :meth:`__new__`, but

Doc/includes/custom.c

@@ -9,7 +9,7 @@ typedef struct{
 static PyTypeObject CustomType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "custom.Custom",
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
  .tp_basicsize = sizeof(CustomObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT,

Doc/includes/custom2.c

@@ -98,7 +98,7 @@ static PyMethodDef Custom_methods[] ={
 static PyTypeObject CustomType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "custom2.Custom",
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
  .tp_basicsize = sizeof(CustomObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

Doc/includes/custom3.c

@@ -148,7 +148,7 @@ static PyMethodDef Custom_methods[] ={
 static PyTypeObject CustomType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "custom3.Custom",
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
  .tp_basicsize = sizeof(CustomObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

Doc/includes/custom4.c

@@ -160,7 +160,7 @@ static PyMethodDef Custom_methods[] ={
 static PyTypeObject CustomType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "custom4.Custom",
- .tp_doc = "Custom objects",
+ .tp_doc = PyDoc_STR("Custom objects"),
  .tp_basicsize = sizeof(CustomObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

Doc/includes/sublist.c

@@ -31,7 +31,7 @@ SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
 static PyTypeObject SubListType ={
  PyVarObject_HEAD_INIT(NULL, 0)
  .tp_name = "sublist.SubList",
- .tp_doc = "SubList objects",
+ .tp_doc = PyDoc_STR("SubList objects"),
  .tp_basicsize = sizeof(SubListObject),
  .tp_itemsize = 0,
  .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst

@@ -0,0 +1,10 @@
+Classes and functions that unconditionally declared their docstrings
+ignoring the `--without-doc-strings` compilation flag no longer do so.
+
+The classes affected are :class:`ctypes.UnionType`,
+:class:`pickle.PickleBuffer`, :class:`testcapi.RecursingInfinitelyError`,
+and :class:`types.GenericAlias`.
+
+The functions affected are 24 methods in :mod:`ctypes`.
+
+Patch by Oleg Iarygin.

Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst

@@ -0,0 +1,4 @@
+All docstrings in code snippets are now wrapped into :func:`PyDoc_STR` to
+follow the guideline of `PEP 7's Documentation Strings paragraph
+<https://www.python.org/dev/peps/pep-0007/#documentation-strings>`_. Patch
+by Oleg Iarygin.

Modules/_ctypes/_ctypes.c

@@ -187,7 +187,7 @@ static PyTypeObject DictRemover_Type ={
  0, /* tp_as_buffer */
 /* XXX should participate in GC? */
  Py_TPFLAGS_DEFAULT, /* tp_flags */
- "deletes a key from a dictionary",  /* tp_doc */
+PyDoc_STR("deletes a key from a dictionary"), /* tp_doc */
  0, /* tp_traverse */
  0, /* tp_clear */
  0, /* tp_richcompare */
@@ -570,8 +570,8 @@ UnionType_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
  return StructUnionType_new(type, args, kwds, 0);
 }
 
-static const char from_address_doc[] =
-"C.from_address(integer) -> C instance\naccess a C instance at the specified address"
+PyDoc_STRVAR(from_address_doc,
+"C.from_address(integer) -> C instance\naccess a C instance at the specified address");
 
 static PyObject *
 CDataType_from_address(PyObject *type, PyObject *value)
@@ -588,8 +588,8 @@ CDataType_from_address(PyObject *type, PyObject *value)
  return PyCData_AtAddress(type, buf);
 }
 
-static const char from_buffer_doc[] =
-"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer"
+PyDoc_STRVAR(from_buffer_doc,
+"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer");
 
 static int
 KeepRef(CDataObject *target, Py_ssize_t index, PyObject *keep);
@@ -668,8 +668,8 @@ CDataType_from_buffer(PyObject *type, PyObject *args)
  return result;
 }
 
-static const char from_buffer_copy_doc[] =
-"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer"
+PyDoc_STRVAR(from_buffer_copy_doc,
+"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer");
 
 static PyObject *
 GenericPyCData_new(PyTypeObject *type, PyObject *args, PyObject *kwds);
@@ -719,8 +719,8 @@ CDataType_from_buffer_copy(PyObject *type, PyObject *args)
  return result;
 }
 
-static const char in_dll_doc[] =
-"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll"
+PyDoc_STRVAR(in_dll_doc,
+"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll");
 
 static PyObject *
 CDataType_in_dll(PyObject *type, PyObject *args)
@@ -781,8 +781,8 @@ CDataType_in_dll(PyObject *type, PyObject *args)
  return PyCData_AtAddress(type, address);
 }
 
-static const char from_param_doc[] =
-"Convert a Python object into a function call parameter."
+PyDoc_STRVAR(from_param_doc,
+"Convert a Python object into a function call parameter.");
 
 static PyObject *
 CDataType_from_param(PyObject *type, PyObject *value)
@@ -936,7 +936,7 @@ PyTypeObject PyCStructType_Type ={
  PyCStructType_setattro, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "metatype for the CData Objects",  /* tp_doc */
+PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
  (traverseproc)CDataType_traverse, /* tp_traverse */
  (inquiry)CDataType_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -978,7 +978,7 @@ static PyTypeObject UnionType_Type ={
  UnionType_setattro, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "metatype for the CData Objects",  /* tp_doc */
+PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
  (traverseproc)CDataType_traverse, /* tp_traverse */
  (inquiry)CDataType_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -1236,7 +1236,7 @@ PyTypeObject PyCPointerType_Type ={
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "metatype for the Pointer Objects",  /* tp_doc */
+PyDoc_STR("metatype for the Pointer Objects"), /* tp_doc */
  (traverseproc)CDataType_traverse, /* tp_traverse */
  (inquiry)CDataType_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -1648,7 +1648,7 @@ PyTypeObject PyCArrayType_Type ={
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "metatype for the Array Objects",  /* tp_doc */
+PyDoc_STR("metatype for the Array Objects"), /* tp_doc */
  0, /* tp_traverse */
  0, /* tp_clear */
  0, /* tp_richcompare */
@@ -2342,7 +2342,7 @@ PyTypeObject PyCSimpleType_Type ={
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "metatype for the PyCSimpleType Objects",  /* tp_doc */
+PyDoc_STR("metatype for the PyCSimpleType Objects"), /* tp_doc */
  0, /* tp_traverse */
  0, /* tp_clear */
  0, /* tp_richcompare */
@@ -2624,7 +2624,7 @@ PyTypeObject PyCFuncPtrType_Type ={
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "metatype for C function pointers",  /* tp_doc */
+PyDoc_STR("metatype for C function pointers"), /* tp_doc */
  (traverseproc)CDataType_traverse, /* tp_traverse */
  (inquiry)CDataType_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -2929,7 +2929,7 @@ PyTypeObject PyCData_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "XXX to be provided",  /* tp_doc */
+PyDoc_STR("XXX to be provided"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -4327,7 +4327,7 @@ PyTypeObject PyCFuncPtr_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "Function Pointer",  /* tp_doc */
+PyDoc_STR("Function Pointer"), /* tp_doc */
  (traverseproc)PyCFuncPtr_traverse, /* tp_traverse */
  (inquiry)PyCFuncPtr_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -4479,7 +4479,7 @@ static PyTypeObject Struct_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "Structure base class",  /* tp_doc */
+PyDoc_STR("Structure base class"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -4521,7 +4521,7 @@ static PyTypeObject Union_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "Union base class",  /* tp_doc */
+PyDoc_STR("Union base class"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -4841,7 +4841,7 @@ PyTypeObject PyCArray_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "XXX to be provided",  /* tp_doc */
+PyDoc_STR("XXX to be provided"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -5060,7 +5060,7 @@ static PyTypeObject Simple_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "XXX to be provided",  /* tp_doc */
+PyDoc_STR("XXX to be provided"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -5442,7 +5442,7 @@ PyTypeObject PyCPointer_Type ={
  0, /* tp_setattro */
  &PyCData_as_buffer, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
- "XXX to be provided",  /* tp_doc */
+PyDoc_STR("XXX to be provided"), /* tp_doc */
  (traverseproc)PyCData_traverse, /* tp_traverse */
  (inquiry)PyCData_clear, /* tp_clear */
  0, /* tp_richcompare */
@@ -5469,12 +5469,12 @@ PyTypeObject PyCPointer_Type ={
  * Module initialization.
  */
 
-static const char module_docs[] =
-"Create and manipulate C compatible data types in Python."
+PyDoc_STRVAR(_ctypes__doc__,
+"Create and manipulate C compatible data types in Python.");
 
 #ifdef MS_WIN32
 
-static const char comerror_doc[] = "Raised when a COM method call failed."
+PyDoc_STRVAR(comerror_doc, "Raised when a COM method call failed.");
 
 int
 comerror_init(PyObject *self, PyObject *args, PyObject *kwds)
@@ -5663,7 +5663,7 @@ wstring_at(const wchar_t *ptr, int size)
 static struct PyModuleDef _ctypesmodule ={
  PyModuleDef_HEAD_INIT,
  .m_name = "_ctypes",
- .m_doc = module_docs,
+ .m_doc = _ctypes__doc__,
  .m_size = -1,
  .m_methods = _ctypes_module_methods,
 };

Modules/_ctypes/callbacks.c

@@ -65,7 +65,7 @@ PyTypeObject PyCThunk_Type ={
  0, /* tp_setattro */
  0, /* tp_as_buffer */
  Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "CThunkObject",  /* tp_doc */
+PyDoc_STR("CThunkObject"), /* tp_doc */
  CThunkObject_traverse, /* tp_traverse */
  CThunkObject_clear, /* tp_clear */
  0, /* tp_richcompare */