From d31bee5e350d5eb06c0789552236f2f068811962 Mon Sep 17 00:00:00 2001 From: Jon Dufresne Date: Fri, 22 Mar 2019 05:57:05 -0700 Subject: [PATCH] Add backticks around Python classes and modules in open_files.rst --- docs/reference/open_files.rst | 36 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/reference/open_files.rst b/docs/reference/open_files.rst index 511eb97bf..0d62210dd 100644 --- a/docs/reference/open_files.rst +++ b/docs/reference/open_files.rst @@ -3,10 +3,10 @@ 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. +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 first four of these items are equivalent, the last is dangerous and may fail:: @@ -48,24 +48,23 @@ Issues Image Lifecycle --------------- -* ``Image.open()`` Path-like objects are opened as a file. Metadata is read - from the open file. The file is left open for further usage. +* ``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-like 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. + 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 pointer and destroys the - core image object. This is used in the Pillow context manager - support. e.g.:: +* ``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. @@ -84,10 +83,9 @@ 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. +* ``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. * ``decoder.handles_eof`` This slightly misnamed flag indicates that the decoder wants to be called with a 0 length buffer when reads are