Docs changes for close/context manager

PIL/Image.py

@@ -497,16 +497,23 @@ class Image:
 
     _makeself = _new # compatibility
 
-    # with compatibility
+    # Context Manager Support
     def __enter__(self):
         return self
     def __exit__(self, *args):
         self.close()
         
     def close(self):
-        """ Close the file pointer, if possible. Destroy the image core.
-            This releases memory, and the image will be unusable afterward
-            """
+        """
+        Closes the file pointer, if possible.
+
+        This operation will destroy the image core and release it's memory.
+        The image data will be unusable afterward.
+
+        This function is only required to close images that have not
+        had their file read and closed by the
+        :py:meth:`~PIL.Image.Image.load` method.
+        """
         try:
             self.fp.close()
         except Exception as msg:
@@ -664,7 +671,8 @@ class Image:
         Allocates storage for the image and loads the pixel data.  In
         normal cases, you don't need to call this method, since the
         Image class automatically loads an opened image when it is
-        accessed for the first time.
+        accessed for the first time. This method will close the file
+        associated with the image. 
 
         :returns: An image access object.
         """
@@ -2096,10 +2104,11 @@ def open(fp, mode="r"):
     """
     Opens and identifies the given image file.
 
-    This is a lazy operation; this function identifies the file, but the
-    actual image data is not read from the file until you try to process
-    the data (or call the :py:meth:`~PIL.Image.Image.load` method).
-    See :py:func:`~PIL.Image.new`.
+    This is a lazy operation; this function identifies the file, but
+    the file remains open and the actual image data is not read from
+    the file until you try to process the data (or call the
+    :py:meth:`~PIL.Image.Image.load` method).  See
+    :py:func:`~PIL.Image.new`.
 
     :param file: A filename (string) or a file object.  The file object
        must implement :py:meth:`~file.read`, :py:meth:`~file.seek`, and

docs/handbook/tutorial.rst

@@ -126,8 +126,8 @@ Identify Image Files
 
     for infile in sys.argv[1:]:
         try:
-            im = Image.open(infile)
-            print(infile, im.format, "%dx%d" % im.size, im.mode)
+            with Image.open(infile) as im:
+                print(infile, im.format, "%dx%d" % im.size, im.mode)
         except IOError:
             pass
 

docs/reference/Image.rst

@@ -136,9 +136,9 @@ ITU-R 709, using the D65 luminant) to the CIE XYZ color space:
 .. automethod:: PIL.Image.Image.verify
 
 .. automethod:: PIL.Image.Image.fromstring
-.. deprecated:: 2.0
 
 .. automethod:: PIL.Image.Image.load
+.. automethod:: PIL.Image.Image.close
 
 Attributes
 ----------