URLObject

3.0.0 · active · verified Wed Apr 15

URLObject is a utility class for manipulating URLs in Python. The latest version, 3.0.0, aims for a clearer API by focusing on explicit method names rather than relying heavily on operator overrides, building upon its predecessors. It provides an immutable object-oriented interface for parsing, constructing, and modifying URLs and their components. It is actively maintained with a recent release.

Warnings

breaking Major API changes occurred between `urlobject` 2.x and 3.x. Version 3.x shifts focus to 'proper method names over operator overrides'. Code relying on operator overloading (e.g., `url + '/path'`) from older versions will break and needs to be migrated to explicit methods like `.add_path()`, `.with_query()`, etc.
Fix: Review your code and replace operator overloads with explicit method calls as described in the library's documentation for version 3.x. For example, use `url.add_path('segment')` instead of `url + 'segment'`.
gotcha URLObject instances are immutable. All methods that 'modify' a URLObject (e.g., `with_scheme()`, `add_query_param()`, `without_fragment()`) return a *new* URLObject instance with the applied changes, leaving the original object untouched. Forgetting to assign the result of these methods will lead to no changes being observed.
Fix: Always assign the return value of modification methods to a variable: `my_new_url = original_url.with_scheme('https')`.
gotcha When handling sensitive information like API keys or passwords in URLs, avoid hardcoding them directly in your code. Using `os.environ.get()` is a safer practice to retrieve credentials from environment variables.
Fix: Store sensitive credentials in environment variables and access them using `os.environ.get('YOUR_ENV_VAR', 'default_value')` when constructing URLs with authentication.

Install

pip install urlobject Install latest version

Imports

URLObject
```
from urlobject import URLObject
```

Quickstart

Demonstrates creating a URLObject, immutably modifying its components, accessing properties, and an example of handling authentication details using environment variables.

import os
from urlobject import URLObject

# Create a URLObject from a string
url = URLObject("https://github.com/zacharyvoase/urlobject?topic=python&q=docs#api-reference")
print(f"Original URL: {url}")

# URLObject instances are immutable; methods return new objects
modified_url = (
    url.with_scheme('http')
    .with_hostname('example.com')
    .add_query_param('lang', 'en')
    .without_fragment()
)
print(f"Modified URL: {modified_url}")

# Access individual components
print(f"Scheme: {modified_url.scheme}")
print(f"Hostname: {modified_url.hostname}")
print(f"Path: {modified_url.path}")
print(f"Query params: {modified_url.query_list_multidict()}")

# Example with authentication (use environment variables for sensitive data)
auth_url = URLObject("https://api.example.com/data").with_auth(
    os.environ.get('API_USERNAME', 'your_username'),
    os.environ.get('API_PASSWORD', 'your_password')
)
print(f"URL with auth (sensitive parts hidden): {auth_url.without_auth()}")

view raw JSON →