Merge pull request #7512 from hugovk/docs-link-exceptions

hugovk · web-flow · commit 4a7cf0551aa9 · 2023-11-05T10:58:12.000+02:00
Docs: link exceptions to Python docs
diff --git a/docs/deprecations.rst b/docs/deprecations.rst
@@ -10,7 +10,7 @@ Deprecated features
 -------------------
 
 Below are features which are considered deprecated. Where appropriate,
-a ``DeprecationWarning`` is issued.
+a :py:exc:`DeprecationWarning` is issued.
 
 PSFile
 ~~~~~~
@@ -267,7 +267,7 @@ ImageFile.raise_ioerror
 .. deprecated:: 7.2.0
 .. versionremoved:: 9.0.0
 
-``IOError`` was merged into ``OSError`` in Python 3.3.
+:py:exc:`IOError` was merged into :py:exc:`OSError` in Python 3.3.
 So, ``ImageFile.raise_ioerror`` has been removed.
 Use ``ImageFile.raise_oserror`` instead.
 
@@ -293,9 +293,9 @@ im.offset
 ``im.offset()`` has been removed, call :py:func:`.ImageChops.offset()` instead.
 
 It was documented as deprecated in PIL 1.1.2,
-raised a ``DeprecationWarning`` since 1.1.5,
-an ``Exception`` since Pillow 3.0.0
-and ``NotImplementedError`` since 3.3.0.
+raised a :py:exc:`DeprecationWarning` since 1.1.5,
+an :py:exc:`Exception` since Pillow 3.0.0
+and :py:exc:`NotImplementedError` since 3.3.0.
 
 Image.fromstring, im.fromstring and im.tostring
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -307,9 +307,9 @@ Image.fromstring, im.fromstring and im.tostring
 * ``im.fromstring()`` has been removed, call :py:meth:`~PIL.Image.Image.frombytes()` instead.
 * ``im.tostring()`` has been removed, call :py:meth:`~PIL.Image.Image.tobytes()` instead.
 
-They issued a ``DeprecationWarning`` since 2.0.0,
-an ``Exception`` since 3.0.0
-and ``NotImplementedError`` since 3.3.0.
+They issued a :py:exc:`DeprecationWarning` since 2.0.0,
+an :py:exc:`Exception` since 3.0.0
+and :py:exc:`NotImplementedError` since 3.3.0.
 
 ImageCms.CmsProfile attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -318,7 +318,7 @@ ImageCms.CmsProfile attributes
 .. versionremoved:: 8.0.0
 
 Some attributes in :py:class:`PIL.ImageCms.CmsProfile` have been removed. From 6.0.0,
-they issued a ``DeprecationWarning``:
+they issued a :py:exc:`DeprecationWarning`:
 
 ========================  ===================================================
 Removed                   Use instead
@@ -442,7 +442,7 @@ PIL.OleFileIO
 .. deprecated:: 4.0.0
 .. versionremoved:: 6.0.0
 
-PIL.OleFileIO was removed as a vendored file in Pillow 4.0.0 (2017-01) in favour of
-the upstream :pypi:`olefile` Python package, and replaced with an ``ImportError`` in 5.0.0
+``PIL.OleFileIO`` was removed as a vendored file in Pillow 4.0.0 (2017-01) in favour of
+the upstream :pypi:`olefile` Python package, and replaced with an :py:exc:`ImportError` in 5.0.0
 (2018-01). The deprecated file has now been removed from Pillow. If needed, install from
 PyPI (eg. ``python3 -m pip install olefile``).
diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst
@@ -20,7 +20,7 @@ the imToolkit package.
 
 .. warning::
     To protect against potential DOS attacks when using arbitrary strings as
-    text input, Pillow will raise a ``ValueError`` if the number of characters
+    text input, Pillow will raise a :py:exc:`ValueError` if the number of characters
     is over a certain limit, :py:data:`MAX_STRING_LENGTH`.
 
     This threshold can be changed by setting
@@ -89,5 +89,5 @@ Constants
 .. data:: MAX_STRING_LENGTH
 
     Set to 1,000,000, to protect against potential DOS attacks. Pillow will
-    raise a ``ValueError`` if the number of characters is over this limit. The
+    raise a :py:exc:`ValueError` if the number of characters is over this limit. The
     check can be disabled by setting ``ImageFont.MAX_STRING_LENGTH = None``.
diff --git a/docs/releasenotes/10.1.0.rst b/docs/releasenotes/10.1.0.rst
@@ -8,7 +8,7 @@ Setting image mode
 ^^^^^^^^^^^^^^^^^^
 
 If you attempt to set the mode of an image directly, e.g.
