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

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.

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:

pip install purl

To install from GitHub (unstable):

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:

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:

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:

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:

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:

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
• Official Documentation: purl.readthedocs.org
• PyPI Project Page: purl on PyPI
• RFC 6570 Specification: tools.ietf.org/html/rfc6570