urlpath

2.0.0 verified Fri May 01 auth: no python

Object-oriented URL classes built on urllib.parse and pathlib for Python 3.9+. Version 2.0.0 switches license from PSF to MIT, drops support for Python 3.4-3.8, and restructures from a single-file module to a multi-module package. Generally stable with infrequent releases.

pip install urlpath

Common errors

error AttributeError: module 'urlpath' has no attribute 'URL' ↓

cause Importing the module instead of the class from it (old style before v2.0.0).

fix

Use 'from urlpath import URL' instead of 'import urlpath' then 'urlpath.URL'.

error AttributeError: 'str' object has no attribute 'parent' ↓

cause Treating a string as a URL object. Path operations return a URL, not a string.

fix

Create a URL object first: url = URL('https://example.com') then call url.parent().

error TypeError: expected str, bytes or os.PathLike object, not URL ↓

cause Using a URL object where a string is expected (e.g., as argument to os.path functions).

fix

Convert URL to string via str(url) or url.url before passing to non-urlpath functions.

Warnings

breaking In v2.0.0 the package changed from a single-file module to a multi-module package. Any code relying on internal module paths (e.g., importing directly from 'urlpath.py' or accessing private attributes) may break. ↓

fix Update imports to use the public API from 'urlpath' (e.g., 'from urlpath import URL').

deprecated Python 3.8 and earlier are no longer supported. The package requires Python 3.9+. ↓

fix Upgrade Python to 3.9 or later.

gotcha URL path operations (like '/' for joining) return a new URL object, not a string. Forgetting to call str() or print() can lead to confusing output. ↓

fix Convert URL to string with str(url) or use .url attribute to get the full string representation.

Imports

URL
wrong
```
import urlpath
urlpath.URL('/path')
```
correct
```
from urlpath import URL
```
Common mistake: using old single-file import style before v2.0.0 restructured the package.

Quickstart

Basic usage of URL class with path joining and query parameters.

from urlpath import URL

url = URL('https://api.example.com/resource/123')
print(url.scheme)    # 'https'
print(url.host)      # 'api.example.com'
print(url.path)      # '/resource/123'
print(url.parent())  # URL('https://api.example.com/resource')
print(url.name)      # '123'

# Chaining
new_url = url / 'sub' / 'item'
print(new_url)       # 'https://api.example.com/resource/123/sub/item'

# Query params
query_url = URL('https://example.com/search').with_query({'q': 'test', 'page': '1'})
print(query_url)     # 'https://example.com/search?q=test&page=1'

# Check if URL is absolute
print(url.is_absolute())  # True