From 86ce449e8284482fe2af6eec1f28a50ec5c40f9c Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sat, 19 Feb 2022 15:17:26 +1100 Subject: [PATCH] Documented using PyEncoder --- docs/handbook/appendices.rst | 2 +- ....rst => writing-your-own-image-plugin.rst} | 34 +++++++++---------- src/PIL/ImageFile.py | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) rename docs/handbook/{writing-your-own-file-decoder.rst => writing-your-own-image-plugin.rst} (93%) diff --git a/docs/handbook/appendices.rst b/docs/handbook/appendices.rst index 6afaef07175..347a8848b37 100644 --- a/docs/handbook/appendices.rst +++ b/docs/handbook/appendices.rst @@ -8,4 +8,4 @@ Appendices image-file-formats text-anchors - writing-your-own-file-decoder + writing-your-own-image-plugin diff --git a/docs/handbook/writing-your-own-file-decoder.rst b/docs/handbook/writing-your-own-image-plugin.rst similarity index 93% rename from docs/handbook/writing-your-own-file-decoder.rst rename to docs/handbook/writing-your-own-image-plugin.rst index f69da9a9441..0c9cfe8e80d 100644 --- a/docs/handbook/writing-your-own-file-decoder.rst +++ b/docs/handbook/writing-your-own-image-plugin.rst @@ -4,10 +4,9 @@ Writing Your Own Image Plugin ============================= Pillow uses a plugin model which allows you to add your own -decoders to the library, without any changes to the library -itself. Such plugins usually have names like -:file:`XxxImagePlugin.py`, where ``Xxx`` is a unique format name -(usually an abbreviation). +decoders and encoders to the library, without any changes to the library +itself. Such plugins usually have names like :file:`XxxImagePlugin.py`, +where ``Xxx`` is a unique format name (usually an abbreviation). .. warning:: Pillow >= 2.1.0 no longer automatically imports any file in the Python path with a name ending in @@ -413,23 +412,24 @@ value, or if there is a read error from the file. This function should free any allocated memory and release any resources from external libraries. -.. _file-decoders-py: +.. _file-codecs-py: -Writing Your Own File Decoder in Python -======================================= +Writing Your Own File Codec in Python +===================================== -Python file decoders should derive from -:py:class:`PIL.ImageFile.PyDecoder` and should at least override the -decode method. File decoders should be registered using -:py:meth:`PIL.Image.register_decoder`. As in the C implementation of -the file decoders, there are three stages in the lifetime of a -Python-based file decoder: +Python file decoders and encoders should derive from +:py:class:`PIL.ImageFile.PyDecoder` and :py:class:`PIL.ImageFile.PyEncoder` +respectively, and should at least override the decode or encode method. +They should be registered using :py:meth:`PIL.Image.register_decoder` and +:py:meth:`PIL.Image.register_encoder`. As in the C implementation of +the file codecs, there are three stages in the lifetime of a +Python-based file codec: 1. Setup: Pillow looks for the decoder in the registry, then instantiates the class. -2. Decoding: The decoder instance's ``decode`` method is repeatedly - called with a buffer of data to be interpreted. - -3. Cleanup: The decoder instance's ``cleanup`` method is called. +2. Transforming: The instance's ``decode`` method is repeatedly called with + a buffer of data to be interpreted, or the ``encode`` method is repeatedly + called with the size of data to be output. +3. Cleanup: The instance's ``cleanup`` method is called. diff --git a/src/PIL/ImageFile.py b/src/PIL/ImageFile.py index 35934f98a9c..2d2fe314c6e 100644 --- a/src/PIL/ImageFile.py +++ b/src/PIL/ImageFile.py @@ -656,7 +656,7 @@ class PyDecoder(PyCodec): Python implementation of a format decoder. Override this class and add the decoding logic in the :meth:`decode` method. - See :ref:`Writing Your Own File Decoder in Python` + See :ref:`Writing Your Own File Codec in Python` """ _pulls_fd = False