Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-106948: Doc config ignores more standard C functions #107301

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@
Call :func:`sys.unraisablehook` using the current exception and *obj*
argument.

This utility function prints a warning message to ``sys.stderr`` when an

Check warning on line 83 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:meth reference target not found: __del__
exception has been set but it is impossible for the interpreter to actually
raise the exception. It is used, for example, when an exception occurs in an
:meth:`__del__` method.
Expand Down Expand Up @@ -108,7 +108,7 @@

.. c:function:: void PyErr_SetString(PyObject *type, const char *message)

This is the most common way to set the error indicator. The first argument

Check warning on line 111 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:data reference target not found: PyExc_RuntimeError
specifies the exception type; it is normally one of the standard exceptions,
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
The second argument is an error message; it is decoded from ``'utf-8'``.
Expand Down Expand Up @@ -163,7 +163,7 @@
This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable :c:data:`errno`. It constructs a
tuple object whose first item is the integer :c:data:`errno` value and whose
second item is the corresponding error message (gotten from :c:func:`!strerror`),
second item is the corresponding error message (gotten from :c:func:`strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
:c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
Expand All @@ -174,7 +174,7 @@

.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)

Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if

Check warning on line 177 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:attr reference target not found: filename
*filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
a third parameter. In the case of :exc:`OSError` exception,
this is used to define the :attr:`filename` attribute of the
Expand Down Expand Up @@ -221,7 +221,7 @@

.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the

Check warning on line 224 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:func reference target not found: PyErr_SetFromWindowsErrWithFilenameObject
filename is given as a C string. *filename* is decoded from the filesystem
encoding (:func:`os.fsdecode`).

Expand All @@ -230,7 +230,7 @@

.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an

Check warning on line 233 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:func reference target not found: PyErr_SetFromWindowsErrWithFilenameObject
additional parameter specifying the exception type to be raised.

.. availability:: Windows.
Expand Down Expand Up @@ -329,7 +329,7 @@
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
and so forth.

Warning categories must be subclasses of :c:data:`PyExc_Warning`;

Check warning on line 332 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:data reference target not found: PyExc_Warning

Check warning on line 332 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:data reference target not found: PyExc_Warning

Check warning on line 332 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:data reference target not found: PyExc_Exception

Check warning on line 332 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

c:data reference target not found: PyExc_RuntimeWarning
:c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
Python warning categories are available as global variables whose names are
Expand Down Expand Up @@ -369,7 +369,7 @@

.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

Function similar to :c:func:`PyErr_WarnFormat`, but *category* is

Check warning on line 372 in Doc/c-api/exceptions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:func reference target not found: warnings.WarningMessage
:exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.

.. versionadded:: 3.6
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -106,15 +106,15 @@ Operating System Utilities
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)

Return the current signal handler for signal *i*. This is a thin wrapper around
either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions
either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
(\*)(int)`.


.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Set the signal handler for signal *i* to be *h*; return the old signal handler.
This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do
This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:expr:`void (\*)(int)`.

Expand Down
78 changes: 77 additions & 1 deletion Doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,43 +78,119 @@

nitpick_ignore = [
# Standard C functions
('c:func', '_exit'),
('c:func', '_stricmp'),
('c:func', 'abort'),
('c:func', 'atof'),
('c:func', 'calloc'),
('c:func', 'close'),
('c:func', 'ctime'),
('c:func', 'dlopen'),
('c:func', 'exec'),
('c:func', 'exit'),
('c:func', 'fcntl'),
('c:func', 'flock'),
('c:func', 'fork'),
('c:func', 'free'),
('c:func', 'fstat'),
('c:func', 'fsync'),
('c:func', 'getsid'),
('c:func', 'gettimeofday'),
('c:func', 'gmtime'),
('c:func', 'inet_aton'),
('c:func', 'inet_pton'),
('c:func', 'ioctl'),
('c:func', 'localeconv'),
('c:func', 'localtime'),
('c:func', 'lockf'),
('c:func', 'lstat'),
('c:func', 'main'),
('c:func', 'malloc'),
('c:func', 'memcpy'),
('c:func', 'memmove'),
('c:func', 'mktime'),
('c:func', 'mmap'),
('c:func', 'munmap'),
('c:func', 'open'),
('c:func', 'perror'),
('c:func', 'posix_spawn'),
('c:func', 'posix_spawn_file_actions_addclose'),
('c:func', 'posix_spawn_file_actions_adddup2'),
('c:func', 'posix_spawn_file_actions_addopen'),
('c:func', 'posix_spawnp'),
('c:func', 'printf'),
('c:func', 'putenv'),
('c:func', 'qsort'),
('c:func', 'realloc'),
('c:func', 'select'),
('c:func', 'setenv'),
('c:func', 'setpgid'),
('c:func', 'setpgrp'),
('c:func', 'setsid'),
('c:func', 'setsockopt'),
('c:func', 'sigaction'),
('c:func', 'sigaltstack'),
('c:func', 'siginterrupt'),
('c:func', 'signal'),
('c:func', 'snprintf'),
('c:func', 'splice'),
('c:func', 'sprintf'),
('c:func', 'stat'),
('c:func', 'statvfs'),
('c:func', 'strcasecmp'),
('c:func', 'strcmp'),
('c:func', 'strerror'),
('c:func', 'strlen'),
('c:func', 'strncmp'),
('c:func', 'system'),
('c:func', 'unsetenv'),
('c:func', 'vsnprintf'),
('c:func', 'vsprintf'),

# Standard C types
('c:type', 'FILE'),
('c:type', '__int'),
('c:type', 'int64_t'),
('c:type', 'intmax_t'),
('c:type', 'off_t'),
('c:type', 'ptrdiff_t'),
('c:type', 'siginfo_t'),
('c:type', 'size_t'),
('c:type', 'ssize_t'),
('c:type', 'time_t'),
('c:type', 'uint64_t'),
('c:type', 'uintmax_t'),
('c:type', 'uintptr_t'),
('c:type', 'va_list'),
('c:type', 'wchar'),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a typo, not a c:type. 😉

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh! I wasn't sure about this one, ok, I will remove it. First, I'm trying to land PR #107302 to reduce the number of warnings.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
('c:type', 'wchar'),
('c:type', 'wchar_t'),

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that wchar_t is already listed right below, so the change here should be just removing it:

Suggested change
('c:type', 'wchar'),

('c:type', 'wchar_t'),

# Standard C macros
('c:macro', 'EDOM'),
('c:macro', 'EINTR'),
('c:macro', 'LLONG_MAX'),
('c:macro', 'LLONG_MIN'),
('c:macro', 'LONG_MAX'),
('c:macro', 'LONG_MIN'),

# Standard C variables
('c:data', 'errno'),

# Win32 API functions
('c:func', 'FormatMessage'),
('c:func', 'GetFileInformationByHandle'),
('c:func', 'GetLastError'),
('c:func', 'GetVersionEx'),
('c:func', 'MessageBeep'),
('c:func', 'PlaySound'),
('c:func', 'ShellExecute'),
('c:func', 'TerminateProcess'),
('c:func', 'VirtualAlloc'),
('c:func', 'VirtualFree'),
('c:func', 'WSAIoctl'),

# Win32 API macros
('c:macro', 'CP_ACP'),

# Standard environment variables
('envvar', 'BROWSER'),
('envvar', 'COLUMNS'),
Expand Down
8 changes: 4 additions & 4 deletions Doc/library/mailbox.rst
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()

Three locking mechanisms are used---dot locking and, if available, the
:c:func:`!flock` and :c:func:`!lockf` system calls.
:c:func:`flock` and :c:func:`lockf` system calls.


.. seealso::
Expand Down Expand Up @@ -588,7 +588,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()

Three locking mechanisms are used---dot locking and, if available, the
:c:func:`!flock` and :c:func:`!lockf` system calls. For MH mailboxes, locking
:c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking
the mailbox means locking the :file:`.mh_sequences` file and, only for the
duration of any operations that affect them, locking individual message
files.
Expand Down Expand Up @@ -686,7 +686,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()

Three locking mechanisms are used---dot locking and, if available, the
:c:func:`!flock` and :c:func:`!lockf` system calls.
:c:func:`flock` and :c:func:`lockf` system calls.


.. seealso::
Expand Down Expand Up @@ -737,7 +737,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()

Three locking mechanisms are used---dot locking and, if available, the
:c:func:`!flock` and :c:func:`!lockf` system calls.
:c:func:`flock` and :c:func:`lockf` system calls.


.. seealso::
Expand Down
6 changes: 3 additions & 3 deletions Doc/library/os.rst
Original file line number Diff line number Diff line change
Expand Up @@ -714,14 +714,14 @@ process and user.

.. function:: getsid(pid, /)

Call the system call :c:func:`!getsid`. See the Unix manual for the semantics.
Call the system call :c:func:`getsid`. See the Unix manual for the semantics.

.. availability:: Unix, not Emscripten, not WASI.


.. function:: setsid()

Call the system call :c:func:`!setsid`. See the Unix manual for the semantics.
Call the system call :c:func:`setsid`. See the Unix manual for the semantics.

.. availability:: Unix, not Emscripten, not WASI.

Expand All @@ -739,7 +739,7 @@ process and user.
.. function:: strerror(code, /)

Return the error message corresponding to the error code in *code*.
On platforms where :c:func:`!strerror` returns ``NULL`` when given an unknown
On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
error number, :exc:`ValueError` is raised.


Expand Down
2 changes: 1 addition & 1 deletion Doc/library/signal.rst
Original file line number Diff line number Diff line change
Expand Up @@ -562,7 +562,7 @@ The :mod:`signal` module defines the following functions:

Note that installing a signal handler with :func:`signal` will reset the
restart behaviour to interruptible by implicitly calling
:c:func:`!siginterrupt` with a true *flag* value for the given signal.
:c:func:`siginterrupt` with a true *flag* value for the given signal.


.. function:: signal(signalnum, handler)
Expand Down
2 changes: 1 addition & 1 deletion Doc/whatsnew/2.6.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2982,7 +2982,7 @@ Changes to Python's build process and to the C API include:

* Python now must be compiled with C89 compilers (after 19
years!). This means that the Python source tree has dropped its
own implementations of :c:func:`!memmove` and :c:func:`!strerror`, which
own implementations of :c:func:`memmove` and :c:func:`strerror`, which
are in the C89 standard library.

* Python 2.6 can be built with Microsoft Visual Studio 2008 (version
Expand Down
2 changes: 1 addition & 1 deletion Misc/NEWS.d/3.10.0a1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ format string in f-string and :meth:`str.format`.

The implementation of :func:`signal.siginterrupt` now uses
:c:func:`!sigaction` (if it is available in the system) instead of the
deprecated :c:func:`!siginterrupt`. Patch by Pablo Galindo.
deprecated :c:func:`siginterrupt`. Patch by Pablo Galindo.

..

Expand Down
Loading