Fixed #18744 -- Updated docstring to highlight limitations of NamedTemporaryFile

- Noted that this does not allow for reading and writing the same open
file in different processes under Windows.
- Noted that the keyword arguments to NamedTemporaryFile no longer
match the Python version.

1 files changed, 21 insertions, 10 deletions

diff --git a/django/core/files/temp.py b/django/core/files/temp.py
index 3dcda17a09..58fbd231dc 100644
--- a/django/core/files/temp.py
+++ b/django/core/files/temp.py
@@ -1,12 +1,19 @@
 """
-The temp module provides a NamedTemporaryFile that can be re-opened on any
-platform. Most platforms use the standard Python tempfile.TemporaryFile class,
-but MS Windows users are given a custom class.
+The temp module provides a NamedTemporaryFile that can be reopened in the same
+process on any platform. Most platforms use the standard Python
+tempfile.NamedTemporaryFile class, but Windows users are given a custom class.
 
-This is needed because in Windows NT, the default implementation of
-NamedTemporaryFile uses the O_TEMPORARY flag, and thus cannot be reopened [1].
+This is needed because the Python implementation of NamedTemporaryFile uses the
+O_TEMPORARY flag under Windows, which prevents the file from being reopened
+if the same flag is not provided [1][2]. Note that this does not address the
+more general issue of opening a file for writing and reading in multiple
+processes in a manner that works across platforms.
 
-1: http://mail.python.org/pipermail/python-list/2005-December/359474.html
+Also note that the custom version of NamedTemporaryFile does not support the
+full range of keyword arguments available in Python 2.6+ and 3.0+.
+
+1: https://mail.python.org/pipermail/python-list/2005-December/336958.html
+2: http://bugs.python.org/issue14243
 """
 
 import os
@@ -15,16 +22,20 @@ from django.core.files.utils import FileProxyMixin
 
 __all__ = ('NamedTemporaryFile', 'gettempdir',)
 
+
 if os.name == 'nt':
     class TemporaryFile(FileProxyMixin):
         """
-        Temporary file object constructor that works in Windows and supports
-        reopening of the temporary file in windows.
+        Temporary file object constructor that supports reopening of the
+        temporary file in Windows.
+
+        Note that __init__() does not support the 'delete' keyword argument in
+        Python 2.6+, or the 'delete', 'buffering', 'encoding', or 'newline'
+        keyword arguments in Python 3.0+.
         """
         def __init__(self, mode='w+b', bufsize=-1, suffix='', prefix='',
                 dir=None):
-            fd, name = tempfile.mkstemp(suffix=suffix, prefix=prefix,
-                                          dir=dir)
+            fd, name = tempfile.mkstemp(suffix=suffix, prefix=prefix, dir=dir)
             self.name = name
             self.file = os.fdopen(fd, mode, bufsize)
             self.close_called = False