Document ImageFile.Parser

PIL/ImageFile.py

@@ -137,7 +137,7 @@ class ImageFile(Image.Image):
         readonly = 0
 
         if self.filename and len(self.tile) == 1 and not hasattr(sys, 'pypy_version_info'):
-            # As of pypy 2.1.0, memory mapping was failing here. 
+            # As of pypy 2.1.0, memory mapping was failing here.
             # try memory mapping
             d, e, o, a = self.tile[0]
             if d == "raw" and a[0] == self.mode and a[0] in Image._MAPMODES:
@@ -299,6 +299,8 @@ class Parser:
     """
     Incremental image parser.  This class implements the standard
     feed/close consumer interface.
+
+    In Python 2.x, this is an old-style class.
     """
     incremental = None
     image = None
@@ -318,7 +320,7 @@ class Parser:
         """
         (Consumer) Feed data to the parser.
 
-        :param data" A string buffer.
+        :param data: A string buffer.
         :exception IOError: If the parser failed to parse the image file.
         """
         # collect data
@@ -404,7 +406,9 @@ class Parser:
         (Consumer) Close the stream.
 
         :returns: An image object.
-        :exception IOError: If the parser failed to parse the image file.
+        :exception IOError: If the parser failed to parse the image file either
+                            because it cannot be identified or cannot be
+                            decoded.
         """
         # finish decoding
         if self.decoder:

docs/PIL.rst

@@ -76,14 +76,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageFile` Module
------------------------
-
-.. automodule:: PIL.ImageFile
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImageFileIO` Module
 -------------------------
 

docs/reference/ImageFile.rst

@@ -0,0 +1,41 @@
+.. py:module:: PIL.ImageFile
+.. py:currentmodule:: PIL.ImageFile
+
+:mod:`ImageFile` Module
+=======================
+
+The :py:mod:`ImageFile` module provides support functions for the image open
+and save functions.
+
+In addition, it provides a :py:class:`Parser` class which can be used to decode
+an image piece by piece (e.g. while receiving it over a network connection).
+This class implements the same consumer interface as the standard **sgmllib**
+and **xmllib** modules.
+
+Example: Parse an image
+-----------------------
+
+.. code-block:: python
+
+    from PIL import ImageFile
+
+    fp = open("lena.pgm", "rb")
+
+    p = ImageFile.Parser()
+
+    while 1:
+        s = fp.read(1024)
+        if not s:
+            break
+        p.feed(s)
+
+    im = p.close()
+
+    im.save("copy.jpg")
+
+
+:py:class:`~PIL.ImageFile.Parser`
+---------------------------------
+
+.. autoclass:: PIL.ImageFile.Parser()
+    :members:

docs/reference/index.rst

@@ -9,4 +9,5 @@ Reference
    ImageColor
    ImageDraw
    ImageEnhance
+   ImageFile
    ../PIL