ada-url

This is ada_url, a fast standard-compliant Python library for working with URLs based on the Ada URL parser.

• Documentation <https://ada-url.readthedocs.io>__
• Development <https://github.com/ada-url/ada-python/>__
• Ada <https://www.ada-url.com/>__

Installation

Install from PyPI <https://pypi.org/project/ada-url/>__:

.. code-block:: sh

pip install ada_url

Usage examples

Parsing URLs ^^^^^^^^^^^^

The URL class is intended to match the one described in the WHATWG URL spec <https://url.spec.whatwg.org/#url-class>_.

.. code-block:: python

>>> from ada_url import URL
>>> urlobj = URL('https://example.org/path/../file.txt')
>>> urlobj.href
'https://example.org/path/file.txt'

The parse_url function returns a dictionary of all URL elements:

.. code-block:: python

>>> from ada_url import parse_url
>>> parse_url('https://user:pass@example.org:80/api?q=1#2')
{
    'href': 'https://user:pass@example.org:80/api?q=1#2',
    'username': 'user',
    'password': 'pass',
    'protocol': 'https:',
    'port': '80',
    'hostname': 'example.org',
    'host': 'example.org:80',
    'pathname': '/api',
    'search': '?q=1',
    'hash': '#2',
    'origin': 'https://example.org:80',
    'host_type': <HostType.DEFAULT: 0>,
    'scheme_type': <SchemeType.HTTPS: 2>
}

Altering URLs ^^^^^^^^^^^^^

Replacing URL components with the URL class:

.. code-block:: python

>>> from ada_url import URL
>>> urlobj = URL('https://example.org/path/../file.txt')
>>> urlobj.host = 'example.com'
>>> urlobj.href
'https://example.com/file.txt'

Replacing URL components with the replace_url function:

>>> from ada_url import replace_url
>>> replace_url('https://example.org/path/../file.txt', host='example.com')
'https://example.com/file.txt'

Search parameters ^^^^^^^^^^^^^^^^^

The URLSearchParams class is intended to match the one described in the WHATWG URL spec <https://url.spec.whatwg.org/#interface-urlsearchparams>__.

.. code-block:: python

>>> from ada_url import URLSearchParams
>>> obj = URLSearchParams('key1=value1&key2=value2')
>>> list(obj.items())
[('key1', 'value1'), ('key2', 'value2')]

The parse_search_params function returns a dictionary of search keys mapped to value lists:

.. code-block:: python

>>> from ada_url import parse_search_params
>>> parse_search_params('key1=value1&key2=value2')
{'key1': ['value1'], 'key2': ['value2']}

Internationalized domain names ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The idna class can encode and decode IDNs:

.. code-block:: python

>>> from ada_url import idna
>>> idna.encode('Bücher.example')
b'xn--bcher-kva.example'
>>> idna.decode(b'xn--bcher-kva.example')
'bücher.example'

WHATWG URL compliance

This library is compliant with the WHATWG URL spec. This means, among other things, that it properly encodes IDNs and resolves paths:

.. code-block:: python

>>> from ada_url import URL
>>> parsed_url = URL('https://www.GOoglé.com/./path/../path2/')
>>> parsed_url.hostname
'www.xn--googl-fsa.com'
>>> parsed_url.pathname
'/path2/'

Contrast that with the Python standard library's urllib.parse module, which loosely follows the older RFC 3978 <https://datatracker.ietf.org/doc/html/rfc3978>__ standard:

.. code-block:: python

>>> from urllib.parse import urlparse
>>> parsed_url = urlparse('https://www.GOoglé.com/./path/../path2/')
>>> parsed_url.hostname
'www.googlé.com'
>>> parsed_url.path
'/./path/../path2/'

Performance

This package uses CFFI <https://github.com/ada-url/ada-python/>__ to call the Ada C library's functions, which makes it faster than the Python standard library's urllib.parse module for most applications.

An alternative package, can_ada <https://github.com/tktech/can_ada>, uses pybind11 <https://pybind11.readthedocs.io/en/stable/> to interact with the Ada C++ library functions, which is even faster.