Merge pull request #7465 from radarhere/mode

Describe how to populate mode and size when writing a plugin

docs/handbook/writing-your-own-image-plugin.rst

@@ -26,14 +26,14 @@ Pillow decodes files in two stages:
    it.
 
 An image plugin should contain a format handler derived from the
-:py:class:`PIL.ImageFile.ImageFile` base class. This class should
-provide an ``_open`` method, which reads the file header and
-sets up at least the :py:attr:`~PIL.Image.Image.mode` and
-:py:attr:`~PIL.Image.Image.size` attributes. To be able to load the
-file, the method must also create a list of ``tile`` descriptors,
-which contain a decoder name, extents of the tile, and
-any decoder-specific data. The format handler class must be explicitly
-registered, via a call to the :py:mod:`~PIL.Image` module.
+:py:class:`PIL.ImageFile.ImageFile` base class. This class should provide an
+``_open`` method, which reads the file header and set at least the internal
+``_size`` and ``_mode`` attributes so that :py:attr:`~PIL.Image.Image.mode` and
+:py:attr:`~PIL.Image.Image.size` are populated. To be able to load the file,
+the method must also create a list of ``tile`` descriptors, which contain a
+decoder name, extents of the tile, and any decoder-specific data. The format
+handler class must be explicitly registered, via a call to the
+:py:mod:`~PIL.Image` module.
 
 .. note:: For performance reasons, it is important that the
   ``_open`` method quickly rejects files that do not have the
@@ -96,13 +96,13 @@ true color.
     )
 
 
-The format handler must always set the
-:py:attr:`~PIL.Image.Image.size` and :py:attr:`~PIL.Image.Image.mode`
-attributes. If these are not set, the file cannot be opened. To
-simplify the plugin, the calling code considers exceptions like
-:py:exc:`SyntaxError`, :py:exc:`KeyError`, :py:exc:`IndexError`,
-:py:exc:`EOFError` and :py:exc:`struct.error` as a failure to identify
-the file.
+The format handler must always set the internal ``_size`` and ``_mode``
+attributes so that :py:attr:`~PIL.Image.Image.size` and
+:py:attr:`~PIL.Image.Image.mode` are populated. If these are not set, the file
+cannot be opened. To simplify the plugin, the calling code considers exceptions
+like :py:exc:`SyntaxError`, :py:exc:`KeyError`, :py:exc:`IndexError`,
+:py:exc:`EOFError` and :py:exc:`struct.error` as a failure to identify the
+file.
 
 Note that the image plugin must be explicitly registered using
 :py:func:`PIL.Image.register_open`. Although not required, it is also a good

docs/releasenotes/10.1.0.rst

@@ -1,8 +1,8 @@
 10.1.0
 ------
 
-Backwards Incompatible Changes
-==============================
+API Changes
+===========
 
 Setting image mode
 ^^^^^^^^^^^^^^^^^^
@@ -13,9 +13,6 @@ 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.
 
-API Changes
-===========
-
 Accept a list in getpixel()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^