allow to update query string using mod operator (#435)

* allow to update query string using mod operator

Co-authored-by: Andrew Svetlov <[email protected]>

Author: vanyakosmos

CHANGES/435.feature

@@ -0,0 +1 @@
+Allow using `mod` operator (`%`) for updating query string (an alias for `update_query()` method).

README.rst

@@ -57,8 +57,11 @@ All url manipulations produce a new url object:
 
 .. code-block:: pycon
 
-   >>> url.parent / 'downloads/source'
-   URL('https://www.python.org/downloads/source')
+   >>> url = URL('https://www.python.org')
+   >>> url / 'foo' / 'bar'
+   URL('https://www.python.org/foo/bar')
+   >>> url / 'foo' % {'bar': 'baz'}
+   URL('https://www.python.org/foo?bar=baz')
 
 Strings passed to constructor and modification methods are
 automatically encoded giving canonical representation as result:

docs/api.rst

@@ -592,6 +592,9 @@ section generates a new *URL* instance.
 
    Clear *query* if ``None`` is passed.
 
+   Mod operator (``%``) can be used as alternative to the direct call of
+   :meth:`URL.update_query`.
+
    .. note::
 
       The library accepts :class:`str` and :class:`int` as query argument values.
@@ -620,6 +623,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&c=f')
       URL('http://example.com/path?a=b&c=d&c=f')
+      >>> URL('http://example.com/path?a=b') % {'c': 'd'}
+      URL('http://example.com/path?a=b&c=d')
 
    .. versionchanged:: 1.0
 

docs/index.rst

@@ -46,6 +46,16 @@ All URL manipulations produces a new URL object:
    >>> url.parent / 'downloads/source'
    URL('https://www.python.org/downloads/source')
 
+A URL object can be modified with ``/`` and ``%`` operators:
+
+.. doctest::
+
+   >>> url = URL('https://www.python.org')
+   >>> url / 'foo' / 'bar'
+   URL('https://www.python.org/foo/bar')
+   >>> url / 'foo' % {'bar': 'baz'}
+   URL('https://www.python.org/foo?bar=baz')
+
 Strings passed to constructor and modification methods are
 automatically encoded giving canonical representation as result:
 

tests/test_update_query.py

@@ -268,3 +268,16 @@ def test_update_query_multiple_keys():
     u2 = url.update_query([("a", "3"), ("a", "4")])
 
     assert str(u2) == "http://example.com/path?a=3&a=4"
+
+
+# mod operator
+
+
+def test_update_query_with_mod_operator():
+    url = URL("http://example.com/")
+    assert str(url % {"a": "1"}) == "http://example.com/?a=1"
+    assert str(url % [("a", "1")]) == "http://example.com/?a=1"
+    assert str(url % "a=1&b=2") == "http://example.com/?a=1&b=2"
+    assert str(url % {"a": "1"} % {"b": "2"}) == "http://example.com/?a=1&b=2"
+    assert str(url % {"a": "1"} % {"a": "3", "b": "2"}) == "http://example.com/?a=3&b=2"
+    assert str(url / "foo" % {"a": "1"}) == "http://example.com/foo?a=1"

yarl/__init__.py

@@ -308,6 +308,9 @@ def __truediv__(self, name):
             self._val._replace(path=new_path, query="", fragment=""), encoded=True
         )
 
+    def __mod__(self, query):
+        return self.update_query(query)
+
     def __bool__(self) -> bool:
         return bool(
             self._val.netloc or self._val.path or self._val.query or self._val.fragment

yarl/__init__.pyi

@@ -56,6 +56,7 @@ class URL:
     def __gt__(self, other: Any) -> bool: ...
     def __hash__(self) -> int: ...
     def __truediv__(self, name: str) -> URL: ...
+    def __mod__(self, query: Query) -> URL: ...
     def is_absolute(self) -> bool: ...
     def is_default_port(self) -> bool: ...
     def origin(self) -> URL: ...