From 962ced916d9ae8fe3d96db65f74f3b2670eeec20 Mon Sep 17 00:00:00 2001 From: wiredfool Date: Wed, 19 Nov 2014 14:54:43 -0800 Subject: [PATCH 1/3] Image.save docs, rename fp, link to params [ci skip] --- PIL/Image.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/PIL/Image.py b/PIL/Image.py index d556df34c..51d2d989d 100644 --- a/PIL/Image.py +++ b/PIL/Image.py @@ -1621,15 +1621,16 @@ class Image: Keyword options can be used to provide additional instructions to the writer. If a writer doesn't recognise an option, it is - silently ignored. The available options are described later in - this handbook. + silently ignored. The available options are described in the + :doc:`image format documentation + <../handbook/image-file-formats>` for each writer. You can use a file object instead of a filename. In this case, you must always specify the format. The file object must - implement the **seek**, **tell**, and **write** + implement the ``seek``, ``tell``, and ``write`` methods, and be opened in binary mode. - :param file: File name or file object. + :param fp: File name or file object. :param format: Optional format override. If omitted, the format to use is determined from the filename extension. If a file object was used instead of a filename, this From c770984867cfbb38124f3c803860c5b354bb84b9 Mon Sep 17 00:00:00 2001 From: wiredfool Date: Wed, 19 Nov 2014 15:35:01 -0800 Subject: [PATCH 2/3] Document all the save params for PNG, and their references [ci skip] --- PIL/PngImagePlugin.py | 47 +++++++++++++++++++++++----- docs/PIL.rst | 23 ++++++++++++++ docs/handbook/image-file-formats.rst | 9 ++++++ 3 files changed, 72 insertions(+), 7 deletions(-) diff --git a/PIL/PngImagePlugin.py b/PIL/PngImagePlugin.py index fcf27aba0..8403461be 100644 --- a/PIL/PngImagePlugin.py +++ b/PIL/PngImagePlugin.py @@ -149,31 +149,56 @@ class ChunkStream: return cids -# -------------------------------------------------------------------- -# Subclass of string to allow iTXt chunks to look like strings while -# keeping their extra information - class iTXt(str): + """ + Subclass of string to allow iTXt chunks to look like strings while + keeping their extra information + + """ @staticmethod def __new__(cls, text, lang, tkey): + """ + :param value: value for this key + :param lang: language code + :param tkey: UTF-8 version of the key name + """ + self = str.__new__(cls, text) self.lang = lang self.tkey = tkey return self -# -------------------------------------------------------------------- -# PNG chunk container (for use with save(pnginfo=)) - class PngInfo: + """ + PNG chunk container (for use with save(pnginfo=)) + + """ def __init__(self): self.chunks = [] def add(self, cid, data): + """Appends an arbitrary chunk. Use with caution. + + :param cid: a byte string, 4 bytes long. + :param data: a byte string of the encoded data + + """ + self.chunks.append((cid, data)) def add_itxt(self, key, value, lang="", tkey="", zip=False): + """Appends an iTXt chunk. + + :param key: latin-1 encodable text key name + :param value: value for this key + :param lang: language code + :param tkey: UTF-8 version of the key name + :param zip: compression flag + + """ + if not isinstance(key, bytes): key = key.encode("latin-1", "strict") if not isinstance(value, bytes): @@ -191,6 +216,14 @@ class PngInfo: value) def add_text(self, key, value, zip=0): + """Appends a text chunk. + + :param key: latin-1 encodable text key name + :param value: value for this key, text or an + :py:class:`PIL.PngImagePlugin.iTXt` instance + :param zip: compression flag + + """ if isinstance(value, iTXt): return self.add_itxt(key, value, value.lang, value.tkey, bool(zip)) diff --git a/docs/PIL.rst b/docs/PIL.rst index 8bf89c685..53a61872b 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -113,6 +113,29 @@ can be found here. :undoc-members: :show-inheritance: +:class:`PngImagePlugin.iTXt` Class +---------------------------------- + +.. autoclass:: PIL.PngImagePlugin.iTXt + :members: + :undoc-members: + :show-inheritance: + + .. method:: __new__(cls, text, lang, tkey) + + :param value: value for this key + :param lang: language code + :param tkey: UTF-8 version of the key name + +:class:`PngImagePlugin.PngInfo` Class +------------------------------------- + +.. autoclass:: PIL.PngImagePlugin.PngInfo + :members: + :undoc-members: + :show-inheritance: + + :mod:`TarIO` Module ------------------- diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index a1961fa7c..f9216818d 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -332,6 +332,9 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following Transparency color index. This key is omitted if the image is not a transparent palette image. +``Open`` also sets ``Image.text`` to a list of the values of the +``tEXt``, ``zTXt``, and ``iTXt`` chunks of the PNG image. + The :py:meth:`~PIL.Image.Image.save` method supports the following options: **optimize** @@ -343,6 +346,12 @@ The :py:meth:`~PIL.Image.Image.save` method supports the following options: For ``P``, ``L``, and ``RGB`` images, this option controls what color image to mark as transparent. +**dpi** + A tuple of two numbers corresponding to the desired dpi in each direction. + +**pnginfo** + A :py:class:`PIL.PngImagePlugin.PngInfo` instance containing text tags. + **bits (experimental)** For ``P`` images, this option controls how many bits to store. If omitted, the PNG writer uses 8 bits (256 colors). From 176c804b3900dab3332af5cd7b714eb8a3325830 Mon Sep 17 00:00:00 2001 From: wiredfool Date: Wed, 19 Nov 2014 15:40:49 -0800 Subject: [PATCH 3/3] Note on info not used for saving [ci skip] --- docs/reference/Image.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 08af684d5..d868d26c5 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -193,4 +193,6 @@ Instances of the :py:class:`Image` class have the following attributes: operation affects the dictionary. If you need the information later on, keep a reference to the info dictionary returned from the open method. + Unless noted elsewhere, this dictionary does not affect saving files. + :type: :py:class:`dict`