bpo-41233: Add links to errnos referenced in exceptions docs (GH-21380)

yyyyyyyan · akuchling · JelleZijlstra · web-flow · commit a74892cb2168 · 2022-04-04T19:01:36.000-07:00
Co-authored-by: Andrew Kuchling &lt;amk@amk.ca&gt;
Co-authored-by: Jelle Zijlstra &lt;jelle.zijlstra@gmail.com&gt;
diff --git 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
@@ -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,31 +725,31 @@ 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
 
    Raised when a directory operation (such as :func:`os.listdir`) is requested on
    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
@@ -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
@@ -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.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`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.