Skip to content

Commit a1ddb4d

Browse files
committed
Describe how to populate mode and size
1 parent 4ace56d commit a1ddb4d

File tree

1 file changed

+15
-15
lines changed

1 file changed

+15
-15
lines changed

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

+15-15
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,14 @@ Pillow decodes files in two stages:
2626
it.
2727

2828
An image plugin should contain a format handler derived from the
29-
:py:class:`PIL.ImageFile.ImageFile` base class. This class should
30-
provide an ``_open`` method, which reads the file header and
31-
sets up at least the :py:attr:`~PIL.Image.Image.mode` and
32-
:py:attr:`~PIL.Image.Image.size` attributes. To be able to load the
33-
file, the method must also create a list of ``tile`` descriptors,
34-
which contain a decoder name, extents of the tile, and
35-
any decoder-specific data. The format handler class must be explicitly
36-
registered, via a call to the :py:mod:`~PIL.Image` module.
29+
:py:class:`PIL.ImageFile.ImageFile` base class. This class should provide an
30+
``_open`` method, which reads the file header and set at least the internal
31+
``_size`` and ``_mode`` attributes so that :py:attr:`~PIL.Image.Image.mode` and
32+
:py:attr:`~PIL.Image.Image.size` are populated. To be able to load the file,
33+
the method must also create a list of ``tile`` descriptors, which contain a
34+
decoder name, extents of the tile, and any decoder-specific data. The format
35+
handler class must be explicitly registered, via a call to the
36+
:py:mod:`~PIL.Image` module.
3737

3838
.. note:: For performance reasons, it is important that the
3939
``_open`` method quickly rejects files that do not have the
@@ -96,13 +96,13 @@ true color.
9696
)
9797

9898

99-
The format handler must always set the
100-
:py:attr:`~PIL.Image.Image.size` and :py:attr:`~PIL.Image.Image.mode`
101-
attributes. If these are not set, the file cannot be opened. To
102-
simplify the plugin, the calling code considers exceptions like
103-
:py:exc:`SyntaxError`, :py:exc:`KeyError`, :py:exc:`IndexError`,
104-
:py:exc:`EOFError` and :py:exc:`struct.error` as a failure to identify
105-
the file.
99+
The format handler must always set the internal ``_size`` and ``_mode``
100+
attributes so that :py:attr:`~PIL.Image.Image.size` and
101+
:py:attr:`~PIL.Image.Image.mode` are populated. If these are not set, the file
102+
cannot be opened. To simplify the plugin, the calling code considers exceptions
103+
like :py:exc:`SyntaxError`, :py:exc:`KeyError`, :py:exc:`IndexError`,
104+
:py:exc:`EOFError` and :py:exc:`struct.error` as a failure to identify the
105+
file.
106106

107107
Note that the image plugin must be explicitly registered using
108108
:py:func:`PIL.Image.register_open`. Although not required, it is also a good

0 commit comments

Comments
 (0)