Add reliable file transfer helpers

README.rst

@@ -57,8 +57,44 @@ We provide `Examples`_ to help get you started with a lot of the basic functiona
     - `Commandline OAuth PKCE <https://github.com/dropbox/dropbox-sdk-python/blob/main/example/oauth/commandline-oauth-pkce.py>`_ - Shows a simple example of commandline oauth using PKCE.
 - **Other Examples**
     - `Updown <https://github.com/dropbox/dropbox-sdk-python/blob/main/example/updown.py>`_ - Sample application that uploads the contents of your ``Downloads`` folder to Dropbox.
+    - `Reliable file transfer <https://github.com/dropbox/dropbox-sdk-python/blob/main/example/file_transfer.py>`_ - Downloads and uploads files with retry, progress, and content validation helpers.
     - `Backup and Restore <https://github.com/dropbox/dropbox-sdk-python/tree/main/example/back-up-and-restore>`_ - Sample application that shows how you can backup a file and restore previous versions if the file was modified/corrupted in any way.
 
+Reliable File Transfers
+=======================
+
+Use ``dropbox.file_transfer`` when copying Dropbox files to or from local
+storage and you want retry, progress, validation, byte/file targets, stream/file
+sources, and optional parallel ranged transfers around the generated
+``files_*`` methods.
+
+.. code-block:: python
+
+    import dropbox
+    from dropbox import files
+    from dropbox.file_transfer import (
+        DownloadOptions,
+        File,
+        FileUpload,
+        Uploader,
+        UploadOptions,
+        Downloader,
+    )
+
+    dbx = dropbox.Dropbox("YOUR_ACCESS_TOKEN")
+
+    Downloader(dbx).download(
+        "/large-file.bin",
+        File("large-file.bin"),
+        DownloadOptions(parallel_downloads=4),
+    )
+
+    Uploader(dbx).upload(
+        FileUpload("large-file.bin"),
+        files.CommitInfo("/large-file.bin", mode=files.WriteMode.overwrite),
+        UploadOptions(parallel_uploads=4),
+    )
+
 Getting Help
 ============
 

docs/api/file_transfer.rst

@@ -0,0 +1,5 @@
+:mod:`dropbox.file_transfer` -- Reliable file transfers
+=======================================================
+.. automodule:: dropbox.file_transfer
+   :members:
+   :show-inheritance:

docs/index.rst

@@ -15,6 +15,7 @@ Dropbox for Python Documentation
    api/contacts
    api/dropbox
    api/exceptions
+   api/file_transfer
    api/file_properties
    api/file_requests
    api/files

dropbox/base.py

@@ -1520,13 +1520,16 @@ def files_download(self, path, rev=None, extra_headers=None):
         context manager to ensure this.
         """
         arg = files.DownloadArg(path, rev)
-        r = self.request(
-            files.download,
-            "files",
-            arg,
-            None,
-            extra_headers=extra_headers,
-        )
+        if extra_headers is None:
+            r = self.request(files.download, "files", arg, None)
+        else:
+            r = self.request(
+                files.download,
+                "files",
+                arg,
+                None,
+                extra_headers=extra_headers,
+            )
         return r
 
     def files_download_to_file(self, download_path, path, rev=None, extra_headers=None):
@@ -1550,13 +1553,16 @@ def files_download_to_file(self, download_path, path, rev=None, extra_headers=No
             :class:`dropbox.files.DownloadError`
         """
         arg = files.DownloadArg(path, rev)
-        r = self.request(
-            files.download,
-            "files",
-            arg,
-            None,
-            extra_headers=extra_headers,
-        )
+        if extra_headers is None:
+            r = self.request(files.download, "files", arg, None)
+        else:
+            r = self.request(
+                files.download,
+                "files",
+                arg,
+                None,
+                extra_headers=extra_headers,
+            )
         self._save_body_to_file(download_path, r[1])
         return r[0]