From f5b4565d8c163cc1c55ed9f5525ec5848915aaa0 Mon Sep 17 00:00:00 2001 From: nulano Date: Sat, 27 Jun 2020 17:24:13 +0200 Subject: [PATCH 1/3] document is_animated and n_frames --- docs/reference/Image.rst | 31 +++++++++++++++++++++++++++++++ src/PIL/Image.py | 6 ++++++ 2 files changed, 37 insertions(+) diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 216fa1196..bccaf01f4 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -324,3 +324,34 @@ Instances of the :py:class:`Image` class have the following attributes: Unless noted elsewhere, this dictionary does not affect saving files. :type: :py:class:`dict` + +.. py:attribute:: Image.is_animated + :type: bool + + This attribute is ``True`` if the Image is animated, ``False`` otherwise. + Typically defined as ``Image.n_frames > 1``. + + This attribute is only defined by Image plugins that support animated Images. + Plugins may leave this attribute undefined if they don't support loading + animated images, even if the given format supports animated images. Use + ``hasattr(image, "is_animated")`` to check whether the implementation + supports animated images, or ``getattr(image, "is_animated", False)`` + to check whether an image has been loaded with animation support. + + .. seealso:: :attr:`~Image.n_frames`, :func:`~Image.seek` and :func:`~Image.tell` + +.. py:attribute:: Image.n_frames + :type: int + + The number of frames in this image. + Defined if and only if :attr:`~Image.is_animated` is also defined. + Equal to 1 for non-animated images loaded by a plugin supporting animations. + + This attribute is only defined by Image plugins that support animated Images. + Plugins may leave this attribute undefined if they don't support loading + animated images, even if the given format supports animated images. Use + ``hasattr(image, "is_animated")`` to check whether the implementation + supports animated images, or ``getattr(image, "n_frames", 1)`` + to check whether an image has been loaded with more than one frame. + + .. seealso:: :attr:`~Image.is_animated`, :func:`~Image.seek` and :func:`~Image.tell` diff --git a/src/PIL/Image.py b/src/PIL/Image.py index 7a2ae02d6..e272414d7 100644 --- a/src/PIL/Image.py +++ b/src/PIL/Image.py @@ -2170,6 +2170,9 @@ class Image: See :py:meth:`~PIL.Image.Image.tell`. + If defined, :attr:`~PIL.Image.Image.n_frames` refers to the + number of available frames. + :param frame: Frame number, starting at 0. :exception EOFError: If the call attempts to seek beyond the end of the sequence. @@ -2254,6 +2257,9 @@ class Image: """ Returns the current frame number. See :py:meth:`~PIL.Image.Image.seek`. + If defined, :attr:`~PIL.Image.Image.n_frames` refers to the + number of available frames. + :returns: Frame number, starting with 0. """ return 0 From 91bd2d37529ecf15691fb790b8abba7ba7281215 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sun, 5 Jul 2020 21:47:23 +1000 Subject: [PATCH 2/3] Altered descriptions [ci skip] --- docs/reference/Image.rst | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index dd56b20ff..1eced066f 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -333,15 +333,14 @@ Instances of the :py:class:`Image` class have the following attributes: .. py:attribute:: Image.is_animated :type: bool - This attribute is ``True`` if the Image is animated, ``False`` otherwise. - Typically defined as ``Image.n_frames > 1``. + ``True`` if this image has more than one frame, or ``False`` otherwise. - This attribute is only defined by Image plugins that support animated Images. + This attribute is only defined by image plugins that support animated images. Plugins may leave this attribute undefined if they don't support loading - animated images, even if the given format supports animated images. Use - ``hasattr(image, "is_animated")`` to check whether the implementation - supports animated images, or ``getattr(image, "is_animated", False)`` - to check whether an image has been loaded with animation support. + animated images, even if the given format supports animated images. + + To check whether an image is animated regardless of its format, use + ``getattr(image, "is_animated", False)``. .. seealso:: :attr:`~Image.n_frames`, :func:`~Image.seek` and :func:`~Image.tell` @@ -349,15 +348,13 @@ Instances of the :py:class:`Image` class have the following attributes: :type: int The number of frames in this image. - Defined if and only if :attr:`~Image.is_animated` is also defined. - Equal to 1 for non-animated images loaded by a plugin supporting animations. - This attribute is only defined by Image plugins that support animated Images. + This attribute is only defined by image plugins that support animated images. Plugins may leave this attribute undefined if they don't support loading - animated images, even if the given format supports animated images. Use - ``hasattr(image, "is_animated")`` to check whether the implementation - supports animated images, or ``getattr(image, "n_frames", 1)`` - to check whether an image has been loaded with more than one frame. + animated images, even if the given format supports animated images. + + To check the number of frames in an image regardless of its format, use + ``getattr(image, "n_frames", 1)``. .. seealso:: :attr:`~Image.is_animated`, :func:`~Image.seek` and :func:`~Image.tell` From c244ecf2452a87873f0dfba4a573e758b850f485 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 17:16:41 +0200 Subject: [PATCH 3/3] avoid suggesting that Pillow understands animation in all formats Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com> --- docs/reference/Image.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 1eced066f..23f3eb03c 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -339,8 +339,9 @@ Instances of the :py:class:`Image` class have the following attributes: Plugins may leave this attribute undefined if they don't support loading animated images, even if the given format supports animated images. - To check whether an image is animated regardless of its format, use - ``getattr(image, "is_animated", False)``. + Given that this attribute is not present for all images use + ``getattr(image, "is_animated", False)`` to check if Pillow is aware of multiple + frames in an image regardless of its format. .. seealso:: :attr:`~Image.n_frames`, :func:`~Image.seek` and :func:`~Image.tell` @@ -353,8 +354,9 @@ Instances of the :py:class:`Image` class have the following attributes: Plugins may leave this attribute undefined if they don't support loading animated images, even if the given format supports animated images. - To check the number of frames in an image regardless of its format, use - ``getattr(image, "n_frames", 1)``. + Given that this attribute is not present for all images use + ``getattr(image, "n_frames", 1)`` to check the number of frames that Pillow is + aware of in an image regardless of its format. .. seealso:: :attr:`~Image.is_animated`, :func:`~Image.seek` and :func:`~Image.tell`