From 21972c4601378fcad28cbc63466775b76d6a888a Mon Sep 17 00:00:00 2001
From: Gary Wu <garywu@live.com>
Date: Wed, 1 Mar 2017 13:04:11 -0600
Subject: [PATCH] fix #3902 Add proposed documentation change for post data

---
 AUTHORS.rst              |  2 +-
 docs/user/quickstart.rst | 41 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index e4a325bf..6ab65ffe 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -179,4 +179,4 @@ Patches and Suggestions
 - Matt Kohl (`@mattkohl <https://github.com/mattkohl>`_)
 - Jonathan Vanasco (`@jvanasco <https://github.com/jvanasco>`_)
 - David Fontenot (`@davidfontenot <https://github.com/davidfontenot>`_)
-
+- Gary Wu (`@garywu <https://github.com/garywu>`_)
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
index 60cc73fb..156fd15d 100644
--- a/docs/user/quickstart.rst
+++ b/docs/user/quickstart.rst
@@ -234,6 +234,45 @@ dictionary of data will automatically be form-encoded when the request is made::
       ...
     }
 
+You can also pass a list of tuples to the ``data`` argument. This is particularly
+useful when the form has multiple elements that use the same key::
+
+    >>> payload = (('key1', 'value1'), ('key1', 'value2'))
+    >>> r = requests.post('http://httpbin.org/post', data=payload)
+    >>> print(r.text)
+    {
+      ...
+      "form": {
+        "key1": [
+          "value1",
+          "value2"
+        ]
+      },
+      ...
+    }
+
+Value of each payload element can be a scalar or an iterable::
+
+    >>> payload = (('key1', ('value1', 1, (1, 2))), {'key2', ('value2', 2)})
+    >>> r = requests.post('http://httpbin.org/post', data=payload)
+    >>> print(r.text)
+    {
+      ...
+      "form": {
+        "key1": [
+          "value1",
+          "1",
+          "1",
+          "2"
+        ],
+        "key2": [
+          "value2",
+          "2"
+        ]
+      },
+      ...
+    }
+
 There are many times that you want to send data that is not form-encoded. If
 you pass in a ``string`` instead of a ``dict``, that data will be posted directly.
 
@@ -485,7 +524,7 @@ Timeouts
 --------
 
 You can tell Requests to stop waiting for a response after a given number of
-seconds with the ``timeout`` parameter. Nearly all production code should use 
+seconds with the ``timeout`` parameter. Nearly all production code should use
 this parameter in nearly all requests. Failure to do so can cause your program
 to hang indefinitely::