From ca74a5ea42cff8985e0350536a916e3a454c82d1 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 1 Nov 2023 20:18:25 +0200 Subject: [PATCH 1/2] Docs: link exceptions to Python docs --- docs/deprecations.rst | 22 +++++++++++----------- docs/reference/ImageFont.rst | 4 ++-- docs/releasenotes/10.0.0.rst | 2 +- docs/releasenotes/10.1.0.rst | 2 +- docs/releasenotes/2.8.0.rst | 2 +- docs/releasenotes/3.4.0.rst | 2 +- docs/releasenotes/5.3.0.rst | 5 +++-- docs/releasenotes/5.4.1.rst | 4 ++-- docs/releasenotes/6.0.0.rst | 2 +- docs/releasenotes/6.1.0.rst | 2 +- docs/releasenotes/7.0.0.rst | 2 +- docs/releasenotes/7.1.2.rst | 2 +- docs/releasenotes/7.2.0.rst | 2 +- docs/releasenotes/8.0.0.rst | 2 +- docs/releasenotes/9.0.0.rst | 2 +- docs/releasenotes/9.1.0.rst | 6 +++--- 16 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/deprecations.rst b/docs/deprecations.rst index ffde4d45ca2..b4fbb8d5053 100644 --- 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 index e15aed9fc18..a944a13fa37 100644 --- 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.0.0.rst b/docs/releasenotes/10.0.0.rst index 06acfc7afd2..1f46e14729a 100644 --- a/docs/releasenotes/10.0.0.rst +++ b/docs/releasenotes/10.0.0.rst @@ -174,7 +174,7 @@ Added ImageFont.MAX_STRING_LENGTH ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To protect against potential DOS attacks when using arbitrary strings as text -input, Pillow will now raise a ``ValueError`` if the number of characters +input, Pillow will now raise a :py:exc:`ValueError` if the number of characters passed into ImageFont methods is over a certain limit, :py:data:`PIL.ImageFont.MAX_STRING_LENGTH`. diff --git a/docs/releasenotes/10.1.0.rst b/docs/releasenotes/10.1.0.rst index 8c3413c8c56..fd556bdf17f 100644 --- 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 index c522fe8b0a3..4dbbc0bdd29 100644 --- 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 index dc5e2e29598..2bbafe741d2 100644 --- 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 index bff56566b66..8f276da2407 100644 --- a/docs/releasenotes/5.3.0.rst +++ b/docs/releasenotes/5.3.0.rst @@ -8,7 +8,7 @@ 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. @@ -16,7 +16,8 @@ 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 index 78f483db658..bbabd652090 100644 --- 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 index 70a52b58e4f..5e69f0b6b5a 100644 --- 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 index e7c593e6e63..ce3edc5fa9b 100644 --- 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 index f2e2352897a..ed6026593e6 100644 --- 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 index b12d84e33bd..ec0063e7953 100644 --- 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 index ff1b7c9e764..91e54da1999 100644 --- 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 index 00c691a7459..2bf299dd3d8 100644 --- 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/9.0.0.rst b/docs/releasenotes/9.0.0.rst index 73e77ad3ef6..090ec802467 100644 --- 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 index 19690ca59b5..02da702a799 100644 --- 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 From 8cbd0b5fe09725e57f0253290f894877e408552d Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sun, 5 Nov 2023 12:18:38 +1100 Subject: [PATCH 2/2] Docs: link exceptions to Python docs --- docs/releasenotes/8.3.1.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/releasenotes/8.3.1.rst b/docs/releasenotes/8.3.1.rst index e97070c111c..6af2b37bfe1 100644 --- 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.