8000 [3.11] gh-107298: Fix more Sphinx warnings in the C API doc (GH-10732… · python/cpython@32e17d4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 32e17d4

Browse files
serhiy-storchakavstinner
serhiy-storchaka
and
vstinner
authored
[3.11] gh-107298: Fix more Sphinx warnings in the C API doc (GH-107329) (GH-107377)
Declare the following functions as macros, since they are actually macros. It avoids a warning on "TYPE" or "macro" argument. * PyMem_New() * PyMem_Resize() * PyModule_AddIntMacro() * PyModule_AddStringMacro() * PyObject_GC_New() * PyObject_GC_NewVar() * PyObject_New() * PyObject_NewVar() (cherry picked from commit 8d61a71) Co-authored-by: Victor Stinner <vstinner@python.org>
1 parent dcfdfa5 commit 32e17d4

22 files changed

+119
-113
lines changed

‎Doc/c-api/allocation.rst

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,31 +27,34 @@ Allocating Objects on the Heap
2727
length information for a variable-size object.
2828
2929
30-
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
30+
.. c:macro:: PyObject_New(TYPE, typeobj)
3131
3232
Allocate a new Python object using the C structure type *TYPE* and the
33-
Python type object *type*. Fields not defined by the Python object header
33+
Python type object *typeobj* (``PyTypeObject*``).
34+
Fields not defined by the Python object header
3435
are not initialized; the object's reference count will be one. The size of
3536
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
3637
the type object.
3738
3839
39-
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
40+
.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
4041
4142
Allocate a new Python object using the C structure type *TYPE* and the
42-
Python type object *type*. Fields not defined by the Python object header
43+
Python type object *typeobj* (``PyTypeObject*``).
44+
Fields not defined by the Python object header
4345
are not initialized. The allocated memory allows for the *TYPE* structure
44-
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
45-
*type*. This is useful for implementing objects like tuples, which are
46+
plus *size* (``Py_ssize_t``) fields of the size
47+
given by the :c:member:`~PyTypeObject.tp_itemsize` field of
48+
*typeobj*. This is useful for implementing objects like tuples, which are
4649
able to determine their size at construction time. Embedding the array of
4750
fields into the same allocation decreases the number of allocations,
4851
improving the memory management efficiency.
4952
5053
5154
.. c:function:: void PyObject_Del(void *op)
5255
53-
Releases memory allocated to an object using :c:func:`PyObject_New` or
54-
:c:func:`PyObject_NewVar`. This is normally called from the
56+
Releases memory allocated to an object using :c:macro:`PyObject_New` or
57+
:c:macro:`PyObject_NewVar`. This is normally called from the
5558
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
5659
the object should not be accessed after this call as the memory is no
5760
longer a valid Python object.

‎Doc/c-api/capsule.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
6464
6565
The *name* parameter must compare exactly to the name stored in the capsule.
6666
If the name stored in the capsule is ``NULL``, the *name* passed in must also
67-
be ``NULL``. Python uses the C function :c:func:`strcmp` to compare capsule
67+
be ``NULL``. Python uses the C function :c:func:`!strcmp` to compare capsule
6868
names.
6969
7070

‎Doc/c-api/complex.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ pointers. This is consistent throughout the API.
6464
representation.
6565
6666
If *divisor* is null, this method returns zero and sets
67-
:c:data:`errno` to :c:macro:`EDOM`.
67+
:c:data:`errno` to :c:macro:`!EDOM`.
6868
6969
7070
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers. This is consistent throughout the API.
7373
representation.
7474
7575
If *num* is null and *exp* is not a positive real number,
76-
this method returns zero and sets :c:data:`errno` to :c:macro:`EDOM`.
76+
this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
7777
7878
7979
Complex Numbers as Python Objects

‎Doc/c-api/conversion.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,10 +119,10 @@ The following functions provide locale-independent string to number conversions.
119119
.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
120120
121121
Case insensitive comparison of strings. The function works almost
122-
identically to :c:func:`strcmp` except that it ignores the case.
122+
identically to :c:func:`!strcmp` except that it ignores the case.
123123
124124
125125
.. c:function:: int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)
126126
127127
Case insensitive comparison of strings. The function works almost
128-
identically to :c:func:`strncmp` except that it ignores the case.
128+
identically to :c:func:`!strncmp` except that it ignores the case.

