From 95e31944971d4441430e82047e93aacd905f72c7 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Mon, 28 Feb 2022 12:21:29 +1100 Subject: [PATCH] Improved documentation for _pulls_fd and _pushes_fd --- docs/handbook/writing-your-own-image-plugin.rst | 11 ++++++++++- src/PIL/ImageFile.py | 3 +++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/handbook/writing-your-own-image-plugin.rst b/docs/handbook/writing-your-own-image-plugin.rst index d62be7685..3efea1426 100644 --- a/docs/handbook/writing-your-own-image-plugin.rst +++ b/docs/handbook/writing-your-own-image-plugin.rst @@ -395,7 +395,9 @@ from the file like object. Alternatively, if ``pulls_fd`` is set, then the decode function is called once, with an empty buffer. It is the decoder's responsibility -to decode the entire tile in that one call. +to decode the entire tile in that one call. Using this will provide a +codec with more freedom, but that freedom may mean increased memory usage +if entire tile is held in memory at once by the codec. If an error occurs, set ``state->errcode`` and return -1. @@ -429,6 +431,13 @@ Python-based file codec: a buffer of data to be interpreted, or the ``encode`` method is repeatedly called with the size of data to be output. + Alternatively, if the decoder's ``_pulls_fd`` property (or the encoder's + ``_pushes_fd`` property) is set to ``True``, then ``decode`` and ``encode`` + will only be called once. In the decoder, ``self.fd`` can be used to access + the file-like object. Using this will provide a codec with more freedom, but + that freedom may mean increased memory usage if entire file is held in + memory at once by the codec. + In ``decode``, once the data has been interpreted, ``set_as_raw`` can be used to populate the image. diff --git a/src/PIL/ImageFile.py b/src/PIL/ImageFile.py index 767b38ca4..acfb1a734 100644 --- a/src/PIL/ImageFile.py +++ b/src/PIL/ImageFile.py @@ -725,6 +725,9 @@ class PyEncoder(PyCodec): def encode_to_pyfd(self): """ + If ``pushes_fd`` is ``True``, then this method will be used, + and ``encode()`` will only be called once. + :returns: A tuple of ``(bytes consumed, errcode)``. Err codes are from :data:`.ImageFile.ERRORS`. """