{"id":9569,"library":"can-ada","title":"can-ada: Fast Spec-Compliant URL Parser","description":"can-ada is a Python wrapper for the Ada C++ library, providing a fast and spec-compliant URL parser. It adheres to the WHATWG URL Standard, offering high-performance parsing capabilities. The current version is 3.0.0, with releases typically following updates to the underlying Ada C++ library.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/tktech/can_ada","tags":["url","parser","whatwg","performance","ada","c-extension"],"install":[{"cmd":"pip install can-ada","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"URL is a class directly exposed at the top level of the package.","wrong":"import can_ada.URL","symbol":"URL","correct":"from can_ada import URL"},{"note":"parse_url is a utility function exposed at the top level of the package.","wrong":"import can_ada.parse_url","symbol":"parse_url","correct":"from can_ada import parse_url"},{"note":"URLSearchParams is a class for working with URL query parameters.","wrong":"import can_ada.URLSearchParams","symbol":"URLSearchParams","correct":"from can_ada import URLSearchParams"}],"quickstart":{"code":"from can_ada import URL, parse_url\n\n# Parse a URL string into a URL object\nurl_string = \"https://example.com:8080/path/to/resource?query=value&foo=bar#fragment\"\nurl_object = URL(url_string)\n\nprint(f\"Original URL: {url_object.href}\")\nprint(f\"Protocol: {url_object.protocol}\")     # e.g., 'https:'\nprint(f\"Host: {url_object.host}\")             # e.g., 'example.com:8080'\nprint(f\"Hostname: {url_object.hostname}\")     # e.g., 'example.com'\nprint(f\"Port: {url_object.port}\")             # e.g., '8080'\nprint(f\"Pathname: {url_object.pathname}\")     # e.g., '/path/to/resource'\nprint(f\"Search: {url_object.search}\")         # e.g., '?query=value&foo=bar'\nprint(f\"Hash: {url_object.hash}\")             # e.g., '#fragment'\n\n# Modify parts of the URL\nurl_object.hostname = \"newhost.org\"\nurl_object.pathname = \"/new/path\"\nprint(f\"Modified URL: {url_object.href}\")\n\n# Using parse_url for convenience (returns a dictionary-like object)\nparsed_dict = parse_url(\"http://test.com/page\")\nprint(f\"Parsed dict protocol: {parsed_dict.protocol}\")\n","lang":"python","description":"Demonstrates basic URL parsing, accessing components, and modification using the URL object, as well as the convenience function `parse_url`."},"warnings":[{"fix":"Upgrade to Python 3.9 or higher (Python 3.14 is supported as of v3.0.0) to ensure full compatibility and support.","message":"Official support for Python 3.7 and 3.8 was removed in `can-ada` v2.0.0. While it might still work, stability and future compatibility are not guaranteed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"No direct fix needed for standard usage. If encountering unexpected behavior in advanced scenarios, consult the `can-ada` GitHub repository for details on the `nanobind` migration.","message":"`can-ada` v3.0.0 switched its underlying binding library from `pybind11` to `nanobind`. While this led to significant performance improvements (32% faster) and reduced call overhead, users with highly specialized C-extension interactions or those relying on `pybind11`-specific internal behaviors might observe subtle changes. Standard Python usage should be unaffected.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"For robust handling of query parameters (adding, deleting, getting values), use `from can_ada import URLSearchParams` and interact with `URL.searchParams` property which returns a `URLSearchParams` object.","message":"The `URLSearchParams` object (introduced in v1.3.0) provides a structured way to interact with URL query parameters. Directly manipulating the `URL.search` string property can lead to malformed URLs if not handled carefully.","severity":"gotcha","affected_versions":">=1.3.0"},{"fix":"If parsing a relative URL, always provide a `base_input`: `URL('/relative/path', base_input='http://example.com')`.","message":"When constructing URLs, ensure that relative paths or base URLs are handled correctly. The `URL` constructor allows an optional `base_input` argument for resolving relative URLs, which can prevent unexpected parsing outcomes.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure you are using `from can_ada import URL` (or `parse_url`, `URLSearchParams`) as these are top-level exports.","cause":"Attempting to import `URL` (or other symbols) from `can_ada` directly as an attribute, or a typo in the import path.","error":"ImportError: cannot import name 'URL' from 'can_ada'"},{"fix":"Verify that the URL string is correctly formatted (e.g., includes a scheme like 'http://', valid characters, etc.).","cause":"The input string provided to the `URL` constructor or `parse_url` function does not conform to the WHATWG URL standard.","error":"ValueError: Invalid URL"},{"fix":"Use `url_object.hostname` for the domain without port, or `url_object.host` for the domain with port (if present).","cause":"Attempting to access a non-existent URL component. `can-ada` adheres to the WHATWG URL Standard, which uses `hostname` or `host` instead of `domain`.","error":"AttributeError: 'URL' object has no attribute 'domain'"},{"fix":"Ensure `base_input` is always a string when provided, or omit it if no base URL is required.","cause":"Passing `None` as the `base_input` argument to the `URL` constructor when it expects a string for URL resolution.","error":"TypeError: argument 'base_input': 'NoneType' object cannot be converted to 'str'"}]}