# purl: A Simple, Immutable Python URL Class for Clean Manipulation

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/codeinthehole-purl
Generated for open source discovery and AI-assisted research.

purl is a Python library offering a simple, immutable URL class designed for easy interrogation and manipulation of URLs. It provides a clean API, supports various Python versions, and includes features like URL template expansion based on RFC 6570. This makes it an excellent tool for handling URLs robustly in your Python projects.

GitHub: https://github.com/codeinthehole/purl
OSRepos URL: https://osrepos.com/repo/codeinthehole-purl

## Summary

purl is a Python library offering a simple, immutable URL class designed for easy interrogation and manipulation of URLs. It provides a clean API, supports various Python versions, and includes features like URL template expansion based on RFC 6570. This makes it an excellent tool for handling URLs robustly in your Python projects.

## Topics

- Python
- URL Parsing
- Web Development
- Immutable Objects
- RFC 6570
- URL Manipulation
- Python Library

## Repository Information

Last analyzed by OSRepos: Mon Jul 27 2026 20:22:31 GMT+0100 (Western European Summer Time)
Detail views: 0
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

purl is a powerful yet simple Python library that provides an immutable URL class, offering a clean and intuitive API for interrogating and manipulating URLs. Designed for robustness, purl supports a wide range of Python versions, from 2.7 up to 3.8 and PyPy. A standout feature is its comprehensive support for template URLs, adhering to the specifications of [RFC 6570](http://tools.ietf.org/html/rfc6570 "RFC 6570 specification" target="_blank").

## Installation

Installing purl is straightforward. You can install the stable version from PyPI or the latest development version directly from GitHub.

To install from PyPI:

bash
pip install purl


To install from GitHub (unstable):

bash
pip install git+git://github.com/codeinthehole/purl.git#egg=purl


## Examples

purl's API is designed for ease of use, allowing you to construct, interrogate, and manipulate URL objects efficiently.

### Construction

You can create `URL` objects from strings, keyword arguments, or by chaining methods:

python
from purl import URL

# String constructor
from_str = URL('https://www.google.com/search?q=testing')

# Keyword constructor
from_kwargs = URL(scheme='https', host='www.google.com', path='/search', query='q=testing')

# Combine methods
from_combo = URL('https://www.google.com').path('search').query_param('q', 'testing')


A key aspect of purl is that URL objects are immutable; all methods that modify a URL return a *new* instance.

### Interrogation

Accessing URL components is simple:

python
u = URL('https://www.google.com/search?q=testing')
print(u.scheme())       # 'https'
print(u.host())         # 'www.google.com'
print(u.path())         # '/search'
print(u.query())        # 'q=testing'
print(u.query_param('q')) # 'testing'
print(u.path_segments())# ('search',)


### Manipulation

Accessor methods are overloaded to also act as mutators, returning a new `URL` instance:

python
u = URL.from_string('https://github.com/codeinthehole')

# Access
print(u.path_segment(0)) # 'codeinthehole'

# Mutate (creates a new instance)
new_url = u.path_segment(0, 'tangentlabs')
print(new_url is u)      # False
print(new_url.path_segment(0)) # 'tangentlabs'


You can also build URLs step-by-step:

python
u = URL().scheme('http').domain('www.example.com').path('/some/path').query_param('q', 'search term')
print(u.as_string()) # 'http://www.example.com/some/path?q=search+term'


purl also supports URL templates as per RFC 6570:

python
from purl import Template, expand

tpl = Template("http://example.com{/list*}")
url = tpl.expand({'list': ['red', 'green', 'blue']})
print(url.as_string()) # 'http://example.com/red/green/blue'

expanded_url = expand(u"{/list*}", {'list': ['red', 'green', 'blue']})
print(expanded_url) # '/red/green/blue'


## Why Use purl?

purl stands out for several reasons, making it an excellent choice for URL handling in Python:

*   **Immutability**: All URL modifications return new instances, ensuring thread-safety and predictability. This also allows `URL` objects to be used as dictionary keys.
*   **Clean and Consistent API**: The API is intuitive, making it easy to interrogate and manipulate URL components with minimal boilerplate.
*   **RFC 6570 URL Templates**: Full support for URI templates allows for powerful and flexible URL generation.
*   **Broad Python Compatibility**: Works across a wide range of Python versions, ensuring compatibility for diverse projects.
*   **Robustness**: Designed to handle various URL structures and edge cases, providing reliable URL parsing and construction.

## Links

*   **GitHub Repository**: [codeinthehole/purl](https://github.com/codeinthehole/purl "purl GitHub Repository" target="_blank")
*   **Official Documentation**: [purl.readthedocs.org](http://purl.readthedocs.org/en/latest/ "purl Official Documentation" target="_blank")
*   **PyPI Project Page**: [purl on PyPI](https://pypi.org/project/purl/ "purl PyPI Project Page" target="_blank")
*   **RFC 6570 Specification**: [tools.ietf.org/html/rfc6570](http://tools.ietf.org/html/rfc6570 "RFC 6570 specification" target="_blank")