-``im.mode = "RGBA"``, you will now receive an ``AttributeError``. This is
+``im.mode = "RGBA"``, you will now receive an :py:exc:`AttributeError`. This is
 not about removing existing functionality, but instead about raising an
 explicit error to prevent later consequences. The ``convert`` method is the
 correct way to change an image's mode.
diff --git a/docs/releasenotes/2.8.0.rst b/docs/releasenotes/2.8.0.rst
@@ -10,7 +10,7 @@ operations. As a result PIL was unable to open them as images, requiring a wrap
 ``cStringIO`` or ``BytesIO``.
 
 Now new functionality has been added to ``Image.open()`` by way of an ``.seek(0)`` check and
-catch on exception ``AttributeError`` or ``io.UnsupportedOperation``. If this is caught we
+catch on exception :py:exc:`AttributeError` or :py:exc:`io.UnsupportedOperation`. If this is caught we
 attempt to wrap the object using ``io.BytesIO`` (which will only work on buffer-file-like
 objects).
 
diff --git a/docs/releasenotes/3.4.0.rst b/docs/releasenotes/3.4.0.rst
@@ -19,7 +19,7 @@ Deprecation Warning when Saving JPEGs
 
 JPEG images cannot contain an alpha channel. Pillow prior to 3.4.0
 silently drops the alpha channel. With this release Pillow will now
-issue a ``DeprecationWarning`` when attempting to save a ``RGBA`` mode
+issue a :py:exc:`DeprecationWarning` when attempting to save a ``RGBA`` mode
 image as a JPEG. This will become an error in Pillow 4.2.
 
 New DDS Decoders
diff --git a/docs/releasenotes/5.3.0.rst b/docs/releasenotes/5.3.0.rst
@@ -8,15 +8,16 @@ Image size
 ^^^^^^^^^^
 
 If you attempt to set the size of an image directly, e.g.
-``im.size = (100, 100)``, you will now receive an ``AttributeError``. This is
+``im.size = (100, 100)``, you will now receive an :py:exc:`AttributeError`. This is
 not about removing existing functionality, but instead about raising an
 explicit error to prevent later consequences. The ``resize`` method is the
 correct way to change an image's size.
 
 The exceptions to this are:
 
 * The ICO and ICNS image formats, which use ``im.size = (100, 100)`` to select a subimage.
-* The TIFF image format, which now has a ``DeprecationWarning`` for this action, as direct image size setting was previously necessary to work around an issue with tile extents.
+* The TIFF image format, which now has a :py:exc:`DeprecationWarning` for this action,
+  as direct image size setting was previously necessary to work around an issue with tile extents.
 
 
 API Additions
diff --git a/docs/releasenotes/5.4.1.rst b/docs/releasenotes/5.4.1.rst
@@ -15,7 +15,7 @@ PNG: Handle IDAT chunks after image end
 
 Some PNG images have multiple IDAT chunks. In some cases, Pillow will stop
 reading image data before the IDAT chunks finish. A regression caused an
-``EOFError`` exception when previously there was none. This is now fixed, and
+:py:exc:`EOFError` exception when previously there was none. This is now fixed, and
 file reading continues in case there are subsequent text chunks.
 
 PNG: MIME type
@@ -30,7 +30,7 @@ File closing
 ^^^^^^^^^^^^
 
 A regression caused an unsupported image file to report a
-``ValueError: seek of closed file`` exception instead of an ``OSError``. This
+``ValueError: seek of closed file`` exception instead of an :py:exc:`OSError`. This
 has been fixed by ensuring that image plugins only close their internal ``__fp``
 if they are not the same as ``ImageFile``'s ``fp``, allowing each to manage their own
 file pointers.
diff --git a/docs/releasenotes/6.0.0.rst b/docs/releasenotes/6.0.0.rst
@@ -103,7 +103,7 @@ ImageCms.CmsProfile attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some attributes in ``ImageCms.CmsProfile`` have been deprecated since Pillow 3.2.0. From
-6.0.0, they issue a ``DeprecationWarning``:
+6.0.0, they issue a :py:exc:`DeprecationWarning`:
 
 ========================  ===============================
 Deprecated                Use instead
diff --git a/docs/releasenotes/6.1.0.rst b/docs/releasenotes/6.1.0.rst
@@ -58,7 +58,7 @@ file. ``ImageFont.FreeTypeFont`` has four new methods,
 :py:meth:`PIL.ImageFont.FreeTypeFont.set_variation_by_name` for using named styles, and
 :py:meth:`PIL.ImageFont.FreeTypeFont.get_variation_axes` and
 :py:meth:`PIL.ImageFont.FreeTypeFont.set_variation_by_axes` for using font axes
