https://github.com/ada-url/ada-python

Python bindings for Ada URL parser
https://github.com/ada-url/ada-python

whatwg-url

Last synced: 3 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 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-13T17:32:40.000Z (7 months ago)
• Last Synced: 2024-04-14T13:07:41.170Z (7 months ago)
• Topics: whatwg-url
• Language: C++
• Homepage: https://ada-url.com
• Size: 618 KB
• Stars: 31
• Watchers: 6
• Forks: 5
• Open Issues: 10
• 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:[email protected]:80/api?q=1#2')

    {

        'href': 'https://user:[email protected]: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.