Add WHATWG URL class

Author: bbayles

README.rst

@@ -3,9 +3,24 @@ ada-url
 
 This is ``ada_url``, a Python library for parsing and joining URLs.
 
+
 Examples
 --------
 
+This package exposes a ``URL`` class that is intended to match the one described in the
+`WHATWG URL spec <https://url.spec.whatwg.org/#url-class>`__.
+
+.. code-block:: python
+
+    >>> import ada_url
+    >>> with ada_url.URL('https://example.org/path/../file.txt') as urlobj:
+    ...     urlobj.host = 'example.com'
+    ...     new_url = urlobj.href
+    >>> new_url
+    'https://example.com/file.txt'
+
+It also provides some higher level functions for parsing and manipulating URLs.
+
 .. code-block:: python
 
     >>> import ada_url

ada_url/__init__.py

@@ -1,4 +1,5 @@
 from ada_url.ada_adapter import (
+    URL,
     check_url,
     join_url,
     normalize_url,
@@ -7,6 +8,7 @@
 )
 
 __all__ = [
+    'URL',
     'check_url',
     'join_url',
     'normalize_url',

ada_url/ada_adapter.py

@@ -14,12 +14,137 @@
 )
 PARSE_ATTRIBUTES = URL_ATTRIBUTES + ('origin',)
 
+GET_ATTRIBUTES = frozenset(PARSE_ATTRIBUTES)
+SET_ATTRIBUTES = frozenset(URL_ATTRIBUTES)
+
 
 def _get_str(x):
     ret = ffi.string(x.data, x.length).decode('utf-8') if x.length else ''
     return ret
 
 
