Document all the save params for PNG, and their references [ci skip]

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))
 

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
 -------------------
 

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).