https://github.com/ada-url/ada-python
Python bindings for Ada URL parser
https://github.com/ada-url/ada-python
whatwg-url
Last synced: 6 months ago
JSON representation
Python bindings for Ada URL parser
- Host: GitHub
- URL: https://github.com/ada-url/ada-python
- Owner: ada-url
- License: mit
- Created: 2023-05-16T20:57:05.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-28T16:33:08.000Z (6 months ago)
- Last Synced: 2025-04-28T17:39:37.984Z (6 months ago)
- Topics: whatwg-url
- Language: C++
- Homepage: https://ada-url.com
- Size: 1.04 MB
- Stars: 45
- Watchers: 5
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
ada-url
========
The `urlib.parse` module in Python does not follow the legacy RFC 3978 standard nor
does it follow the newer WHATWG URL specification. It is also relatively slow.
This is ``ada_url``, a fast standard-compliant Python library for working with URLs based on the ``Ada`` URL
parser.
* `Documentation `__
* `Development `__
* `Ada `__
Installation
------------
Install from `PyPI `__:
.. 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 `_:.
.. 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': ,
'scheme_type':
}
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 `__.
.. 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 ``urlib.parse`` module:
.. 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/'
Alternative Python bindings
---------------------------
This package uses `CFFI `__ to call
the ``Ada`` library's functions, which has a performance cost.
The alternative `can_ada `__ (Canadian Ada)
package uses `pybind11 `__ to generate a
Python extension module, which is more performant.