From 27a7fe319a46bb3e36f27a9efeaf061f2379dcd8 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 10:49:29 -0700 Subject: [PATCH] [3.11] gh-93738: Disallow pre-v3 syntax in the C domain (GH-97962) (#97976) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also, disable using invalid sphinx-lint 0.6.2. (cherry picked from commit f612565bd32d4ab0945798da775eea070f08b6fe) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Łukasz Langa --- Doc/c-api/unicode.rst | 12 ++++++------ Doc/conf.py | 25 ------------------------- Doc/extending/newtypes.rst | 8 ++++---- Doc/extending/newtypes_tutorial.rst | 2 +- Doc/howto/isolating-extensions.rst | 2 +- Doc/requirements.txt | 5 ++++- Doc/whatsnew/2.2.rst | 2 +- Doc/whatsnew/2.5.rst | 2 +- 8 files changed, 18 insertions(+), 40 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 26d34052972ad4..e72f151510cbde 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -17,8 +17,8 @@ of Unicode characters while staying memory efficient. There are special cases for strings where all code points are below 128, 256, or 65536; otherwise, code points must be below 1114112 (which is the full Unicode range). -:c:type:`Py_UNICODE*` and UTF-8 representations are created on demand and cached -in the Unicode object. The :c:type:`Py_UNICODE*` representation is deprecated +:c:expr:`Py_UNICODE*` and UTF-8 representations are created on demand and cached +in the Unicode object. The :c:expr:`Py_UNICODE*` representation is deprecated and inefficient. Due to the transition between the old APIs and the new APIs, Unicode objects @@ -30,7 +30,7 @@ can internally be in two states depending on how they were created: * "legacy" Unicode objects have been created through one of the deprecated APIs (typically :c:func:`PyUnicode_FromUnicode`) and only bear the - :c:type:`Py_UNICODE*` representation; you will have to call + :c:expr:`Py_UNICODE*` representation; you will have to call :c:func:`PyUnicode_READY` on them before calling any other API. .. note:: @@ -236,7 +236,7 @@ access to internal read-only data of Unicode objects: returned buffer is always terminated with an extra null code point. It may also contain embedded null code points, which would cause the string to be truncated when used in most C functions. The ``AS_DATA`` form - casts the pointer to :c:type:`const char *`. The *o* argument has to be + casts the pointer to :c:expr:`const char *`. The *o* argument has to be a Unicode object (not checked). .. versionchanged:: 3.3 @@ -714,7 +714,7 @@ Extension modules can continue using them, as they will not be removed in Python Return a read-only pointer to the Unicode object's internal :c:type:`Py_UNICODE` buffer, or ``NULL`` on error. This will create the - :c:type:`Py_UNICODE*` representation of the object if it is not yet + :c:expr:`Py_UNICODE*` representation of the object if it is not yet available. The buffer is always terminated with an extra null code point. Note that the resulting :c:type:`Py_UNICODE` string may also contain embedded null code points, which would cause the string to be truncated when @@ -730,7 +730,7 @@ Extension modules can continue using them, as they will not be removed in Python Like :c:func:`PyUnicode_AsUnicode`, but also saves the :c:func:`Py_UNICODE` array length (excluding the extra null terminator) in *size*. - Note that the resulting :c:type:`Py_UNICODE*` string + Note that the resulting :c:expr:`Py_UNICODE*` string may contain embedded null code points, which would cause the string to be truncated when used in most C functions. diff --git a/Doc/conf.py b/Doc/conf.py index e5c989da0b360d..fd4ee2d5eee811 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -234,28 +234,3 @@ # Relative filename of the data files refcount_file = 'data/refcounts.dat' stable_abi_file = 'data/stable_abi.dat' - -# Sphinx 2 and Sphinx 3 compatibility -# ----------------------------------- - -# bpo-40204: Allow Sphinx 2 syntax in the C domain -c_allow_pre_v3 = True - -# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the -# documentation is built with -W (warnings treated as errors). -c_warn_on_allowed_pre_v3 = False - -# Fix '!' not working with C domain when pre_v3 is enabled -import sphinx - -if sphinx.version_info[:2] < (5, 3): - from sphinx.domains.c import CXRefRole - - original_run = CXRefRole.run - - def new_run(self): - if self.disabled: - return super(CXRefRole, self).run() - return original_run(self) - - CXRefRole.run = new_run diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 1eef7f6e8eb9fb..5ba6383640cc73 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -208,7 +208,7 @@ a special case, for which the new value passed to the handler is ``NULL``. Python supports two pairs of attribute handlers; a type that supports attributes only needs to implement the functions for one pair. The difference is that one pair takes the name of the attribute as a :c:expr:`char\*`, while the other -accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more +accepts a :c:expr:`PyObject*`. Each type can use whichever pair makes more sense for the implementation's convenience. :: getattrfunc tp_getattr; /* char * version */ @@ -219,7 +219,7 @@ sense for the implementation's convenience. :: If accessing attributes of an object is always a simple operation (this will be explained shortly), there are generic implementations which can be used to -provide the :c:type:`PyObject\*` version of the attribute management functions. +provide the :c:expr:`PyObject*` version of the attribute management functions. The actual need for type-specific attribute handlers almost completely disappeared starting with Python 2.2, though there are many examples which have not been updated to use some of the new generic mechanism that is available. @@ -341,7 +341,7 @@ Type-specific Attribute Management For simplicity, only the :c:expr:`char\*` version will be demonstrated here; the type of the name parameter is the only difference between the :c:expr:`char\*` -and :c:type:`PyObject\*` flavors of the interface. This example effectively does +and :c:expr:`PyObject*` flavors of the interface. This example effectively does the same thing as the generic example above, but does not use the generic support added in Python 2.2. It explains how the handler functions are called, so that if you do need to extend their functionality, you'll understand @@ -572,7 +572,7 @@ performance-critical objects (such as numbers). For an object to be weakly referencable, the extension type must do two things: -#. Include a :c:type:`PyObject\*` field in the C object structure dedicated to +#. Include a :c:expr:`PyObject*` field in the C object structure dedicated to the weak reference mechanism. The object's constructor should leave it ``NULL`` (which is automatic when using the default :c:member:`~PyTypeObject.tp_alloc`). diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst index 34c25d1f6f199c..5d4a3f06dd5402 100644 --- a/Doc/extending/newtypes_tutorial.rst +++ b/Doc/extending/newtypes_tutorial.rst @@ -24,7 +24,7 @@ The Basics ========== The :term:`CPython` runtime sees all Python objects as variables of type -:c:type:`PyObject\*`, which serves as a "base type" for all Python objects. +:c:expr:`PyObject*`, which serves as a "base type" for all Python objects. The :c:type:`PyObject` structure itself only contains the object's :term:`reference count` and a pointer to the object's "type object". This is where the action is; the type object determines which (C) functions diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst index 8ee7e5e28479a5..2657b4ec6aaf9f 100644 --- a/Doc/howto/isolating-extensions.rst +++ b/Doc/howto/isolating-extensions.rst @@ -411,7 +411,7 @@ that subclass, which may be defined in different module than yours. pass For a method to get its "defining class", it must use the -:c:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS` +:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS` :c:type:`calling convention ` and the corresponding :c:type:`PyCMethod` signature:: diff --git a/Doc/requirements.txt b/Doc/requirements.txt index f8a7f9db144c21..be058733fcf4d7 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -7,7 +7,10 @@ sphinx==4.5.0 blurb -sphinx-lint<1 +# sphinx-lint 0.6.2 yields many default role errors due to the new regular +# expression used for default role detection, so we don't use the version +# until the errors are fixed. +sphinx-lint<1,!=0.6.2 # The theme used by the documentation is stored separately, so we need # to install that as well. diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index bfb2aacbc07747..39997661bb96c4 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -1102,7 +1102,7 @@ code, none of the changes described here will affect you very much. * A different argument parsing function, :c:func:`PyArg_UnpackTuple`, has been added that's simpler and presumably faster. Instead of specifying a format string, the caller simply gives the minimum and maximum number of arguments - expected, and a set of pointers to :c:type:`PyObject\*` variables that will be + expected, and a set of pointers to :c:expr:`PyObject*` variables that will be filled in with argument values. * Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 0aca2fe697ccdb..dcfaef6ed29494 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1725,7 +1725,7 @@ attribute of the function object to change this:: ``ctypes.pythonapi`` object. This object does *not* release the global interpreter lock before calling a function, because the lock must be held when calling into the interpreter's code. There's a :class:`py_object()` type -constructor that will create a :c:type:`PyObject \*` pointer. A simple usage:: +constructor that will create a :c:expr:`PyObject *` pointer. A simple usage:: import ctypes