Tweak DownloadCodec tempfile behavior slightly

Author: tomchristie

coreapi/codecs/download.py

@@ -5,11 +5,12 @@
 import mimetypes
 import os
 import posixpath
-import shutil
 import tempfile
 
 
 class DownloadedFile(tempfile._TemporaryFileWrapper):
+    basename = None
+
     def __repr__(self):
         state = "closed" if self.close_called else "open"
         mode = "" if self.close_called else " '%s'" % self.file.mode
@@ -98,6 +99,8 @@ def _get_filename(base_url=None, content_type=None, content_disposition=None):
         filename = _get_filename_from_content_disposition(content_disposition)
     if base_url and not filename:
         filename = _get_filename_from_url(base_url, content_type)
+    if not filename:
+        return None  # Ensure empty filenames return as `None` for consistency.
     return filename
 
 
@@ -111,17 +114,11 @@ def __init__(self, download_dir=None):
         """
         `download_dir` - The path to use for file downloads.
         """
-        self._temporary = download_dir is None
+        self._delete_on_close = download_dir is None
         self._download_dir = download_dir
 
-    def __del__(self):
-        if self._temporary and self._download_dir:
-            shutil.rmtree(self._download_dir)
-
     @property
     def download_dir(self):
-        if self._download_dir is None:
-            self._download_dir = tempfile.mkdtemp(prefix='temp-coreapi-download-')
         return self._download_dir
 
     def decode(self, bytestring, **options):
@@ -137,15 +134,21 @@ def decode(self, bytestring, **options):
 
         # Determine the output filename.
         output_filename = _get_filename(base_url, content_type, content_disposition)
-        if not output_filename:
-            # Fallback if no output filename could be determined.
+        if output_filename is None:
             output_filename = os.path.basename(temp_path)
 
+        # Determine the output directory.
+        output_dir = self._download_dir
+        if output_dir is None:
+            output_dir = os.path.dirname(temp_path)
+
         # Determine the full output path.
-        output_path = os.path.join(self.download_dir, output_filename)
+        output_path = os.path.join(output_dir, output_filename)
         output_path = _unique_output_path(output_path)
 
         # Move the temporary download file to the final location.
         os.rename(temp_path, output_path)
         output_file = open(output_path, 'rb')
-        return DownloadedFile(output_file, output_path, delete=self._temporary)
+        downloaded = DownloadedFile(output_file, output_path, delete=self._delete_on_close)
+        downloaded.basename = output_filename
+        return downloaded

coreapi/transports/http.py

@@ -88,6 +88,7 @@ def _get_params(method, encoding, fields, params=None):
     if errors:
         raise exceptions.ValidationError(errors)
 
+    # Move any files from 'data' into 'files'.
     if isinstance(data, dict):
         for key, value in list(data.items()):
             if is_file(data[key]):

docs/api-guide/codecs.md

@@ -129,18 +129,31 @@ Example:
 
 ### DownloadCodec
 
-Supports decoding arbitrary media as a download file. Returns a temporary file
+Supports decoding arbitrary media as a download file. Returns a [temporary file][tempfile]
 that will be deleted once it goes out of scope.
 
 **.media_type**: `*/*`
 
 Example:
 
-    >>> from coreapi import codecs
     >>> codec = codecs.DownloadCodec()
-    >>> data = codec.decode(b'...')
-    >>> print(data)
+    >>> download = codec.decode(b'abc...xyz')
+    >>> print(download)
     <DownloadedFile '.../tmpYbxNXT.download', open 'rb'>
+    >>> content = download.read()
+    >>> print(content)
+    abc...xyz
+
+The download filename will be determined by either the `Content-Disposition`
+header, or based on the request URL and the `Content-Type` header. Download
+collisions are avoided by using incrementing filenames where required.
+The original name used for the download file can be inspected using `.basename`.
+
+    >>> download = codec.decode(b'abc...xyz', content_type='image/png', base_url='http://example.com/download/')
+    >>> download.name
+    '/var/folders/2k/qjf3np5s28zf2f58963pz2k40000gn/T/download.png'
+    >>> download.basename
+    'download.png'
 
 #### Instantiation
 
@@ -233,6 +246,7 @@ A codec for the [HAL][hal] hypermedia format. Installable [from PyPI][hal-pypi]
 
 [content-disposition-filename]: https://tools.ietf.org/html/draft-ietf-httpbis-content-disp-00#section-3.3
 [click-ansi]: http://click.pocoo.org/5/utils/#ansi-colors
+[tempfile]: https://docs.python.org/3/library/tempfile.html#tempfile.TemporaryFile
 
 [openapi]: https://openapis.org/specification
 [openapi-pypi]: https://pypi.python.org/pypi/openapi-codec