https://github.com/python/cpython/commit/a74892cb2168d249d9a8c53fad605a5def9... commit: a74892cb2168d249d9a8c53fad605a5def9b41d4 branch: main author: yyyyyyyan <24644216+yyyyyyyan@users.noreply.github.com> committer: JelleZijlstra <jelle.zijlstra@gmail.com> date: 2022-04-04T19:01:36-07:00 summary: bpo-41233: Add links to errnos referenced in exceptions docs (GH-21380) Co-authored-by: Andrew Kuchling <amk@amk.ca> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> files: A Misc/NEWS.d/next/Documentation/2020-07-07-22-54-51.bpo-41233.lyUJ8L.rst M Doc/library/errno.rst M Doc/library/exceptions.rst M Misc/ACKS diff --git a/Doc/library/errno.rst b/Doc/library/errno.rst index 93bdb6ca9b8e3..035340e256874 100644 --- a/Doc/library/errno.rst +++ b/Doc/library/errno.rst @@ -8,7 +8,7 @@ This module makes available standard ``errno`` system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are -borrowed from :file:`linux/include/errno.h`, which should be pretty +borrowed from :file:`linux/include/errno.h`, which should be all-inclusive. @@ -27,25 +27,26 @@ defined by the module. The specific list of defined symbols is available as .. data:: EPERM - Operation not permitted + Operation not permitted. This error is mapped to the exception + :exc:`PermissionError`. .. data:: ENOENT - No such file or directory + No such file or directory. This error is mapped to the exception + :exc:`FileNotFoundError`. .. data:: ESRCH - No such process + No such process. This error is mapped to the exception + :exc:`ProcessLookupError`. .. data:: EINTR - Interrupted system call. - - .. seealso:: - This error is mapped to the exception :exc:`InterruptedError`. + Interrupted system call. This error is mapped to the exception + :exc:`InterruptedError`. .. data:: EIO @@ -75,12 +76,13 @@ defined by the module. The specific list of defined symbols is available as .. data:: ECHILD - No child processes + No child processes. This error is mapped to the exception + :exc:`ChildProcessError`. .. data:: EAGAIN - Try again + Try again. This error is mapped to the exception :exc:`BlockingIOError`. .. data:: ENOMEM @@ -90,7 +92,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EACCES - Permission denied + Permission denied. This error is mapped to the exception + :exc:`PermissionError`. .. data:: EFAULT @@ -110,7 +113,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EEXIST - File exists + File exists. This error is mapped to the exception + :exc:`FileExistsError`. .. data:: EXDEV @@ -125,12 +129,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ENOTDIR - Not a directory + Not a directory. This error is mapped to the exception + :exc:`NotADirectoryError`. .. data:: EISDIR - Is a directory + Is a directory. This error is mapped to the exception + :exc:`IsADirectoryError`. .. data:: EINVAL @@ -185,7 +191,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EPIPE - Broken pipe + Broken pipe. This error is mapped to the exception + :exc:`BrokenPipeError`. .. data:: EDOM @@ -230,7 +237,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EWOULDBLOCK - Operation would block + Operation would block. This error is mapped to the exception + :exc:`BlockingIOError`. .. data:: ENOMSG @@ -540,12 +548,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ECONNABORTED - Software caused connection abort + Software caused connection abort. This error is mapped to the + exception :exc:`ConnectionAbortedError`. .. data:: ECONNRESET - Connection reset by peer + Connection reset by peer. This error is mapped to the exception + :exc:`ConnectionResetError`. .. data:: ENOBUFS @@ -565,7 +575,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: ESHUTDOWN - Cannot send after transport endpoint shutdown + Cannot send after transport endpoint shutdown. This error is mapped + to the exception :exc:`BrokenPipeError`. .. data:: ETOOMANYREFS @@ -575,12 +586,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ETIMEDOUT - Connection timed out + Connection timed out. This error is mapped to the exception + :exc:`TimeoutError`. .. data:: ECONNREFUSED - Connection refused + Connection refused. This error is mapped to the exception + :exc:`ConnectionRefusedError`. .. data:: EHOSTDOWN @@ -595,12 +608,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: EALREADY - Operation already in progress + Operation already in progress. This error is mapped to the + exception :exc:`BlockingIOError`. .. data:: EINPROGRESS - Operation now in progress + Operation now in progress. This error is mapped to the exception + :exc:`BlockingIOError`. .. data:: ESTALE diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 9e001c8dcd757..137566e079d20 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -652,8 +652,8 @@ depending on the system error code. Raised when an operation would block on an object (e.g. socket) set for non-blocking operation. - Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, - ``EWOULDBLOCK`` and ``EINPROGRESS``. + Corresponds to :c:data:`errno` :py:data:`~errno.EAGAIN`, :py:data:`~errno.EALREADY`, + :py:data:`~errno.EWOULDBLOCK` and :py:data:`~errno.EINPROGRESS`. In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have one more attribute: @@ -667,7 +667,7 @@ depending on the system error code. .. exception:: ChildProcessError Raised when an operation on a child process failed. - Corresponds to :c:data:`errno` ``ECHILD``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECHILD`. .. exception:: ConnectionError @@ -681,35 +681,35 @@ depending on the system error code. A subclass of :exc:`ConnectionError`, raised when trying to write on a pipe while the other end has been closed, or trying to write on a socket which has been shutdown for writing. - Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. + Corresponds to :c:data:`errno` :py:data:`~errno.EPIPE` and :py:data:`~errno.ESHUTDOWN`. .. exception:: ConnectionAbortedError A subclass of :exc:`ConnectionError`, raised when a connection attempt is aborted by the peer. - Corresponds to :c:data:`errno` ``ECONNABORTED``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNABORTED`. .. exception:: ConnectionRefusedError A subclass of :exc:`ConnectionError`, raised when a connection attempt is refused by the peer. - Corresponds to :c:data:`errno` ``ECONNREFUSED``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNREFUSED`. .. exception:: ConnectionResetError A subclass of :exc:`ConnectionError`, raised when a connection is reset by the peer. - Corresponds to :c:data:`errno` ``ECONNRESET``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNRESET`. .. exception:: FileExistsError Raised when trying to create a file or directory which already exists. - Corresponds to :c:data:`errno` ``EEXIST``. + Corresponds to :c:data:`errno` :py:data:`~errno.EEXIST`. .. exception:: FileNotFoundError Raised when a file or directory is requested but doesn't exist. - Corresponds to :c:data:`errno` ``ENOENT``. + Corresponds to :c:data:`errno` :py:data:`~errno.ENOENT`. .. exception:: InterruptedError @@ -725,7 +725,7 @@ depending on the system error code. Raised when a file operation (such as :func:`os.remove`) is requested on a directory. - Corresponds to :c:data:`errno` ``EISDIR``. + Corresponds to :c:data:`errno` :py:data:`~errno.EISDIR`. .. exception:: NotADirectoryError @@ -733,23 +733,23 @@ depending on the system error code. something which is not a directory. On most POSIX platforms, it may also be raised if an operation attempts to open or traverse a non-directory file as if it were a directory. - Corresponds to :c:data:`errno` ``ENOTDIR``. + Corresponds to :c:data:`errno` :py:data:`~errno.ENOTDIR`. .. exception:: PermissionError Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. - Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. + Corresponds to :c:data:`errno` :py:data:`~errno.EACCES` and :py:data:`~errno.EPERM`. .. exception:: ProcessLookupError Raised when a given process doesn't exist. - Corresponds to :c:data:`errno` ``ESRCH``. + Corresponds to :c:data:`errno` :py:data:`~errno.ESRCH`. .. exception:: TimeoutError Raised when a system function timed out at the system level. - Corresponds to :c:data:`errno` ``ETIMEDOUT``. + Corresponds to :c:data:`errno` :py:data:`~errno.ETIMEDOUT`. .. versionadded:: 3.3 All the above :exc:`OSError` subclasses were added. diff --git a/Misc/ACKS b/Misc/ACKS index 33e1c4c492983..5e66a2e757adf 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1298,6 +1298,7 @@ Ken Jin Ooi Piet van Oostrum Tomas Oppelstrup Jason Orendorff +Yan "yyyyyyyan" Orestes Bastien Orivel orlnub123 Douglas Orr diff --git a/Misc/NEWS.d/next/Documentation/2020-07-07-22-54-51.bpo-41233.lyUJ8L.rst b/Misc/NEWS.d/next/Documentation/2020-07-07-22-54-51.bpo-41233.lyUJ8L.rst new file mode 100644 index 0000000000000..ea0643aa00ee0 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2020-07-07-22-54-51.bpo-41233.lyUJ8L.rst @@ -0,0 +1 @@ +Link the errnos referenced in ``Doc/library/exceptions.rst`` to their respective section in ``Doc/library/errno.rst``, and vice versa. Previously this was only done for EINTR and InterruptedError. Patch by Yan "yyyyyyyan" Orestes.