From d6db6cae374ce262f209f6c9869b8d1d21ac37e6 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 17:05:17 +0300 Subject: [PATCH 01/12] Fix inlined docstrings without PyDoc_STR --- Doc/includes/sublist.c | 2 +- Modules/_ctypes/_ctypes.c | 6 +++--- Objects/genericaliasobject.c | 10 ++++++---- Objects/picklebufobject.c | 2 +- Objects/unionobject.c | 4 ++-- 5 files changed, 13 insertions(+), 11 deletions(-) diff --git a/Doc/includes/sublist.c b/Doc/includes/sublist.c index b2c26e73ebaf7e..b36dadf07eae87 100644 --- a/Doc/includes/sublist.c +++ b/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, diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index 481de85fde3adb..64f965953d8d80 100644 --- a/Modules/_ctypes/_ctypes.c +++ b/Modules/_ctypes/_ctypes.c @@ -5485,8 +5485,8 @@ 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 @@ -5679,7 +5679,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, }; diff --git a/Objects/genericaliasobject.c b/Objects/genericaliasobject.c index b41644910f5d25..4b2cc6cb3bd4e5 100644 --- a/Objects/genericaliasobject.c +++ b/Objects/genericaliasobject.c @@ -344,6 +344,11 @@ _Py_subs_parameters(PyObject *self, PyObject *args, PyObject *parameters, PyObje return newargs; } +PyDoc_STRVAR(genericalias__doc__, +"Represent a PEP 585 generic type\n" +"\n" +"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,)."); + static PyObject * ga_getitem(PyObject *self, PyObject *item) { @@ -623,14 +628,11 @@ static PyNumberMethods ga_as_number = { // TODO: // - argument clinic? -// - __doc__? // - cache? PyTypeObject Py_GenericAliasType = { PyVarObject_HEAD_INIT(&PyType_Type, 0) .tp_name = "types.GenericAlias", - .tp_doc = "Represent a PEP 585 generic type\n" - "\n" - "E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).", + .tp_doc = genericalias__doc__, .tp_basicsize = sizeof(gaobject), .tp_dealloc = ga_dealloc, .tp_repr = ga_repr, diff --git a/Objects/picklebufobject.c b/Objects/picklebufobject.c index a135e5575e28c5..aaa852cfbb05b0 100644 --- a/Objects/picklebufobject.c +++ b/Objects/picklebufobject.c @@ -206,7 +206,7 @@ static PyMethodDef picklebuf_methods[] = { PyTypeObject PyPickleBuffer_Type = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "pickle.PickleBuffer", - .tp_doc = "Wrapper for potentially out-of-band buffers", + .tp_doc = PyDoc_STR("Wrapper for potentially out-of-band buffers"), .tp_basicsize = sizeof(PyPickleBufferObject), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, .tp_new = picklebuf_new, diff --git a/Objects/unionobject.c b/Objects/unionobject.c index 72a0a3f2cf8d22..5432c6faa3f909 100644 --- a/Objects/unionobject.c +++ b/Objects/unionobject.c @@ -443,9 +443,9 @@ union_getattro(PyObject *self, PyObject *name) PyTypeObject _PyUnion_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) .tp_name = "types.UnionType", - .tp_doc = "Represent a PEP 604 union type\n" + .tp_doc = PyDoc_STR("Represent a PEP 604 union type\n" "\n" - "E.g. for int | str", + "E.g. for int | str"), .tp_basicsize = sizeof(unionobject), .tp_dealloc = unionobject_dealloc, .tp_alloc = PyType_GenericAlloc, From 4a4f01816dddc14ec6b3731bcdecb690e1589383 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 21:11:35 +0300 Subject: [PATCH 02/12] Fix sample docstrings to show good PEP 7 practice --- Doc/c-api/typeobj.rst | 6 +++--- Doc/extending/newtypes_tutorial.rst | 4 ++-- Doc/includes/custom.c | 2 +- Doc/includes/custom2.c | 2 +- Doc/includes/custom3.c | 2 +- Doc/includes/custom4.c | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4a54139c5d498b..4542221070438e 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2597,7 +2597,7 @@ A basic :ref:`static type `:: 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, @@ -2660,7 +2660,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, @@ -2688,7 +2688,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, }; diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst index 530e2c4d35f848..7f2cb53c07100f 100644 --- a/Doc/extending/newtypes_tutorial.rst +++ b/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 diff --git a/Doc/includes/custom.c b/Doc/includes/custom.c index f361baf830dd1b..26ca754964733d 100644 --- a/Doc/includes/custom.c +++ b/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, diff --git a/Doc/includes/custom2.c b/Doc/includes/custom2.c index 5bacab7a2a9714..2a3c59f8f04c3d 100644 --- a/Doc/includes/custom2.c +++ b/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, diff --git a/Doc/includes/custom3.c b/Doc/includes/custom3.c index 2b7a99ecf96c76..5a47530f0a6b0d 100644 --- a/Doc/includes/custom3.c +++ b/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, diff --git a/Doc/includes/custom4.c b/Doc/includes/custom4.c index 584992fc5f1a8a..c7ee55578488ed 100644 --- a/Doc/includes/custom4.c +++ b/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, From 1a8760456f2a9b41003aa1d6e8f06d73f3830a0f Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 21:21:23 +0300 Subject: [PATCH 03/12] Fix non-inlined docstrings without PyDoc_STRVAR --- Modules/_ctypes/_ctypes.c | 22 +++++++++++----------- Modules/_ctypes/callproc.c | 32 ++++++++++++++++---------------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index 64f965953d8d80..d38dc3dd02c80b 100644 --- a/Modules/_ctypes/_ctypes.c +++ b/Modules/_ctypes/_ctypes.c @@ -579,8 +579,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) @@ -597,8 +597,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); @@ -677,8 +677,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); @@ -728,8 +728,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) @@ -790,8 +790,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) @@ -5490,7 +5490,7 @@ PyDoc_STRVAR(_ctypes__doc__, #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) diff --git a/Modules/_ctypes/callproc.c b/Modules/_ctypes/callproc.c index 4a6b8ec3ee016f..ae11be75021a8a 100644 --- a/Modules/_ctypes/callproc.c +++ b/Modules/_ctypes/callproc.c @@ -1302,11 +1302,11 @@ _parse_voidp(PyObject *obj, void **address) #ifdef MS_WIN32 -static const char format_error_doc[] = +PyDoc_STRVAR(format_error_doc, "FormatError([integer]) -> string\n\ \n\ Convert a win32 error code into a string. If the error code is not\n\ -given, the return value of a call to GetLastError() is used.\n"; +given, the return value of a call to GetLastError() is used.\n"); static PyObject *format_error(PyObject *self, PyObject *args) { PyObject *result; @@ -1326,13 +1326,13 @@ static PyObject *format_error(PyObject *self, PyObject *args) return result; } -static const char load_library_doc[] = +PyDoc_STRVAR(load_library_doc, "LoadLibrary(name, load_flags) -> handle\n\ \n\ Load an executable (usually a DLL), and return a handle to it.\n\ The handle may be used to locate exported functions in this\n\ module. load_flags are as defined for LoadLibraryEx in the\n\ -Windows API.\n"; +Windows API.\n"); static PyObject *load_library(PyObject *self, PyObject *args) { PyObject *nameobj; @@ -1377,10 +1377,10 @@ static PyObject *load_library(PyObject *self, PyObject *args) #endif } -static const char free_library_doc[] = +PyDoc_STRVAR(free_library_doc, "FreeLibrary(handle) -> void\n\ \n\ -Free the handle of an executable previously loaded by LoadLibrary.\n"; +Free the handle of an executable previously loaded by LoadLibrary.\n"); static PyObject *free_library(PyObject *self, PyObject *args) { void *hMod; @@ -1400,8 +1400,8 @@ static PyObject *free_library(PyObject *self, PyObject *args) Py_RETURN_NONE; } -static const char copy_com_pointer_doc[] = -"CopyComPointer(src, dst) -> HRESULT value\n"; +PyDoc_STRVAR(copy_com_pointer_doc, +"CopyComPointer(src, dst) -> HRESULT value\n"); static PyObject * copy_com_pointer(PyObject *self, PyObject *args) @@ -1639,10 +1639,10 @@ call_cdeclfunction(PyObject *self, PyObject *args) /***************************************************************** * functions */ -static const char sizeof_doc[] = +PyDoc_STRVAR(sizeof_doc, "sizeof(C type) -> integer\n" "sizeof(C instance) -> integer\n" -"Return the size in bytes of a C instance"; +"Return the size in bytes of a C instance"); static PyObject * sizeof_func(PyObject *self, PyObject *obj) @@ -1660,10 +1660,10 @@ sizeof_func(PyObject *self, PyObject *obj) return NULL; } -static const char alignment_doc[] = +PyDoc_STRVAR(alignment_doc[] = "alignment(C type) -> integer\n" "alignment(C instance) -> integer\n" -"Return the alignment requirements of a C instance"; +"Return the alignment requirements of a C instance"); static PyObject * align_func(PyObject *self, PyObject *obj) @@ -1683,10 +1683,10 @@ align_func(PyObject *self, PyObject *obj) return NULL; } -static const char byref_doc[] = +PyDoc_STRVAR(byref_doc, "byref(C instance[, offset=0]) -> byref-object\n" "Return a pointer lookalike to a C instance, only usable\n" -"as function argument"; +"as function argument"); /* * We must return something which can be converted to a parameter, @@ -1727,9 +1727,9 @@ byref(PyObject *self, PyObject *args) return (PyObject *)parg; } -static const char addressof_doc[] = +PyDoc_STRVAR(addressof_doc, "addressof(C instance) -> integer\n" -"Return the address of the C instance internal buffer"; +"Return the address of the C instance internal buffer"); static PyObject * addressof(PyObject *self, PyObject *obj) From 745c8876cfdb92df4b37ee81666ab32425776986 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 22:12:06 +0300 Subject: [PATCH 04/12] Add NEWS entries --- .../2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 15 +++++++++++++++ .../2022-03-08-22-10-38.bpo-46962.FIVe9I.rst | 4 ++++ 2 files changed, 19 insertions(+) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst create mode 100644 Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst new file mode 100644 index 00000000000000..0833de54a19b30 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -0,0 +1,15 @@ +Classes and functions that unconditionally declared their docstrings +ignoring --without-doc-strings compilation no longer do so. + +The classes affected are :class:`~ctypes.UnionType`, +:class:`~pickle.PickleBuffer`, and :class:`~types.GenericAlias`. + +The functions affected are :func:`ctypes.addressof`, +:func:`ctypes.alignment`, :func:`ctypes.byref`, +:func:`ctypes.CopyComPointer`, :func:`ctypes.FormatError`, +:func:`ctypes.FreeLibrary`, :func:`ctypes.LoadLibrary`, and +:func:`ctypes.sizeof`, along with a bunch of methods in +:class:`~_ctypes.PyCPointerType:, :class:`~_ctypes.PyCSimpleType:, and +:class:`~_ctypes.PyCStructType:. + +Patch by Oleg Iarygin. diff --git a/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst b/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst new file mode 100644 index 00000000000000..f65abd1474caac --- /dev/null +++ b/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 +not teach programmers violation of `PEP 7's Documentation Strings paragraph +`_. Patch +by Oleg Iarygin. From b04a23434f34132662106dd1c96e638fb7189869 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 22:14:58 +0300 Subject: [PATCH 05/12] Fix a typo --- Modules/_ctypes/callproc.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_ctypes/callproc.c b/Modules/_ctypes/callproc.c index ae11be75021a8a..c49ec23d1d0412 100644 --- a/Modules/_ctypes/callproc.c +++ b/Modules/_ctypes/callproc.c @@ -1660,7 +1660,7 @@ sizeof_func(PyObject *self, PyObject *obj) return NULL; } -PyDoc_STRVAR(alignment_doc[] = +PyDoc_STRVAR(alignment_doc "alignment(C type) -> integer\n" "alignment(C instance) -> integer\n" "Return the alignment requirements of a C instance"); From a9c6225fcddc90fdeac3603759fa7ae0a792a3cb Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 22:18:04 +0300 Subject: [PATCH 06/12] Clarify a NEWS entry for Core and Builtins --- .../Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst index 0833de54a19b30..2f5343e90bc04e 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -1,5 +1,5 @@ Classes and functions that unconditionally declared their docstrings -ignoring --without-doc-strings compilation no longer do so. +ignoring --without-doc-strings compilation flag no longer do so. The classes affected are :class:`~ctypes.UnionType`, :class:`~pickle.PickleBuffer`, and :class:`~types.GenericAlias`. From cf019f6e270ca91479e9f555c00bb130cda02553 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 22:22:11 +0300 Subject: [PATCH 07/12] Fix a typo 2 --- Modules/_ctypes/callproc.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_ctypes/callproc.c b/Modules/_ctypes/callproc.c index c49ec23d1d0412..f1199ef67d5360 100644 --- a/Modules/_ctypes/callproc.c +++ b/Modules/_ctypes/callproc.c @@ -1660,7 +1660,7 @@ sizeof_func(PyObject *self, PyObject *obj) return NULL; } -PyDoc_STRVAR(alignment_doc +PyDoc_STRVAR(alignment_doc, "alignment(C type) -> integer\n" "alignment(C instance) -> integer\n" "Return the alignment requirements of a C instance"); From e5d5613279ce19a8b444259d574f8d9b07c6fb2c Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Tue, 8 Mar 2022 22:27:54 +0300 Subject: [PATCH 08/12] The module is called ctypes, not _ctypes --- .../2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst index 2f5343e90bc04e..aa5ac74cfff2c8 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -9,7 +9,7 @@ The functions affected are :func:`ctypes.addressof`, :func:`ctypes.CopyComPointer`, :func:`ctypes.FormatError`, :func:`ctypes.FreeLibrary`, :func:`ctypes.LoadLibrary`, and :func:`ctypes.sizeof`, along with a bunch of methods in -:class:`~_ctypes.PyCPointerType:, :class:`~_ctypes.PyCSimpleType:, and -:class:`~_ctypes.PyCStructType:. +:class:`~ctypes.PyCPointerType`, :class:`~ctypes.PyCSimpleType`, and +:class:`~ctypes.PyCStructType`. Patch by Oleg Iarygin. From 62da0700bf757dce3b08c13754ab64d632311dc4 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 9 Mar 2022 09:39:26 +0300 Subject: [PATCH 09/12] Address a review --- Doc/c-api/typeobj.rst | 2 +- .../2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 11 ++------ Modules/_ctypes/_ctypes.c | 28 +++++++++---------- Modules/_ctypes/callbacks.c | 2 +- Modules/_ctypes/cfield.c | 2 +- Modules/_testcapimodule.c | 2 +- 6 files changed, 21 insertions(+), 26 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4542221070438e..ed434d8fd44fb2 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2627,7 +2627,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 */ diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst index aa5ac74cfff2c8..47b595b7055ae1 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -2,14 +2,9 @@ Classes and functions that unconditionally declared their docstrings ignoring --without-doc-strings compilation flag no longer do so. The classes affected are :class:`~ctypes.UnionType`, -:class:`~pickle.PickleBuffer`, and :class:`~types.GenericAlias`. +:class:`~pickle.PickleBuffer`, :class:`~testcapi.RecursingInfinitelyError`, +and :class:`~types.GenericAlias`. -The functions affected are :func:`ctypes.addressof`, -:func:`ctypes.alignment`, :func:`ctypes.byref`, -:func:`ctypes.CopyComPointer`, :func:`ctypes.FormatError`, -:func:`ctypes.FreeLibrary`, :func:`ctypes.LoadLibrary`, and -:func:`ctypes.sizeof`, along with a bunch of methods in -:class:`~ctypes.PyCPointerType`, :class:`~ctypes.PyCSimpleType`, and -:class:`~ctypes.PyCStructType`. +The functions affected are 24 methods of :mod:`ctypes`'s classes. Patch by Oleg Iarygin. diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index d38dc3dd02c80b..5e89a91932e436 100644 --- a/Modules/_ctypes/_ctypes.c +++ b/Modules/_ctypes/_ctypes.c @@ -196,7 +196,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 */ @@ -945,7 +945,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 */ @@ -987,7 +987,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 */ @@ -1245,7 +1245,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 */ @@ -1657,7 +1657,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 */ @@ -2351,7 +2351,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 */ @@ -2640,7 +2640,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 */ @@ -2945,7 +2945,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 */ @@ -4343,7 +4343,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 */ @@ -4495,7 +4495,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 */ @@ -4537,7 +4537,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 */ @@ -4857,7 +4857,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 */ @@ -5076,7 +5076,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 */ @@ -5458,7 +5458,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 */ diff --git a/Modules/_ctypes/callbacks.c b/Modules/_ctypes/callbacks.c index bb59456a7321a2..9eb320898160b7 100644 --- a/Modules/_ctypes/callbacks.c +++ b/Modules/_ctypes/callbacks.c @@ -82,7 +82,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 */ diff --git a/Modules/_ctypes/cfield.c b/Modules/_ctypes/cfield.c index 2992d34934194e..41b24e6bba64f8 100644 --- a/Modules/_ctypes/cfield.c +++ b/Modules/_ctypes/cfield.c @@ -326,7 +326,7 @@ PyTypeObject PyCField_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "Structure/Union member", /* tp_doc */ + PyDoc_STR("Structure/Union member"), /* tp_doc */ (traverseproc)PyCField_traverse, /* tp_traverse */ (inquiry)PyCField_clear, /* tp_clear */ 0, /* tp_richcompare */ diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c index 6fa0cced4ecfb9..293925cf62e43d 100644 --- a/Modules/_testcapimodule.c +++ b/Modules/_testcapimodule.c @@ -6447,7 +6447,7 @@ static PyTypeObject PyRecursingInfinitelyError_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "Instantiating this exception starts infinite recursion.", /* tp_doc */ + PyDoc_STR("Instantiating this exception starts infinite recursion."), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ From 87ebe0ed52171401dee47880f51eec33903fc549 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Sat, 12 Mar 2022 23:24:59 +0300 Subject: [PATCH 10/12] Update Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric --- .../next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst b/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst index f65abd1474caac..f5b54013bd6720 100644 --- a/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst +++ b/Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst @@ -1,4 +1,4 @@ All docstrings in code snippets are now wrapped into :func:`PyDoc_STR` to -not teach programmers violation of `PEP 7's Documentation Strings paragraph +follow the guideline of `PEP 7's Documentation Strings paragraph `_. Patch by Oleg Iarygin. From a4a94bef969c844ca7b5275ea2f721eca0f01ddb Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Sat, 12 Mar 2022 23:27:15 +0300 Subject: [PATCH 11/12] Address a review --- .../2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst index 47b595b7055ae1..669ccfdaaacf98 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -1,9 +1,9 @@ Classes and functions that unconditionally declared their docstrings ignoring --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 classes affected are :class:`ctypes.UnionType`, +:class:`pickle.PickleBuffer`, :class:`testcapi.RecursingInfinitelyError`, +and :class:`types.GenericAlias`. The functions affected are 24 methods of :mod:`ctypes`'s classes. From c4a5025360a707a8aeaaf0ea2e776f2ffc0fe9ff Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 17 Apr 2022 13:39:46 -0700 Subject: [PATCH 12/12] Wordsmith the NEWS entry --- .../2022-03-08-21-59-57.bpo-46962.UomDfz.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst index 669ccfdaaacf98..395c9b3d8f5260 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst @@ -1,10 +1,10 @@ Classes and functions that unconditionally declared their docstrings -ignoring --without-doc-strings compilation flag no longer do so. +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 of :mod:`ctypes`'s classes. +The functions affected are 24 methods in :mod:`ctypes`. Patch by Oleg Iarygin.