Skip to content

Commit

Permalink
pythongh-106948: Doc config ignores more standard C functions
Browse files Browse the repository at this point in the history
Complete nitpick_ignore list in Doc/conf.py to ignore more standard C
functions, variables, macros, and also Win32 API functions and
macros.
  • Loading branch information
vstinner committed Jul 26, 2023
1 parent b1de380 commit c3ebffa
Show file tree
Hide file tree
Showing 8 changed files with 93 additions and 17 deletions.
4 changes: 2 additions & 2 deletions Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ For convenience, some of these functions will always return a
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 Down Expand Up @@ -370,7 +370,7 @@ an error value).
.. 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
:exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.
:exc:`ResourceWarning` and it passes *source* to :func:`!warnings.WarningMessage`.
.. versionadded:: 3.6
Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -97,24 +97,24 @@ Operating System Utilities
.. c:function:: int PyOS_CheckStack()
Return true when the interpreter runs out of stack space. This is a reliable
check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently
check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently
on certain versions of Windows using the Microsoft Visual C++ compiler).
:c:macro:`USE_STACKCHECK` will be defined automatically; you should never
:c:macro:`!USE_STACKCHECK` will be defined automatically; you should never
change the definition in your own code.
.. 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'),
('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

0 comments on commit c3ebffa

Please sign in to comment.