Fixed #17671 - Cursors are now context managers.

2 files changed, 46 insertions, 0 deletions

diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 6a29635d18..8dc17761b9 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -111,6 +111,25 @@ In addition, the widgets now display a help message when the browser and
 server time zone are different, to clarify how the value inserted in the field
 will be interpreted.
 
+Using database cursors as context managers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prior to Python 2.7, database cursors could be used as a context manager. The
+specific backend's cursor defined the behavior of the context manager. The
+behavior of magic method lookups was changed with Python 2.7 and cursors were
+no longer usable as context managers.
+
+Django 1.7 allows a cursor to be used as a context manager that is a shortcut
+for the following, instead of backend specific behavior.
+
+.. code-block:: python
+
+    c = connection.cursor()
+    try:
+        c.execute(...)
+    finally:
+        c.close()
+
 Minor features
 ~~~~~~~~~~~~~~
 
diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index 7437d51d28..1369ed84f5 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -297,3 +297,30 @@ database library will automatically escape your parameters as necessary.
 Also note that Django expects the ``"%s"`` placeholder, *not* the ``"?"``
 placeholder, which is used by the SQLite Python bindings. This is for the sake
 of consistency and sanity.
+
+.. versionchanged:: 1.7
+
+:pep:`249` does not state whether a cursor should be usable as a context
+manager. Prior to Python 2.7, a cursor was usable as a context manager due
+an unexpected behavior in magic method lookups (`Python ticket #9220`_).
+Django 1.7 explicitly added support to allow using a cursor as context
+manager.
+
+.. _`Python ticket #9220`: http://bugs.python.org/issue9220
+
+Using a cursor as a context manager:
+
+.. code-block:: python
+
+    with connection.cursor() as c:
+        c.execute(...)
+
+is equivalent to:
+
+.. code-block:: python
+
+    c = connection.cursor()
+    try:
+        c.execute(...)
+    finally:
+        c.close()
\ No newline at end of file