Describe how to populate mode and size

Author: radarhere

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
+The format handler must always populate the :py:attr:`~PIL.Image.Image.size`
+and :py:attr:`~PIL.Image.Image.mode` attributes, by setting the internal
+`_size` and `_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.
+: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