From f5b4565d8c163cc1c55ed9f5525ec5848915aaa0 Mon Sep 17 00:00:00 2001
From: nulano <nulano@nulano.eu>
Date: Sat, 27 Jun 2020 17:24:13 +0200
Subject: [PATCH] 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