mirror of
https://github.com/python-pillow/Pillow.git
synced 2024-09-21 19:38:57 +03:00
4cd4adddc3
Follow Python's file object semantics. User code is responsible for closing resources (usually through a context manager) in a deterministic way. To achieve this, remove __del__ functions. These functions used to closed open file handlers in an attempt to silence Python ResourceWarnings. However, using __del__ has the following drawbacks: - __del__ isn't called until the object's reference count reaches 0. Therefore, resource handlers remain open or in use longer than necessary. - The __del__ method isn't guaranteed to execute on system exit. See the Python documentation: https://docs.python.org/3/reference/datamodel.html#object.__del__ > It is not guaranteed that __del__() methods are called for objects > that still exist when the interpreter exits. - Exceptions that occur inside __del__ are ignored instead of raised. This has the potential of hiding bugs. This is also in the Python documentation: > Warning: Due to the precarious circumstances under which __del__() > methods are invoked, exceptions that occur during their execution > are ignored, and a warning is printed to sys.stderr instead. Instead, always close resource handlers when they are no longer in use. This will close the file handler at a specified point in the user's code and not wait until the interpreter chooses to. It is always guaranteed to run. And, if an exception occurs while closing the file handler, the bug will not be ignored. Now, when code receives a ResourceWarning, it will highlight an area that is mishandling resources. It should not simply be silenced, but fixed by closing resources with a context manager. All warnings that were emitted during tests have been cleaned up. To enable warnings, I passed the `-Wa` CLI option to Python. This exposed some mishandling of resources in ImageFile.__init__() and SpiderImagePlugin.loadImageSeries(), they too were fixed.
103 lines
3.4 KiB
ReStructuredText
103 lines
3.4 KiB
ReStructuredText
.. _file-handling:
|
|
|
|
File Handling in Pillow
|
|
=======================
|
|
|
|
When opening a file as an image, Pillow requires a filename, ``pathlib.Path``
|
|
object, or a file-like object. Pillow uses the filename or ``Path`` to open a
|
|
file, so for the rest of this article, they will all be treated as a file-like
|
|
object.
|
|
|
|
The following are all equivalent::
|
|
|
|
from PIL import Image
|
|
import io
|
|
import pathlib
|
|
|
|
with Image.open('test.jpg') as im:
|
|
...
|
|
|
|
with Image.open(pathlib.Path('test.jpg')) as im2:
|
|
...
|
|
|
|
with open('test.jpg', 'rb') as f:
|
|
im3 = Image.open(f)
|
|
...
|
|
|
|
with open('test.jpg', 'rb') as f:
|
|
im4 = Image.open(io.BytesIO(f.read()))
|
|
...
|
|
|
|
If a filename or a path-like object is passed to Pillow, then the resulting
|
|
file object opened by Pillow may also be closed by Pillow after the
|
|
``Image.Image.load()`` method is called, provided the associated image does not
|
|
have multiple frames.
|
|
|
|
Pillow cannot in general close and reopen a file, so any access to
|
|
that file needs to be prior to the close.
|
|
|
|
Image Lifecycle
|
|
---------------
|
|
|
|
* ``Image.open()`` Filenames and ``Path`` objects are opened as a file.
|
|
Metadata is read from the open file. The file is left open for further usage.
|
|
|
|
* ``Image.Image.load()`` When the pixel data from the image is
|
|
required, ``load()`` is called. The current frame is read into
|
|
memory. The image can now be used independently of the underlying
|
|
image file.
|
|
|
|
If a filename or a ``Path`` object was passed to ``Image.open()``, then the
|
|
file object was opened by Pillow and is considered to be used exclusively by
|
|
Pillow. So if the image is a single-frame image, the file will be closed in
|
|
this method after the frame is read. If the image is a multi-frame image,
|
|
(e.g. multipage TIFF and animated GIF) the image file is left open so that
|
|
``Image.Image.seek()`` can load the appropriate frame.
|
|
|
|
* ``Image.Image.close()`` Closes the file and destroys the core image object.
|
|
This is used in the Pillow context manager support. e.g.::
|
|
|
|
with Image.open('test.jpg') as img:
|
|
... # image operations here.
|
|
|
|
|
|
The lifecycle of a single-frame image is relatively simple. The file must
|
|
remain open until the ``load()`` or ``close()`` function is called or the
|
|
context manager exits.
|
|
|
|
Multi-frame images are more complicated. The ``load()`` method is not
|
|
a terminal method, so it should not close the underlying file. In general,
|
|
Pillow does not know if there are going to be any requests for additional
|
|
data until the caller has explicitly closed the image.
|
|
|
|
|
|
Complications
|
|
-------------
|
|
|
|
* ``TiffImagePlugin`` has some code to pass the underlying file descriptor into
|
|
libtiff (if working on an actual file). Since libtiff closes the file
|
|
descriptor internally, it is duplicated prior to passing it into libtiff.
|
|
|
|
* After a file has been closed, operations that require file access will fail::
|
|
|
|
with open('test.jpg', 'rb') as f:
|
|
im5 = Image.open(f)
|
|
im5.load() # FAILS, closed file
|
|
|
|
with Image.open('test.jpg') as im6:
|
|
pass
|
|
im6.load() # FAILS, closed file
|
|
|
|
|
|
Proposed File Handling
|
|
----------------------
|
|
|
|
* ``Image.Image.load()`` should close the image file, unless there are
|
|
multiple frames.
|
|
|
|
* ``Image.Image.seek()`` should never close the image file.
|
|
|
|
* Users of the library should use a context manager or call
|
|
``Image.Image.close()`` on any image opened with a filename or ``Path``
|
|
object to ensure that the underlying file is closed.
|