[Python-checkins] bpo-35044, doc: Use the :exc: role for the exceptions (GH-10037)
Miss Islington (bot)
webhook-mailer at python.org
Fri Oct 26 06:56:32 EDT 2018
https://github.com/python/cpython/commit/ec10b70ea66e738ccb5c28f75a9c5d2b1c197de7
commit: ec10b70ea66e738ccb5c28f75a9c5d2b1c197de7
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-10-26T03:56:28-07:00
summary:
bpo-35044, doc: Use the :exc: role for the exceptions (GH-10037)
(cherry picked from commit e483f02423917dc4dfd25f46e5b9e6fce304777d)
Co-authored-by: Stéphane Wirtel <stephane at wirtel.be>
files:
A Misc/NEWS.d/next/Documentation/2018-10-22-14-09-58.bpo-35044.qjvNtI.rst
M Doc/c-api/conversion.rst
M Doc/faq/design.rst
M Doc/faq/extending.rst
M Doc/glossary.rst
M Doc/library/configparser.rst
M Doc/library/imp.rst
M Doc/library/importlib.rst
M Doc/library/io.rst
M Doc/library/os.path.rst
M Doc/library/ssl.rst
M Doc/library/typing.rst
M Doc/library/unittest.rst
M Doc/tutorial/datastructures.rst
M Doc/whatsnew/3.5.rst
M Doc/whatsnew/3.6.rst
M Doc/whatsnew/3.7.rst
diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
index 9566d9d79200..c46722d782a2 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 5e54df61bda9..e2d63a0323da 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 fd04a83df33c..b611bb48012a 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 16fc7f0783c8..b8e773741ce7 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 1c479bf9080a..8f6b5a792d3d 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 ccf5f92d1636..1bd6f12b915f 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 09d5989c2f8b..c6c7160a9d15 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 98649de7310f..2536c37e772b 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 1f767170b5a5..edcbb3aa8b0b 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 175ea17ff138..0835e9ae04e6 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 268adc0c9de5..9861da8d7073 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 83aee1b02621..b35a724fc540 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 95dc0f98ba51..b291d11595a8 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 4eddf841dcbe..b4540ac1dd90 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 bba16543686c..936ea2dc321e 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 <specialnames>` 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 9a13dae13eab..9fc0f2398369 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 000000000000..05e67e51a73a
--- /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
More information about the Python-checkins
mailing list