Support quoting list values in mappings

CHANGES/443.feature

@@ -0,0 +1,6 @@
+These changes fix https://github.com/aio-libs/aiohttp/issues/4714, that is,
+we now support the use of lists and tuples when quoting mappings such as
+Python's builtin dict. As an example from the tests:
+
+    url = URL("http://example.com")
+    assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")

docs/api.rst

@@ -547,6 +547,9 @@ section generates a new *URL* instance.
 
       The library accepts :class:`str` and :class:`int` as query argument values.
 
+      If a mapping such as :class:`dict` is used, the values may also be
+      :class:`list` or :class:`tuple` to represent a key has many values.
+
       Please see :ref:`yarl-bools-support` for the reason why :class:`bool` is not
       supported out-of-the-box.
 
@@ -556,6 +559,8 @@ section generates a new *URL* instance.
       URL('http://example.com/path?c=d')
       >>> URL('http://example.com/path?a=b').with_query({'c': 'd'})
       URL('http://example.com/path?c=d')
+      >>> URL('http://example.com/path?a=b').with_query({'c': [1, 2]})
+      URL('http://example.com/path?c=1&c=2')
       >>> URL('http://example.com/path?a=b').with_query({'кл': 'зн'})
       URL('http://example.com/path?%D0%BA%D0%BB=%D0%B7%D0%BD')
       >>> URL('http://example.com/path?a=b').with_query(None)
@@ -591,6 +596,9 @@ section generates a new *URL* instance.
 
       The library accepts :class:`str` and :class:`int` as query argument values.
 
+      If a mapping such as :class:`dict` is used, the values may also be
+      :class:`list` or :class:`tuple` to represent a key has many values.
+
       Please see :ref:`yarl-bools-support` for the reason why :class:`bool` is not
       supported out-of-the-box.
 
@@ -600,6 +608,8 @@ section generates a new *URL* instance.
       URL('http://example.com/path?a=b&c=d')
       >>> URL('http://example.com/path?a=b').update_query({'c': 'd'})
       URL('http://example.com/path?a=b&c=d')
+      >>> URL('http://example.com/path?a=b').update_query({'c': [1, 2]})
+      URL('http://example.com/path?a=b&c=1&c=2')
       >>> URL('http://example.com/path?a=b').update_query({'кл': 'зн'})
       URL('http://example.com/path?a=b&%D0%BA%D0%BB=%D0%B7%D0%BD')
       >>> URL('http://example.com/path?a=b&b=1').update_query(b='2')

tests/test_update_query.py

@@ -117,6 +117,45 @@ def test_with_query_list_int():
     assert str(url.with_query([("a", 1)])) == "http://example.com/?a=1"
 
 
+def test_with_query_sequence():
+    url = URL("http://example.com")
+    assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")
+
+
+def test_with_query_sequence_tuple():
+    url = URL("http://example.com")
+    assert url.with_query({"a": (1, 2)}) == URL("http://example.com/?a=1&a=2")
+
+
+def test_with_query_sequence_mixed_types():
+    url = URL("http://example.com")
+    assert url.with_query({"a": ["1", 2]}) == URL("http://example.com/?a=1&a=2")
+
+
+def test_with_query_sequence_single_then_list():
+    url = URL("http://example.com")
+    expected = URL("http://example.com/?a=1&b=2&b=3")
+    assert url.with_query({"a": 1, "b": [2, 3]}) == expected
+
+
+def test_with_query_sequence_list_then_single():
+    url = URL("http://example.com")
+    expected = URL("http://example.com/?a=1&a=2&b=3")
+    assert url.with_query({"a": [1, 2], "b": 3}) == expected
+
+
+def test_with_query_sequence_nested_sequence():
+    url = URL("http://example.com")
+    with pytest.raises(TypeError):
+        url.with_query({"a": [[1]]})
+
+
+def test_with_query_sequence_using_pairs():
+    url = URL("http://example.com")
+    with pytest.raises(TypeError):
+        url.with_query([("a", [1, 2])])
+
+
 def test_with_query_non_str():
     url = URL("http://example.com")
     with pytest.raises(TypeError):

yarl/__init__.py

@@ -852,6 +852,15 @@ def with_path(self, path, *, encoded=False):
             path = "/" + path
         return URL(self._val._replace(path=path, query="", fragment=""), encoded=True)
 
+    @classmethod
+    def _query_seq_pairs(cls, quoter, pairs):
+        for key, val in pairs:
+            if isinstance(val, (list, tuple)):
+                for v in val:
+                    yield quoter(key) + "=" + quoter(cls._query_var(v))
+            else:
+                yield quoter(key) + "=" + quoter(cls._query_var(val))
+
     @staticmethod
     def _query_var(v):
         if isinstance(v, str):
@@ -882,9 +891,7 @@ def _get_str_query(self, *args, **kwargs):
             query = ""
         elif isinstance(query, Mapping):
             quoter = self._QUERY_PART_QUOTER
-            query = "&".join(
-                quoter(k) + "=" + quoter(self._query_var(v)) for k, v in query.items()
-            )
+            query = "&".join(self._query_seq_pairs(quoter, query.items()))
         elif isinstance(query, str):
             query = self._QUERY_QUOTER(query)
         elif isinstance(query, (bytes, bytearray, memoryview)):
@@ -893,6 +900,10 @@ def _get_str_query(self, *args, **kwargs):
             )
         elif isinstance(query, Sequence):
             quoter = self._QUERY_PART_QUOTER
+            # We don't expect sequence values if we're given a list of pairs
+            # already; only mappings like builtin `dict` which can't have the
+            # same key pointing to multiple values are allowed to use
+            # `_query_seq_pairs`.
             query = "&".join(
                 quoter(k) + "=" + quoter(self._query_var(v)) for k, v in query
             )