Clarify docs for multipart file uploads

docs/user/advanced.rst

@@ -386,13 +386,13 @@ parameter of ``None``. If you want to set a maximum size of the chunk,
 you can set a ``chunk_size`` parameter to any integer.
 
 
-.. _multipart:
+.. _multiple_multipart_files_same_field:
 
-POST Multiple Multipart-Encoded Files
--------------------------------------
+POST Multiple Multipart-Encoded Files to the Same Field
+-------------------------------------------------------
 
-You can send multiple files in one request. For example, suppose you want to
-upload image files to an HTML form with a multiple file field 'images'::
+You can send multiple files to the same form field in one request. For example, suppose you want to
+upload image files to an HTML form with a multiple-file field 'images'::
 
     <input type="file" name="images" multiple="true" required="true"/>
 

docs/user/quickstart.rst

@@ -297,6 +297,9 @@ and it will be encoded automatically:
 
 Note, the ``json`` parameter is ignored if either ``data`` or ``files`` is passed.
 
+
+.. _multipart_file:
+
 POST a Multipart-Encoded File
 -----------------------------
 
@@ -351,8 +354,8 @@ support this, but there is a separate package which does -
 ``requests-toolbelt``. You should read `the toolbelt's documentation
 <https://toolbelt.readthedocs.io>`_ for more details about how to use it.
 
-For sending multiple files in one request refer to the :ref:`advanced <advanced>`
-section.
+For sending multiple files to the same form field in one request, refer to
+:ref:`multiple_multipart_files_same_field`.
 
 .. warning:: It is strongly recommended that you open files in :ref:`binary
              mode <tut-files>`. This is because Requests may attempt to provide

requests/api.py

@@ -23,11 +23,25 @@ def request(method, url, **kwargs):
     :param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
     :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
     :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``) for multipart encoding upload.
-        ``file-tuple`` can be a 2-tuple ``('filename', fileobj)``, 3-tuple ``('filename', fileobj, 'content_type')``
-        or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``, where ``'content-type'`` is a string
-        defining the content type of the given file and ``custom_headers`` a dict-like object containing additional headers
-        to add for the file.
+    :param files: (optional) For uploading files with ``multipart/form-data`` encoding,
+        either a dictionary of ``'field_name': file_info`` items,
+        or a list of ``('field_name', file_info)`` tuples. Each ``file_info`` can be:
+
+        * A ``file_obj``.
+        * A 2-tuple ``('filename', file_obj)``.
+        * A 3-tuple ``('filename', file_obj, 'content_type')``.
+        * A 4-tuple ``('filename', file_obj, 'content_type', custom_headers)``.
+
+        Where:
+
+        * ``file_obj`` is a binary-mode file-like object to read the file contents from.
+          or a ``str`` or ``bytes`` containing the file contents.
+        * ``'content_type'`` is a string defining the content type of the given file.
+        * ``custom_headers`` is a dict-like object containing additional headers
+          to add for the file.
+
+        For an example of the dict syntax, see :ref:`multipart_file`.
+        For an example of the list-of-tuples syntax, see :ref:`multiple_multipart_files_same_field`.
     :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
     :param timeout: (optional) How many seconds to wait for the server to send data
         before giving up, as a float, or a :ref:`(connect timeout, read