From 8c6a4c0299f33aa05ddba19041d15b4c10684095 Mon Sep 17 00:00:00 2001
From: wiredfool <eric-github@soroos.net>
Date: Thu, 17 Apr 2014 21:53:49 -0700
Subject: [PATCH] Docs changes for close/context manager

---
 PIL/Image.py               | 27 ++++++++++++++++++---------
 docs/handbook/tutorial.rst |  4 ++--
 docs/reference/Image.rst   |  2 +-
 3 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/PIL/Image.py b/PIL/Image.py
index 99acb78fa..333397701 100644
--- a/PIL/Image.py
+++ b/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
diff --git a/docs/handbook/tutorial.rst b/docs/handbook/tutorial.rst
index 9ce50da7d..05d619f40 100644
--- a/docs/handbook/tutorial.rst
+++ b/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
 
diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst
index fe13c882b..7125fcad4 100644
--- a/docs/reference/Image.rst
+++ b/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
 ----------