purl

library1.6pypypi✓ verified 24d ago

purl is an immutable URL class designed for easy URL-building and manipulation in Python. It provides a clean API for interrogation and transformation of URLs, aiming to offer a more intuitive experience than the standard library's urlparse and urllib modules. The current version is 1.6, released in May 2021, and the project is actively maintained.

http-networking serialization

pip install purl

github ↗package ↗

INSTALL

IMPORT

SIG · PURL

purl

http-networkingpythonv1.6

Install

1.6s avg

Import

21ms

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 v1.6 · 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.95 runs

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

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.020s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

URL

✓ from purl import URL

Template

✓ from purl import Template

Demonstrates how to construct a URL object, access its various components, and perform modifications. Note that all modification methods return a new URL instance due to the library's immutable design.

from purl import URL # Constructing a URL u = URL('https://www.example.com/path/to/resource?id=123&lang=en#section-1') print(f"Original URL: {u}") # Accessing parts of the URL print(f"Scheme: {u.scheme()}") print(f"Host: {u.host()}") print(f"Path: {u.path()}") print(f"Query parameter 'id': {u.query_param('id')}") # Modifying the URL (returns a *new* URL object) new_u = u.query_param('lang', 'fr').remove_query_param('id').fragment('top') print(f"Modified URL: {new_u}") print(f"Original URL (unchanged): {u}") # Chaining operations chained_url = URL('http://api.example.com').path('v1').path_segment(1, 'users').query_param('sort', 'asc') print(f"Chained URL: {chained_url}")

Debug

Known issues

gotchaURL objects are immutable. Any method that appears to 'modify' the URL (e.g., `path()`, `query_param()`, `add_query_param()`) will return a *new* `URL` instance with the changes, leaving the original object untouched. Users must assign the result of these operations to a new variable or reassign the original variable.

fix

Always capture the return value of modification methods, e.g., `new_url = old_url.path('new_path')`.

affects: All versions

gotchaAccessor methods (e.g., `u.path()`) are overloaded to also act as mutator methods (e.g., `u.path('new/path')`). When used as a mutator, they will return a *new* `URL` instance, consistent with the immutability principle. This can be confusing if not explicitly understood, as it does not modify the object in place.

fix

Be mindful that `u.some_method()` retrieves a value, while `u.some_method(new_value)` returns a new URL object with `new_value` applied. Always check if you are getting a value or a new instance.

affects: All versions

gotchaThe `purl` library (for general URL manipulation) should not be confused with `packageurl-python` (for Package URLs, or PURLs, specification). They are distinct libraries with different purposes, despite the similar naming. Ensure you import `from purl import URL` for this library.

fix

Verify that you are installing and importing the correct library (`pip install purl` for this library) based on your intended use case.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'URL' object has no attribute 'scheme'

The `purl.URL` objects are immutable; you cannot directly set their attributes (like `scheme`, `host`, or `path`) after creation. Any method that appears to 'mutate' the URL actually returns a new `URL` instance with the changes.

fix

Instead of direct assignment (e.g., `url.scheme = 'https'`), use the chainable methods provided by the `purl` library which return a new `URL` instance with the desired modifications. For example, to change the scheme, use `new_url = url.scheme('https')`.

ModuleNotFoundError: No module named 'purl'

This error indicates that the 'purl' package has not been installed in your current Python environment or that your Python environment is not correctly configured to find installed packages.

fix

Install the library using pip: `pip install purl`.

TypeError: 'str' object cannot be interpreted as an integer

This error typically occurs when trying to access a path segment using the `path_segment()` method and passing a string instead of an expected integer index.

fix

Ensure that you pass an integer as the index to `path_segment()` to specify which segment you want. For example, `url.path_segment(0)` to get the first segment.

Upgrade

Version history

1.6latest on PyPI · released May 15, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/codeinthehole/purl ↗

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