Merge branch 'master' into excuse-my-french

Author: mahmoud

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## dev (not yet released)
 
+* Also accept dictionaries as ‘query=’ arguments (see #50)
+
 ## 17.3.1
 
 *(August 19, 2017)*

README.md

@@ -32,10 +32,10 @@ Then, hyperlink away!
 ```python
 from hyperlink import URL
 
-url = URL.from_text('http://github.com/mahmoud/hyperlink?utm_source=README')
-utm_source = url.get('utm_source')
-better_url = url.replace(scheme='https')
-user_url = better_url.click('..')
+url = URL.from_text(u'http://github.com/mahmoud/hyperlink?utm_source=README')
+utm_source = url.get(u'utm_source')
+better_url = url.replace(scheme=u'https')
+user_url = better_url.click(u'..')
 ```
 
 See the full API docs on [Read the Docs][docs].

docs/design.rst

@@ -92,6 +92,14 @@ by the query parameters, sometimes called "query arguments" or "GET
 parameters". Regardless of what you call them, they are encoded in
 the query string portion of the URL, and they are very powerful.
 
+In the simplest case, these query parameters can be provided as a
+dictionary:
+
+   >>> url = URL.from_text('http://example.com/')
+   >>> url = url.replace(query={'a': 'b', 'c': 'd'})
+   >>> url.to_text()
+   u'http://example.com/?a=b&c=d'
+
 Query parameters are actually a type of "multidict", where a given key
 can have multiple values. This is why the :meth:`~URL.get()` method
 returns a list of strings. Keys can also have no value, which is

docs/index.rst

@@ -10,7 +10,7 @@ hyperlink
 URLs. Based on `RFC 3986`_ and `RFC 3987`_, the Hyperlink URL balances
 simplicity and correctness for both :ref:`URIs and IRIs <uris_and_iris>`.
 
-Hyperlink is tested against Python 2.7, 3.4, 3.5, and PyPy.
+Hyperlink is tested against Python 2.7, 3.4, 3.5, 3.6, and PyPy.
 
 For an introduction to the hyperlink library, its background, and URLs
 in general, see `this talk from PyConWeb 2017`_ (and `the accompanying

hyperlink/_url.py

@@ -16,9 +16,15 @@
 """
 
 import re
+import sys
 import string
 import socket
 from unicodedata import normalize
+
+try:
+    from collections.abc import Mapping
+except ImportError:  # Python 2
+    from collections import Mapping
 try:
     from socket import inet_pton
 except ImportError:
@@ -52,6 +58,7 @@ def inet_pton(address_family, ip_string):
         raise socket.error('unknown address family')
 
 
+PY2 = (sys.version_info[0] == 2)
 unicode = type(u'')
 try:
     unichr
@@ -425,7 +432,7 @@ def _textcheck(name, value, delims=frozenset(), nullable=False):
         if nullable and value is None:
             return value  # used by query string values
         else:
-            str_name = "unicode" if bytes is str else "str"
+            str_name = "unicode" if PY2 else "str"
             exp = str_name + ' or NoneType' if nullable else str_name
             raise TypeError('expected %s for %s, got %r' % (exp, name, value))
     if delims and set(value) & set(delims):  # TODO: test caching into regexes
@@ -434,6 +441,19 @@ def _textcheck(name, value, delims=frozenset(), nullable=False):
     return value
 
 
+def iter_pairs(iterable):
+    """
+    Iterate over the (key, value) pairs in ``iterable``.
+
+    This handles dictionaries sensibly, and falls back to assuming the
+    iterable yields (key, value) pairs. This behaviour is similar to
+    what Python's ``dict()`` constructor does.
+    """
+    if isinstance(iterable, Mapping):
+        iterable = iterable.items()
+    return iter(iterable)
+
+
 def _decode_unreserved(text, normalize_case=False):
     return _percent_decode(text, normalize_case=normalize_case,
                            _decode_map=_UNRESERVED_DECODE_MAP)
@@ -639,8 +659,8 @@ class URL(object):
           for more info.
        path (tuple): A tuple of strings representing the
           slash-separated parts of the path.
-       query (tuple): The query parameters, as a tuple of
-          key-value pairs.
+       query (tuple): The query parameters, as a dictionary or
+          as an iterable of key-value pairs.
        fragment (unicode): The fragment part of the URL.
        rooted (bool): Whether or not the path begins with a slash.
        userinfo (unicode): The username or colon-separated
@@ -695,8 +715,7 @@ def __init__(self, scheme=None, host=None, path=(), query=(), fragment=u'',
         self._query = tuple(
             (_textcheck("query parameter name", k, '&=#'),
              _textcheck("query parameter value", v, '&#', nullable=True))
-            for (k, v) in query
-        )
+            for k, v in iter_pairs(query))
         self._fragment = _textcheck("fragment", fragment)
         self._port = _typecheck("port", port, int, NoneType)
         self._rooted = _typecheck("rooted", rooted, bool)
@@ -912,6 +931,8 @@ def replace(self, scheme=_UNSET, host=_UNSET, path=_UNSET, query=_UNSET,
               slash-separated parts of the path.
            query (tuple): The query parameters, as a tuple of
               key-value pairs.
+           query (tuple): The query parameters, as a dictionary or
+              as an iterable of key-value pairs.
            fragment (unicode): The fragment part of the URL.
            rooted (bool): Whether or not the path begins with a slash.
            userinfo (unicode): The username or colon-separated

hyperlink/test/test_url.py

@@ -742,10 +742,14 @@ def test_mailto(self):
     def test_queryIterable(self):
         """
         When a L{URL} is created with a C{query} argument, the C{query}
-        argument is converted into an N-tuple of 2-tuples.
+        argument is converted into an N-tuple of 2-tuples, sensibly
+        handling dictionaries.
         """
+        expected = (('alpha', 'beta'),)
         url = URL(query=[['alpha', 'beta']])
-        self.assertEqual(url.query, (('alpha', 'beta'),))
+        self.assertEqual(url.query, expected)
+        url = URL(query={'alpha': 'beta'})
+        self.assertEqual(url.query, expected)
 
     def test_pathIterable(self):
         """