‎Doc/c-api/exceptions.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ Printing and clearing
7878
This utility function prints a warning message to ``sys.stderr`` when an
7979
exception has been set but it is impossible for the interpreter to actually
8080
raise the exception. It is used, for example, when an exception occurs in an
81-
:meth:`__del__` method.
81+
:meth:`~object.__del__` method.
8282
8383
The function is called with a single argument *obj* that identifies the context
8484
in which the unraisable exception occurred. If possible,
@@ -154,7 +154,7 @@ For convenience, some of these functions will always return a
154154
tuple object whose first item is the integer :c:data:`errno` value and whose
155155
second item is the corresponding error message (gotten from :c:func:`!strerror`),
156156
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
157-
:c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
157+
:c:data:`errno` value is :c:macro:`!EINTR`, indicating an interrupted system call,
158158
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
159159
leaves it set to that. The function always returns ``NULL``, so a wrapper
160160
function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -166,7 +166,7 @@ For convenience, some of these functions will always return a
166166
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
167167
*filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
168168
a third parameter. In the case of :exc:`OSError` exception,
169-
this is used to define the :attr:`filename` attribute of the
169+
this is used to define the :attr:`!filename` attribute of the
170170
exception instance.
171171
172172
@@ -189,12 +189,12 @@ For convenience, some of these functions will always return a
189189
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
190190
191191
This is a convenience function to raise :exc:`WindowsError`. If called with
192-
*ierr* of ``0``, the error code returned by a call to :c:func:`GetLastError`
193-
is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
194-
the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
192+
*ierr* of ``0``, the error code returned by a call to :c:func:`!GetLastError`
193+
is used instead. It calls the Win32 function :c:func:`!FormatMessage` to retrieve
194+
the Windows description of error code given by *ierr* or :c:func:`!GetLastError`,
195195
then it constructs a tuple object whose first item is the *ierr* value and whose
196196
second item is the corresponding error message (gotten from
197-
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
197+
:c:func:`!FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
198198
object)``. This function always returns ``NULL``.
199199
200200
.. availability:: Windows.
@@ -567,7 +567,7 @@ Signal Handling
567567
be interruptible by user requests (such as by pressing Ctrl-C).
568568
569569
.. note::
570-
The default Python signal handler for :c:macro:`SIGINT` raises the
570+
The default Python signal handler for :c:macro:`!SIGINT` raises the
571571
:exc:`KeyboardInterrupt` exception.
572572
573573
@@ -578,7 +578,7 @@ Signal Handling
578578
single: SIGINT
579579
single: KeyboardInterrupt (built-in exception)
580580
581-
Simulate the effect of a :c:macro:`SIGINT` signal arriving.
581+
Simulate the effect of a :c:macro:`!SIGINT` signal arriving.
582582
This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
583583
584584
.. note::

‎Doc/c-api/gcsupport.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
2525

2626
Constructors for container types must conform to two rules:
2727

28-
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
29-
or :c:func:`PyObject_GC_NewVar`.
28+
#. The memory for the object must be allocated using :c:macro:`PyObject_GC_New`
29+
or :c:macro:`PyObject_GC_NewVar`.
3030

3131
#. Once all the fields which may contain references to other containers are
3232
initialized, it must call :c:func:`PyObject_GC_Track`.
@@ -52,21 +52,21 @@ rules:
5252
class that implements the garbage collector protocol and the child class
5353
does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
5454

55-
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
55+
.. c:macro:: PyObject_GC_New(TYPE, typeobj)
5656
57-
Analogous to :c:func:`PyObject_New` but for container objects with the
57+
Analogous to :c:macro:`PyObject_New` but for container objects with the
5858
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
5959

6060

61-
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
61+
.. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
6262
63-
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
63+
Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
6464
:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
6565

6666

6767
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
6868
69-
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
69+
Resize an object allocated by :c:macro:`PyObject_NewVar`. Returns the
7070
resized object or ``NULL`` on failure. *op* must not be tracked by the collector yet.
7171
7272
@@ -109,8 +109,8 @@ rules:
109109
110110
.. c:function:: void PyObject_GC_Del(void *op)
111111
112-
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
113-
:c:func:`PyObject_GC_NewVar`.
112+
Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or
113+
:c:macro:`PyObject_GC_NewVar`.
114114
115115
116116
.. c:function:: void PyObject_GC_UnTrack(void *op)

‎Doc/c-api/import.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -135,10 +135,10 @@ Importing Modules
135135
The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
136136
not set already, with the appropriate values. The spec's loader will
137137
be set to the module's ``__loader__`` (if set) and to an instance of
138-
:class:`SourceFileLoader` otherwise.
138+
:class:`~importlib.machinery.SourceFileLoader` otherwise.
139139
140140
The module's :attr:`__file__` attribute will be set to the code object's
141-
:attr:`co_filename`. If applicable, :attr:`__cached__` will also
141+
:attr:`!co_filename`. If applicable, :attr:`__cached__` will also
142142
be set.
143143
144144
This function will reload the module if it was already imported. See
@@ -214,7 +214,7 @@ Importing Modules
214214
215215
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
216216
217-
Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item
217+
Return a finder object for a :data:`sys.path`/:attr:`!pkg.__path__` item
218218
*path*, possibly by fetching it from the :data:`sys.path_importer_cache`
219219
dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
220220
is found that can handle the path item. Return ``None`` if no hook could;

‎Doc/c-api/init.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ The following functions can be safely called before Python is initialized:
2525

2626
* :c:func:`PyImport_AppendInittab`
2727
* :c:func:`PyImport_ExtendInittab`
28-
* :c:func:`PyInitFrozenExtensions`
28+
* :c:func:`!PyInitFrozenExtensions`
2929
* :c:func:`PyMem_SetAllocator`
3030
* :c:func:`PyMem_SetupDebugHooks`
3131
* :c:func:`PyObject_SetArenaAllocator`
@@ -122,7 +122,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
122122

123123
.. c:var:: int Py_IgnoreEnvironmentFlag
124124
125-
Ignore all :envvar:`PYTHON*` environment variables, e.g.
125+
Ignore all :envvar:`!PYTHON*` environment variables, e.g.
126126
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
127127

128128
Set by the :option:`-E` and :option:`-I` options.
@@ -165,7 +165,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
165165
.. c:var:: int Py_LegacyWindowsStdioFlag
166166
167167
If the flag is non-zero, use :class:`io.FileIO` instead of
168-
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
168+
:class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.
169169

170170
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
171171
variable is set to a non-empty string.
@@ -292,7 +292,7 @@ Initializing and finalizing the interpreter
292292
the application.
293293
294294
**Bugs and caveats:** The destruction of modules and objects in modules is done
295-
in random order; this may cause destructors (:meth:`__del__` methods) to fail
295+
in random order; this may cause destructors (:meth:`~object.__del__` methods) to fail
296296
when they depend on other objects (even functions) or modules. Dynamically
297297
loaded extension modules loaded by Python are not unloaded. Small amounts of
298298
memory allocated by the Python interpreter may not be freed (if you find a leak,
@@ -381,7 F438 +381,7 @@ Process-wide parameters
381381
.. deprecated:: 3.11
382382
383383
384-
.. c:function:: wchar* Py_GetProgramName()
384+
.. c:function:: wchar_t* Py_GetProgramName()
385385
386386
.. index:: single: Py_SetProgramName()
387387
@@ -872,7 +872,7 @@ the fork, and releasing them afterwards. In addition, it resets any
872872
:ref:`lock-objects` in the child. When extending or embedding Python, there
873873
is no way to inform Python of additional (non-Python) locks that need to be
874874
acquired before or reset after a fork. OS facilities such as
875-
:c:func:`pthread_atfork` would need to be used to accomplish the same thing.
875+
:c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
876876
Additionally, when extending or embedding Python, calling :c:func:`fork`
877877
directly rather than through :func:`os.fork` (and returning to or calling
878878
into Python) may result in a deadlock by one of Python's internal locks
@@ -978,7 +978,7 @@ code, or when embedding the Python interpreter:
978978
.. note::
979979
Calling this function from a thread when the runtime is finalizing
980980
will terminate the thread, even if the thread was not created by Python.
981-
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
981+
You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
982982
check if the interpreter is in process of being finalized before calling
983983
this function to avoid unwanted termination.
984984
@@ -1024,7 +1024,7 @@ with sub-interpreters:
10241024
.. note::
10251025
Calling this function from a thread when the runtime is finalizing
10261026
will terminate the thread, even if the thread was not created by Python.
1027-
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
1027+
You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
10281028
check if the interpreter is in process of being finalized before calling
10291029
this function to avoid unwanted termination.
10301030
@@ -1306,7 +1306,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
13061306
.. note::
13071307
Calling this function from a thread when the runtime is finalizing
13081308
will terminate the thread, even if the thread was not created by Python.
1309-
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
1309+
You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
13101310
check if the interpreter is in process of being finalized before calling
13111311
this function to avoid unwanted termination.
13121312

‎Doc/c-api/init_config.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -850,7 +850,7 @@ PyConfig
850850
.. c:member:: int legacy_windows_stdio
851851
852852
If non-zero, use :class:`io.FileIO` instead of
853-
:class:`io.WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
853+
:class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
854854
and :data:`sys.stderr`.
855855
856856
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
@@ -1096,7 +1096,7 @@ PyConfig
10961096
10971097
Set to ``0`` by the :option:`-S` command line option.
10981098
1099-
:data:`sys.flags.no_site` is set to the inverted value of
1099+
:data:`sys.flags.no_site <sys.flags>` is set to the inverted value of
11001100
:c:member:`~PyConfig.site_import`.
11011101
11021102
Default: ``1``.

‎Doc/c-api/memory.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ need to be held.
136136

137137
The :ref:`default raw memory allocator <default-memory-allocators>` uses
138138
the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc`
139-
and :c:func:`free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
139+
and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
140140
zero bytes.
141141

142142
.. versionadded:: 3.4
@@ -264,14 +264,14 @@ The following type-oriented macros are provided for convenience. Note that
264264
*TYPE* refers to any C type.
265265
266266
267-
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
267+
.. c:macro:: PyMem_New(TYPE, n)
268268
269269
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
270270
memory. Returns a pointer cast to :c:expr:`TYPE*`. The memory will not have
271271
been initialized in any way.
272272
273273
274-
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
274+
.. c:macro:: PyMem_Resize(p, TYPE, n)
275275
276276
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
277277
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:expr:`TYPE*`. On return,
@@ -423,7 +423,7 @@ Customize Memory Allocators
423423
+----------------------------------------------------------+---------------------------------------+
424424
425425
.. versionchanged:: 3.5
426-
The :c:type:`PyMemAllocator` structure was renamed to
426+
The :c:type:`!PyMemAllocator` structure was renamed to
427427
:c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
428428
429429
@@ -627,8 +627,8 @@ with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
627627
628628
The arena allocator uses the following functions:
629629
630-
* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
631-
* :c:func:`mmap` and :c:func:`munmap` if available,
630+
* :c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows,
631+
* :c:func:`!mmap` and :c:func:`!munmap` if available,
632632
* :c:func:`malloc` and :c:func:`free` otherwise.
633633
634634
This allocator is disabled if Python is configured with the
@@ -732,8 +732,8 @@ allocators operating on different heaps. ::
732732
free(buf1); /* Fatal -- should be PyMem_Del() */
733733
734734
In addition to the functions aimed at handling raw memory blocks from the Python
735-
heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
736-
:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
735+
heap, objects in Python are allocated and released with :c:macro:`PyObject_New`,
736+
:c:macro:`PyObject_NewVar` and :c:func:`PyObject_Del`.
737737
738738
These will be explained in the next chapter on defining and implementing new
739739
object types in C.

0 commit comments

Comments
 (0)
0