Document the ability to pass lists of kv pairs to url-concat.

Closes #1216.

diff --git a/tornado/httputil.py b/tornado/httputil.py
index 126db40e3b589353cb848f363a1f48a8b4718b52..f5c9c04fea3e197dafaca2329a797b7ee311fb4a 100644 (file)
--- a/tornado/httputil.py
+++ b/tornado/httputil.py
@@ -562,11 +562,18 @@ class HTTPConnection(object):
 
 
 def url_concat(url, args):
-    """Concatenate url and argument dictionary regardless of whether
+    """Concatenate url and arguments regardless of whether
     url has existing query parameters.
 
+    ``args`` may be either a dictionary or a list of key-value pairs
+    (the latter allows for multiple values with the same key.
+
+    >>> url_concat("http://example.com/foo", dict(c="d"))
+    'http://example.com/foo?c=d'
     >>> url_concat("http://example.com/foo?a=b", dict(c="d"))
     'http://example.com/foo?a=b&c=d'
+    >>> url_concat("http://example.com/foo?a=b", [("c", "d"), ("c", "d2")])
+    'http://example.com/foo?a=b&c=d&c=d2'
     """
     if not args:
         return url