-instead. An ``IOError`` will be raised if the font is not a variation font. FreeType
+instead. An :py:exc:`IOError` will be raised if the font is not a variation font. FreeType
 2.9.1 or greater is required.
 
 Other Changes
diff --git a/docs/releasenotes/7.0.0.rst b/docs/releasenotes/7.0.0.rst
@@ -85,7 +85,7 @@ Custom unidentified image error
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Pillow will now throw a custom ``UnidentifiedImageError`` when an image cannot be
-identified. For backwards compatibility, this will inherit from ``OSError``.
+identified. For backwards compatibility, this will inherit from :py:exc:`OSError`.
 
 New argument ``reducing_gap`` for Image.resize() and Image.thumbnail() methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/releasenotes/7.1.2.rst b/docs/releasenotes/7.1.2.rst
@@ -7,7 +7,7 @@ Fix another regression seeking PNG files
 This fixes a regression introduced in 7.1.0 when adding support for APNG files.
 
 When calling ``seek(n)`` on a regular PNG where ``n > 0``, it failed to raise an
-``EOFError`` as it should have done, resulting in:
+:py:exc:`EOFError` as it should have done, resulting in:
 
 .. code-block:: pycon
 
diff --git a/docs/releasenotes/7.2.0.rst b/docs/releasenotes/7.2.0.rst
@@ -53,6 +53,6 @@ a custom :py:class:`~PIL.ImageShow.Viewer` class.
 ImageFile.raise_ioerror
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-``IOError`` was merged into ``OSError`` in Python 3.3. So, ``ImageFile.raise_ioerror``
+:py:exc:`IOError` was merged into :py:exc:`OSError` in Python 3.3. So, ``ImageFile.raise_ioerror``
 is now deprecated and will be removed in a future release. Use
 ``ImageFile.raise_oserror`` instead.
diff --git a/docs/releasenotes/8.0.0.rst b/docs/releasenotes/8.0.0.rst
@@ -168,7 +168,7 @@ offset.
 Error for large BMP files
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Previously, if a BMP file was too large, an ``OSError`` would be raised. Now,
+Previously, if a BMP file was too large, an :py:exc:`OSError` would be raised. Now,
 ``DecompressionBombError`` is used instead, as Pillow already uses for other formats.
 
 Dark theme for docs
diff --git a/docs/releasenotes/8.3.1.rst b/docs/releasenotes/8.3.1.rst
@@ -22,9 +22,10 @@ Catch OSError when checking if destination is sys.stdout
 ========================================================
 
 In 8.3.0, a check to see if the destination was ``sys.stdout`` when saving an image was
-updated. This lead to an OSError being raised if the environment restricted access.
+updated. This lead to an :py:exc:`OSError` being raised if the environment restricted
+access.
 
-The OSError is now silently caught.
+The :py:exc:`OSError` is now silently caught.
 
 Fixed removing orientation in ImageOps.exif_transpose
 =====================================================
@@ -34,7 +35,7 @@ original image EXIF data was not modified, and the orientation was only removed
 the modified copy.
 
 However, for certain images the orientation was already missing from the modified
-image, leading to a KeyError.
+image, leading to a :py:exc:`KeyError`.
 
 This error has been resolved, and the copying of metadata to the modified image
 improved.
diff --git a/docs/releasenotes/9.0.0.rst b/docs/releasenotes/9.0.0.rst
@@ -63,7 +63,7 @@ a custom :py:class:`~PIL.ImageShow.Viewer` class.
 ImageFile.raise_ioerror
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-``IOError`` was merged into ``OSError`` in Python 3.3. So, ``ImageFile.raise_ioerror``
+:py:exc:`IOError` was merged into :py:exc:`OSError` in Python 3.3. So, ``ImageFile.raise_ioerror``
 has been removed. Use ``ImageFile.raise_oserror`` instead.
 
 
diff --git a/docs/releasenotes/9.1.0.rst b/docs/releasenotes/9.1.0.rst
@@ -8,14 +8,14 @@ Raise an error when performing a negative crop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Performing a negative crop on an image previously just returned a ``(0, 0)`` image. Now
-it will raise a ``ValueError``, to help reduce confusion if a user has unintentionally
+it will raise a :py:exc:`ValueError`, to help reduce confusion if a user has unintentionally
 provided the wrong arguments.
 
 Added specific error if path coordinate type is incorrect
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Rather than returning a ``SystemError``, passing the incorrect types of coordinates into
-a path will now raise a more specific ``ValueError``, with the message "incorrect
+Rather than returning a :py:exc:`SystemError`, passing the incorrect types of coordinates into
+a path will now raise a more specific :py:exc:`ValueError`, with the message "incorrect
 coordinate type".
 
 Replace requirements.txt with extras
