From ec10b70ea66e738ccb5c28f75a9c5d2b1c197de7 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 26 Oct 2018 03:56:28 -0700 Subject: [PATCH] bpo-35044, doc: Use the :exc: role for the exceptions (GH-10037) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit (cherry picked from commit e483f02423917dc4dfd25f46e5b9e6fce304777d) Co-authored-by: Stéphane Wirtel --- Doc/c-api/conversion.rst | 2 +- Doc/faq/design.rst | 2 +- Doc/faq/extending.rst | 2 +- Doc/glossary.rst | 2 +- Doc/library/configparser.rst | 4 ++-- Doc/library/imp.rst | 2 +- Doc/library/importlib.rst | 2 +- Doc/library/io.rst | 2 +- Doc/library/os.path.rst | 2 +- Doc/library/ssl.rst | 2 +- Doc/library/typing.rst | 2 +- Doc/library/unittest.rst | 2 +- Doc/tutorial/datastructures.rst | 2 +- Doc/whatsnew/3.5.rst | 2 +- Doc/whatsnew/3.6.rst | 2 +- Doc/whatsnew/3.7.rst | 2 +- .../Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst | 2 ++ 17 files changed, 19 insertions(+), 17 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index 9566d9d7920..c46722d782a 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -60,7 +60,7 @@ The following functions provide locale-independent string to number conversions. The conversion is independent of the current locale. If ``endptr`` is ``NULL``, convert the whole string. Raise - ValueError and return ``-1.0`` if the string is not a valid + :exc:`ValueError` and return ``-1.0`` if the string is not a valid representation of a floating-point number. If endptr is not ``NULL``, convert as much of the string as diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 5e54df61bda..e2d63a0323d 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -528,7 +528,7 @@ Some unacceptable solutions that have been proposed: mydict = {[1, 2]: '12'} print(mydict[[1, 2]]) - would raise a KeyError exception because the id of the ``[1, 2]`` used in the + would raise a :exc:`KeyError` exception because the id of the ``[1, 2]`` used in the second line differs from that in the first line. In other words, dictionary keys should be compared using ``==``, not using :keyword:`is`. diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index fd04a83df33..b611bb48012 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -63,7 +63,7 @@ How can I execute arbitrary Python statements from C? The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes a single string argument to be executed in the context of the module ``__main__`` and returns ``0`` for success and ``-1`` when an exception occurred -(including ``SyntaxError``). If you want more control, use +(including :exc:`SyntaxError`). If you want more control, use :c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in ``Python/pythonrun.c``. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 16fc7f0783c..b8e773741ce 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -200,7 +200,7 @@ Glossary ``int(3.15)`` converts the floating point number to the integer ``3``, but in ``3+4.5``, each argument is of a different type (one int, one float), and both must be converted to the same type before they can be added or it - will raise a ``TypeError``. Without coercion, all arguments of even + will raise a :exc:`TypeError`. Without coercion, all arguments of even compatible types would have to be normalized to the same value by the programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``. diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 1c479bf9080..8f6b5a792d3 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -401,11 +401,11 @@ However, there are a few differences that should be taken into account: because default values cannot be deleted from the section (because technically they are not there). If they are overridden in the section, deleting causes the default value to be visible again. Trying to delete a default value - causes a ``KeyError``. + causes a :exc:`KeyError`. * ``DEFAULTSECT`` cannot be removed from the parser: - * trying to delete it raises ``ValueError``, + * trying to delete it raises :exc:`ValueError`, * ``parser.clear()`` leaves it intact, diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst index ccf5f92d163..1bd6f12b915 100644 --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -229,7 +229,7 @@ file paths. file path. For example, if *path* is ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform - to :pep:`3147` format, a ``ValueError`` is raised. If + to :pep:`3147` format, a :exc:`ValueError` is raised. If :attr:`sys.implementation.cache_tag` is not defined, :exc:`NotImplementedError` is raised. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 09d5989c2f8..c6c7160a9d1 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1407,7 +1407,7 @@ an :term:`importer`. file path. For example, if *path* is ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform - to :pep:`3147` or :pep:`488` format, a ``ValueError`` is raised. If + to :pep:`3147` or :pep:`488` format, a :exc:`ValueError` is raised. If :attr:`sys.implementation.cache_tag` is not defined, :exc:`NotImplementedError` is raised. diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 98649de7310..2536c37e772 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -39,7 +39,7 @@ pipe). All streams are careful about the type of data you give to them. For example giving a :class:`str` object to the ``write()`` method of a binary stream -will raise a ``TypeError``. So will giving a :class:`bytes` object to the +will raise a :exc:`TypeError`. So will giving a :class:`bytes` object to the ``write()`` method of a text stream. .. versionchanged:: 3.3 diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 1f767170b5a..edcbb3aa8b0 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -317,7 +317,7 @@ the :mod:`glob` module.) Normalize the case of a pathname. On Unix and Mac OS X, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase. On Windows, it also converts forward slashes to backward slashes. - Raise a TypeError if the type of *path* is not ``str`` or ``bytes`` (directly + Raise a :exc:`TypeError` if the type of *path* is not ``str`` or ``bytes`` (directly or indirectly through the :class:`os.PathLike` interface). .. versionchanged:: 3.6 diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 175ea17ff13..0835e9ae04e 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1941,7 +1941,7 @@ to speed up repeated connections from the same clients. .. note:: With versions of OpenSSL older than 0.9.8m, it is only possible to set options, not to clear them. Attempting to clear an option - (by resetting the corresponding bits) will raise a ``ValueError``. + (by resetting the corresponding bits) will raise a :exc:`ValueError`. .. versionchanged:: 3.6 :attr:`SSLContext.options` returns :class:`Options` flags: diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 268adc0c9de..9861da8d707 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -899,7 +899,7 @@ The module defines the following classes, functions and decorators: non-``@overload``-decorated definition, while the latter is used at runtime but should be ignored by a type checker. At runtime, calling a ``@overload``-decorated function directly will raise - ``NotImplementedError``. An example of overload that gives a more + :exc:`NotImplementedError`. An example of overload that gives a more precise type than can be expressed using a union or a type variable:: @overload diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 83aee1b0262..b35a724fc54 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1161,7 +1161,7 @@ Test cases If *delta* is supplied instead of *places* then the difference between *first* and *second* must be less or equal to (or greater than) *delta*. - Supplying both *delta* and *places* raises a ``TypeError``. + Supplying both *delta* and *places* raises a :exc:`TypeError`. .. versionchanged:: 3.2 :meth:`assertAlmostEqual` automatically considers almost equal objects diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst index 95dc0f98ba5..b291d11595a 100644 --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -41,7 +41,7 @@ objects: :noindex: Remove the first item from the list whose value is equal to *x*. It raises a - ``ValueError`` if there is no such item. + :exc:`ValueError` if there is no such item. .. method:: list.pop([i]) diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 4eddf841dcb..b4540ac1dd9 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -593,7 +593,7 @@ a :term:`__future__` import is necessary:: RuntimeError: generator raised StopIteration Without a ``__future__`` import, a :exc:`PendingDeprecationWarning` will be -raised whenever a ``StopIteration`` exception is raised inside a generator. +raised whenever a :exc:`StopIteration` exception is raised inside a generator. .. seealso:: diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index bba16543686..936ea2dc321 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -741,7 +741,7 @@ Some smaller changes made to the core Python language are: * A ``global`` or ``nonlocal`` statement must now textually appear before the first use of the affected name in the same scope. - Previously this was a ``SyntaxWarning``. + Previously this was a :exc:`SyntaxWarning`. * It is now possible to set a :ref:`special method ` to ``None`` to indicate that the corresponding operation is not available. diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 9a13dae13ea..9fc0f239836 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -1030,7 +1030,7 @@ support the loading of resources from packages. See also lacks a spec. (Contributed by Garvit Khatri in :issue:`29851`.) -:func:`importlib.find_spec` now raises ``ModuleNotFoundError`` instead of +:func:`importlib.find_spec` now raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if the specified parent module is not a package (i.e. lacks a ``__path__`` attribute). (Contributed by Milan Oberkirch in :issue:`30436`.) diff --git a/Misc/NEWS.d/next/Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst b/Misc/NEWS.d/next/Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst new file mode 100644 index 00000000000..05e67e51a73 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst @@ -0,0 +1,2 @@ +Fix the documentation with the role ``exc`` for the appropriated exception. Patch by +Stéphane Wirtel