Support URL authority (#478)

Author: asvetlov

CHANGES/478.feature

@@ -0,0 +1 @@
+Support URL authority/raw_authority properties and authority argument of build() method.

docs/api.rst

@@ -229,6 +229,34 @@ There are two kinds of properties: *decoded* and *encoded* (with
 
    .. versionadded:: 1.3
 
+.. attribute:: URL.authority
+
+   Decoded *authority* part of URL, a combination of *user*, *password*, *host*, and
+   *port*.
+
+   ``authority = [ user [ ":" password ] "@" ] host [ ":" port ]``.
+
+   *authority* is ``None`` if all parts are missing.
+
+   .. doctest::
+
+      >>> URL('http://john:[email protected]:8000').authority
+      'john:[email protected]:8000'
+
+   .. versionadded:: 1.5
+
+.. attribute:: URL.raw_authority
+
+   Encoded *authority* part of URL, a combination of *user*, *password*, *host*, and
+   *port*.  ``None`` if all parts are missing.
+
+   .. doctest::
+
+      >>> URL('http://john:pass@хост.домен:8000').raw_authority
+      'john:[email protected]:8000'
+
+   .. versionadded:: 1.5
+
 .. attribute:: URL.path
 
    Decoded *path* part of URL, ``'/'`` for absolute URLs without *path* part.

tests/test_url.py

@@ -190,6 +190,26 @@ def test_raw_host_from_str_with_ipv6():
     assert url.raw_host == "::1"
 
 
+def test_authority_full() -> None:
+    url = URL("http://user:[email protected]:8080/path")
+    assert url.raw_authority == "user:[email protected]:8080"
+    assert url.authority == "user:[email protected]:8080"
+
+
+def test_authority_short() -> None:
+    url = URL("http://host.com/path")
+    assert url.raw_authority == "host.com"
+
+
+def test_authority_full_nonasci() -> None:
+    url = URL("http://ваня:пароль@айдеко.рф:8080/path")
+    assert url.raw_authority == (
+        "%D0%B2%D0%B0%D0%BD%D1%8F:%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C@"
+        "xn--80aidohy.xn--p1ai:8080"
+    )
+    assert url.authority == "ваня:пароль@айдеко.рф:8080"
+
+
 def test_lowercase():
     url = URL("http://gitHUB.com")
     assert url.raw_host == "github.com"

tests/test_url_build.py

@@ -80,6 +80,23 @@ def test_build_with_all():
     assert str(u) == "http://foo:[email protected]:8000/index.html?arg=value1#top"
 
 
+def test_build_with_authority_and_host():
+    with pytest.raises(ValueError):
+        URL.build(authority="host.com", host="example.com")
+
+
+def test_build_with_authority():
+    url = URL.build(scheme="http", authority="ваня:[email protected]:8000", path="path")
+    assert str(url) == "http://%D0%B2%D0%B0%D0%BD%D1%8F:[email protected]:8000/path"
+
+
+def test_build_with_authority_without_encoding():
+    url = URL.build(
+        scheme="http", authority="foo:[email protected]:8000", path="path", encoded=True
+    )
+    assert str(url) == "http://foo:[email protected]:8000/path"
+
+
 def test_query_str():
     u = URL.build(scheme="http", host="127.0.0.1", path="/", query_string="arg=value1")
     assert str(u) == "http://127.0.0.1/?arg=value1"

yarl/__init__.py

@@ -187,6 +187,7 @@ def build(
         cls,
         *,
         scheme="",
+        authority=None,
         user=None,
         password=None,
         host="",
@@ -199,8 +200,14 @@ def build(
     ):
         """Creates and returns a new URL"""
 
-        if not host and scheme:
-            raise ValueError('Can\'t build URL with "scheme" but without "host".')
+        if scheme and (not host and not authority):
+            raise ValueError(
+                'Can\'t build URL with "scheme" but without "host" or "authority".'
+            )
+        if authority and (user or password or host or port):
+            raise ValueError(
+                'Can\'t mix "authority" with "user", "password", "host" or "port".'
+            )
         if port and not host:
             raise ValueError('Can\'t build URL with "port" but without "host".')
         if query and query_string:
@@ -211,7 +218,15 @@ def build(
                 '"fragment" args, use string values instead.'
             )
 
-        if not user and not password and not host and not port:
+        if authority:
+            if encoded:
+                netloc = authority
+            else:
+                tmp = SplitResult("", authority, "", "", "")
+                netloc = cls._make_netloc(
+                    tmp.username, tmp.password, tmp.hostname, tmp.port, encode=True
+                )
+        elif not user and not password and not host and not port:
             netloc = ""
         else:
             netloc = cls._make_netloc(user, password, host, port, encode=not encoded)
@@ -388,6 +403,26 @@ def scheme(self):
         """
         return self._val.scheme
 
+    @property
+    def raw_authority(self):
+        """Encoded authority part of URL.
+
+        Empty string for relative URLs.
+
+        """
+        return self._val.netloc
+
+    @cached_property
+    def authority(self):
+        """Decoded authority part of URL.
+
+        Empty string for relative URLs.
+
+        """
+        return self._make_netloc(
+            self.user, self.password, self.host, self.port, encode=False
+        )
+
     @property
     def raw_user(self):
         """Encoded user part of URL.

yarl/__init__.pyi

@@ -17,6 +17,8 @@ class URL:
     raw_host: Final[Optional[str]]
     host: Final[Optional[str]]
     port: Final[Optional[int]]
+    raw_authority: Final[Optional[str]]
+    authority: Final[Optional[str]]
     raw_path: Final[str]
     path: Final[str]
     raw_query_string: Final[str]
@@ -39,6 +41,7 @@ class URL:
         cls,
         *,
         scheme: str = ...,
+        authority: Optional[str] = ...,
         user: Optional[str] = ...,
         password: Optional[str] = ...,
         host: str = ...,