python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-01-12 18:26:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3737 from jdufresne/quotes

Browse Source 
Add backticks around Python classes and modules in open_files.rst
This commit is contained in:
Hugo 2019-03-23 08:31:15 +00:00 committed by GitHub
commit 30841fe808
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/reference/open_files.rst
View File

@ -3,10 +3,10 @@
File Handling in Pillow File Handling in Pillow
======================= =======================
When opening a file as an image, Pillow requires a filename, When opening a file as an image, Pillow requires a filename, ``pathlib.Path``
pathlib.Path object, or a file-like object. Pillow uses the filename object, or a file-like object. Pillow uses the filename or ``Path`` to open a
or Path to open a file, so for the rest of this article, they will all file, so for the rest of this article, they will all be treated as a file-like
be treated as a file-like object. object.
The first four of these items are equivalent, the last is dangerous The first four of these items are equivalent, the last is dangerous
and may fail:: and may fail::
@ -48,24 +48,23 @@ Issues
Image Lifecycle Image Lifecycle
--------------- ---------------
* ``Image.open()`` Path-like objects are opened as a file. Metadata is read * ``Image.open()`` Filenames and ``Path`` objects are opened as a file.
from the open file. The file is left open for further usage. 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 * ``Image.Image.load()`` When the pixel data from the image is
required, ``load()`` is called. The current frame is read into required, ``load()`` is called. The current frame is read into
memory. The image can now be used independently of the underlying memory. The image can now be used independently of the underlying
image file. image file.
If a filename or a path-like object was passed to ``Image.open()``, then If a filename or a ``Path`` object was passed to ``Image.open()``, then the
the file object was opened by Pillow and is considered to be used exclusively file object was opened by Pillow and is considered to be used exclusively by
by Pillow. So if the image is a single-frame image, the file will Pillow. So if the image is a single-frame image, the file will be closed in
be closed in this method after the frame is read. If the image is a this method after the frame is read. If the image is a multi-frame image,
multi-frame image, (e.g. multipage TIFF and animated GIF) the image file is (e.g. multipage TIFF and animated GIF) the image file is left open so that
left open so that ``Image.Image.seek()`` can load the appropriate frame. ``Image.Image.seek()`` can load the appropriate frame.
* ``Image.Image.close()`` Closes the file pointer and destroys the * ``Image.Image.close()`` Closes the file and destroys the core image object.
core image object. This is used in the Pillow context manager This is used in the Pillow context manager support. e.g.::
support. e.g.::
with Image.open('test.jpg') as img: with Image.open('test.jpg') as img:
... # image operations here. ... # image operations here.
@ -84,10 +83,9 @@ data until the caller has explicitly closed the image.
Complications Complications
------------- -------------
* TiffImagePlugin has some code to pass the underlying file descriptor * ``TiffImagePlugin`` has some code to pass the underlying file descriptor into
into libtiff (if working on an actual file). Since libtiff closes libtiff (if working on an actual file). Since libtiff closes the file
the file descriptor internally, it is duplicated prior to passing it descriptor internally, it is duplicated prior to passing it into libtiff.
into libtiff.
* I don't think that there's any way to make this safe without * I don't think that there's any way to make this safe without
changing the lazy loading:: changing the lazy loading::