python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-10-30 23:47:27 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7465 from radarhere/mode

Browse Source 
Describe how to populate mode and size when writing a plugin
This commit is contained in:
Hugo van Kemenade 2023-10-15 10:01:18 +02:00 committed by GitHub
commit d10f802b22
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 17 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/handbook/writing-your-own-image-plugin.rst
View File

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

7
docs/releasenotes/10.1.0.rst
View File

@ -1,8 +1,8 @@
10.1.0 10.1.0
------ ------
Backwards Incompatible Changes API Changes
============================== ===========
Setting image mode 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 explicit error to prevent later consequences. The ``convert`` method is the
correct way to change an image's mode. correct way to change an image's mode.
API Changes
===========
Accept a list in getpixel() Accept a list in getpixel()
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^