urlobject

library3.0.0pypypi✓ verified 89d ago

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.

http-networking

pip install urlobject

github ↗package ↗

INSTALL

IMPORT

SIG · URLOBJECT

urlobject

http-networkingpythonv3.0.0

Install

1.5s avg

Import

15ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.016s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.015s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

URLObject

✓ from urlobject import URLObject

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()}")

Debug

Known issues

breakingMajor 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'`.

affects: <3.0.0

gotchaURLObject 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')`.

affects: All

gotchaWhen 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.

affects: All

Errors

Common errors & fixes

TypeError: unsupported operand type(s) for +: 'URLObject' and 'str'

The `+` operator for concatenating URL paths was removed in `urlobject` version 3.0.0, which prioritizes explicit method names over operator overloading.

fix

Use the `join()` method for concatenating URL segments or other URLs: `URLObject('http://example.com/base').join('segment')`

AttributeError: 'URLObject' object has no attribute 'q'

The `q` attribute for accessing query parameters was removed in `urlobject` version 3.0.0; the API was revised for clarity.

fix

Use the `query_params` property to access query parameters (read-only dict) or `add_query_params()` to modify them: `url_obj.add_query_params({'param': 'value'})` or `print(url_obj.query_params.get('param'))`

AttributeError: 'URLObject' object has no attribute 'path'

The `path` attribute (a list of strings) was removed in `urlobject` version 3.0.0 in favor of a clearer API.

fix

Use the `path_parts` property to get the path segments as a list, and `replace_path_parts()` to modify them: `url_obj.replace_path_parts(['new', 'path', 'segments'])` or `print(url_obj.path_parts)`

AttributeError: module 'urlobject' has no attribute 'parse'

The `parse` method is a static method of the `URLObject` class, not a top-level function directly available from the `urlobject` module.

fix

Import the `URLObject` class and call `parse` on it: `from urlobject import URLObject; URLObject.parse('http://example.com')`

NameError: name 'URLObject' is not defined

The `URLObject` class was used in the code without being explicitly imported from the `urlobject` library first.

fix

Add an import statement for the `URLObject` class at the beginning of your script: `from urlobject import URLObject`

Upgrade

Version history

3.0.0latest on PyPI · released Jul 11, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/zacharyvoase/urlobject ↗

packagehttps://pypi.org/project/urlobject/ ↗