+class URL:
+    """
+    Parses a *url* (with an optional *base*) according to the
+    WHATWG URL parsing standard.
+
+    .. code-block:: python
+
+        >>> from ada_url import URL
+        >>> old_url = 'https://example.org:443/file.txt?q=1'
+        >>> with URL(old_url) as urlobj:
+        ...     old_host = urlobj.host
+        ...     urlobj.host = 'example.com'
+        ...     new_url = urlobj.href
+        >>> old_host
+        'example.org'
+        >>> new_url
+        'https://example.com:443/file.txt?q=1'
+
+    Note that you should use this class as a context manager to ensure
+    that resources are freed. If you use it without a ``with``
+    statement, call the ``close()`` method manually.
+
+    You can read and write the following attributes:
+
+    * ``href``
+    * ``protocol``
+    * ``username``
+    * ``password``
+    * ``host``
+    * ``hostname``
+    * ``port``
+    * ``pathname``
+    * ``search``
+
+    You can additionally read the ``origin`` attribute.
+
+    The class also exposes a static method that checks whether the input
+    *url* (and optional *base*) can be parsed:
+
+    .. code-block:: python
+
+        >>> url = 'https://example.org:443/file_1.txt'
+        >>> base = 'file_2.txt'
+        >>> URL.can_parse(url, base)
+        True
+
+    See the `WHATWG docs <https://url.spec.whatwg.org/#url-class>`__ for
+    more details on the URL class.
+
+    """
+
+    def __init__(self, url, base=None):
+        url_bytes = url.encode('utf-8')
+
+        if base is None:
+            self.urlobj = lib.ada_parse(url_bytes, len(url_bytes))
+        else:
+            base_bytes = base.encode('utf-8')
+            self.urlobj = lib.ada_parse_with_base(
+                url_bytes, len(url_bytes), base_bytes, len(base_bytes)
+            )
+
+        if not lib.ada_is_valid(self.urlobj):
+            raise ValueError('Invlid input')
+
+    def __getattr__(self, attr):
+        if attr in GET_ATTRIBUTES:
+            get_func = getattr(lib, f'ada_get_{attr}')
+            data = get_func(self.urlobj)
+            ret = _get_str(data)
+            if attr == 'origin':
+                lib.ada_free_owned_string(data)
+
+            return ret
+
+        return super().__getattr__(self, attr)
+
+    def __setattr__(self, attr, value):
+        if attr in SET_ATTRIBUTES:
+            try:
+                value_bytes = value.encode()
+            except Exception:
+                raise ValueError(f'Invalid value for {attr}') from None
+
+            set_func = getattr(lib, f'ada_set_{attr}')
+            ret = set_func(self.urlobj, value_bytes, len(value_bytes))
+            if (ret is not None) and (not ret):
+                raise ValueError(f'Invalid value for {attr}') from None
+
+            return ret
+
+        return super().__setattr__(attr, value)
+
+    def close(self):
+        lib.ada_free(self.urlobj)
+
+    def __enter__(self, *args, **kwargs):
+        return self
+
+    def __exit__(self, *args, **kwargs):
+        self.close()
+
+    @staticmethod
+    def can_parse(url, base=None):
+        try:
+            url_bytes = url.encode('utf-8')
+        except Exception:
+            return False
+
+        if base is None:
+            return lib.ada_can_parse(url_bytes, len(url_bytes))
+
+        try:
+            base_bytes = base.encode('utf-8')
+        except Exception:
+            return False
+
+        return lib.ada_can_parse_with_base(
+            url_bytes, len(url_bytes), base_bytes, len(base_bytes)
+        )
+
+
 def check_url(s):
     """
     Returns ``True`` if *s* represents a valid URL, and ``False`` otherwise.

tests/test_ada_url.py

@@ -1,6 +1,7 @@
 from unittest import TestCase
 
 from ada_url import (
+    URL,
     check_url,
     join_url,
     normalize_url,
@@ -10,6 +11,81 @@
 
 
 class ADAURLTests(TestCase):
+    def test_class_get(self):
+        url = 'https://user_1:password_1@example.org:8080/dir/../api?q=1#frag'
+        with URL(url) as urlobj:
+            self.assertEqual(
+                urlobj.href, 'https://user_1:password_1@example.org:8080/api?q=1#frag'
+            )
+            self.assertEqual(urlobj.username, 'user_1')
+            self.assertEqual(urlobj.password, 'password_1')
+            self.assertEqual(urlobj.protocol, 'https:')
+            self.assertEqual(urlobj.port, '8080')
+            self.assertEqual(urlobj.hostname, 'example.org')
+            self.assertEqual(urlobj.host, 'example.org:8080')
+            self.assertEqual(urlobj.pathname, '/api')
+            self.assertEqual(urlobj.search, '?q=1')
+            self.assertEqual(urlobj.hash, '#frag')
+            self.assertEqual(urlobj.origin, 'https://example.org:8080')
+
+            with self.assertRaises(AttributeError):
+                urlobj.bogus
+
+    def test_class_set(self):
+        url = 'https://username:password@www.google.com:8080/'
+        with URL(url) as urlobj:
+            urlobj.href = 'https://www.yagiz.co'
+            urlobj.hash = 'new-hash'
+            urlobj.hostname = 'new-host'
+            urlobj.host = 'changed-host:9090'
+            urlobj.pathname = 'new-pathname'
+            urlobj.search = 'new-search'
+            urlobj.protocol = 'wss'
+            actual = urlobj.href
+
+            with self.assertRaises(ValueError):
+                urlobj.hostname = 1
+
+            with self.assertRaises(ValueError):
+                urlobj.hostname = '127.0.0.0.0.1'
+
+        expected = 'wss://changed-host:9090/new-pathname?new-search#new-hash'
+        self.assertEqual(actual, expected)
+
+    def test_class_with_base(self):
+        url = '../example.txt'
+        base = 'https://example.org/path/'
+        with URL(url, base) as urlobj:
+            self.assertEqual(urlobj.href, 'https://example.org/example.txt')
+
+    def test_class_invalid(self):
+        with self.assertRaises(ValueError):
+            with URL('bogus'):
+                pass
+
+    def test_class_can_parse(self):
+        for url, expected in (
+            (1, False),
+            (None, False),
+            ('bogus', False),
+            ('https://example.org', True),
+        ):
+            with self.subTest(url=url):
+                actual = URL.can_parse(url)
+                self.assertEqual(actual, expected)
+
+    def test_class_can_parse_with_base(self):
+        url = 'example.txt'
+        for base, expected in (
+            ('https://example.org', True),
+            (1, False),
+            (None, False),
+            ('bogus', False),
+        ):
+            with self.subTest(url=url):
+                actual = URL.can_parse(url, base)
+                self.assertEqual(actual, expected)
+
     def test_check_url(self):
         for s, expected in (
             ('https:example.org', True),