Ada URL Parser

1.31.0 · active · verified Sat Apr 11

Ada URL is a fast, standard-compliant Python library for parsing and manipulating URLs, directly based on the high-performance Ada C++ URL parser. It strictly adheres to the WHATWG URL Standard, offering a more predictable and often faster alternative to Python's built-in `urllib.parse`. The library is actively maintained with frequent updates, often aligning with new releases of the underlying C++ project.

Warnings

deprecated Python 3.9 support was deprecated in version 1.28.0. Users are encouraged to upgrade to Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or later.
gotcha The `__repr__` of `URL` objects now redacts passwords for security reasons. If you relied on the full URL string (including sensitive credentials) in `__repr__` output for debugging or logging, this behavior has changed.
Fix: Access `url_obj.href` for the full URL string if needed, but be mindful of exposing sensitive information.
gotcha While `ada-url` is significantly faster than Python's `urllib.parse`, it uses CFFI for its bindings. For scenarios requiring absolute maximum performance with minimal Python-C overhead, alternative bindings like `can_ada` (which uses `pybind11`) might offer further speed improvements.
Fix: Benchmark `ada-url` against `can_ada` in your specific use case if micro-optimizations for URL parsing speed are critical.
gotcha Ada-url strictly follows the WHATWG URL Standard. This can lead to different parsing behaviors compared to Python's `urllib.parse`, which does not strictly adhere to any single standard (neither WHATWG nor older RFCs). Be aware of potential differences when migrating or when interacting with systems that follow older RFCs.
Fix: Thoroughly test URL parsing and serialization logic when migrating from `urllib.parse` or integrating with non-WHATWG-compliant systems to ensure consistent behavior.
breaking The underlying Ada C++ library (which `ada-url` binds to) has its own breaking changes between major versions (e.g., Ada v3.0 introduced C++20 requirements and changed error types). While the Python bindings aim for stability, users building from source or relying on very specific low-level behaviors might indirectly encounter these breaking changes or require updated C++ toolchains.
Fix: Review the changelogs of the `ada-python` library and the upstream `ada` C++ library when upgrading. Ensure your build environment meets the latest C++ compiler requirements if building from source.

Install

pip install ada-url Install with pip

Imports

URL
```
from ada_url import URL
```
parse_url
```
from ada_url import parse_url
```
URLSearchParams
```
from ada_url import URLSearchParams
```

Quickstart

This quickstart demonstrates parsing a URL into an `URL` object to access its components, modifying a component, and using the `parse_url` function to get a dictionary representation.

import ada_url

# Parse a URL using the URL class
url_obj = ada_url.URL('https://user:pass@example.org:8080/path/to/resource?query=value#fragment')

print(f"Original URL: {url_obj.href}")
print(f"Protocol: {url_obj.protocol}")
print(f"Hostname: {url_obj.hostname}")
print(f"Port: {url_obj.port}")
print(f"Pathname: {url_obj.pathname}")
print(f"Search: {url_obj.search}")
print(f"Hash: {url_obj.hash}")

# Modify a URL component
url_obj.port = '443'
url_obj.protocol = 'https:'
print(f"Modified URL: {url_obj.href}")

# Use high-level parse_url function (returns a dictionary)
parsed_dict = ada_url.parse_url('https://example.com/api?id=123&name=test')
print(f"Parsed dictionary: {parsed_dict['search']}")

view raw JSON →