hyperlink library

Warnings

• gotcha hyperlink's URL objects are immutable. All 'modifying' methods (e.g., `replace()`, `add()`, `drop()`, `set()`) return a *new* URL object with the changes, rather than modifying the object in place.
  Fix: Always assign the result of modifying methods to a new variable (e.g., `new_url = old_url.replace(...)`).
• gotcha The `hyperlink.parse()` function, by default (since v18.0.0), returns a `DecodedURL` which automatically handles encoding/decoding of URL components. Directly instantiating `hyperlink.URL` (or `hyperlink.EncodedURL`) requires manual handling of URL-reserved characters, which can easily lead to incorrect encoding if not carefully managed.
  Fix: For most common use cases, prefer using `hyperlink.parse()` or `hyperlink.DecodedURL` to leverage automatic encoding/decoding. Use `hyperlink.URL` (or `hyperlink.EncodedURL`) only when explicit control over encoding is required.
• breaking In version 19.0.0, the library changed how 'equals sign' characters are handled in query parameter *values*. Previously, they were escaped; now, they are not, aligning with standard web form encoding. This could be a breaking change if your system relied on the old escaping behavior for parsing or comparison.
  Fix: If existing code expects the old escaping behavior for query parameter values, it may need to be updated to account for the new standard or apply custom encoding/decoding.
• breaking In version 20.0.0, bug fixes related to hidden state on `URL` objects mean that constructor arguments like `rooted` and `uses_netloc` may be ignored if applying them would result in an invalid or unparseable URL. The object prioritizes validity over literal argument adherence in such cases.
  Fix: Be aware that the `URL` constructor may internally adjust or ignore certain arguments to maintain RFC compliance and validity. Always inspect the resulting `URL` object if relying on specific argument values.

Install

• pip install hyperlink Install stable version

Imports

• URL

  from hyperlink import URL

  The lower-level URL class, also available as hyperlink.EncodedURL. Requires manual handling of encoding for special characters.
• parse

  from hyperlink import parse

  The recommended top-level convenience function to parse a textual URL into a DecodedURL object.
• DecodedURL

  from hyperlink import DecodedURL

  The recommended URL type for most operations, automatically handling encoding and decoding of components.

Quickstart

This quickstart demonstrates parsing a URL from a string, creating modified copies using the immutable API, navigating paths, accessing query parameters, and constructing a URL from individual components.

from hyperlink import parse

# Parse a URL from text
url = parse(u'http://github.com/python-hyper/hyperlink?utm_source=readthedocs')
print(f"Original URL: {url.to_text()}")

# Create a new URL by replacing components (URL objects are immutable)
secure_url = url.replace(scheme=u'https', port=443)
print(f"Secure URL: {secure_url.to_text()}")

# Navigate to a child path or resolve relative paths
org_url = secure_url.click(u'.') # Clicks to the root of the domain
print(f"Org URL: {org_url.to_text()}")

# Access query parameters
utm_source = secure_url.get(u'utm_source')[0]
print(f"UTM Source: {utm_source}")

# Build a URL from components
new_url_from_parts = URL(scheme=u'https', host=u'example.com', path=[u'api', u'v1'], query=((u'id', u'123'),))
print(f"Built from parts: {new_url_from_parts.to_text()}")