purl 0.8

An immutable URL class for easy URL-building and manipulation

A simple, immutable URL class with a clean API for interrogation and manipulation. Supports Python 2.6, 2.7 and 3.3.

Also supports template URLs as per RFC 6570

Docs

http://purl.readthedocs.org/en/latest/

Install

From PyPI (stable):

pip install purl

From Github (unstable):

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

Use

Construct:

>>> 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
>>> from_combo = URL('https://www.google.com').path('search').query_param('q', 'testing')

URL objects are immutable - all mutator methods return a new instance.

Interrogate:

>>> u = URL(u'https://www.google.com/search?q=testing')
>>> u.scheme()
u'https'
>>> u.host()
u'www.google.com'
>>> u.domain()
u'www.google.com'
>>> u.username()
>>> u.password()
>>> u.netloc()
u'www.google.com'
>>> u.port()
>>> u.path()
u'/search'
>>> u.query()
u'q=testing'
>>> u.fragment()
u''
>>> u.path_segment(0)
u'search'
>>> u.path_segments()
(u'search',)
>>> u.query_param('q')
u'testing'
>>> u.query_param('q', as_list=True)
[u'testing']
>>> u.query_param('lang', default=u'GB')
u'GB'
>>> u.query_params()
{u'q': [u'testing']}
>>> u.has_query_param('q')
True
>>> u.has_query_params(('q', 'r'))
False
>>> u.subdomains()
[u'www', u'google', u'com']
>>> u.subdomain(0)
u'www'

Note that each accessor method is overloaded to be a mutator method too, similar to the jQuery API. Eg:

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

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

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

Hence, you can build a URL up in steps:

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

Along with the above overloaded methods, there is also a add_path_segment method for adding a segment at the end of the current path:

>>> new_url = u.add_path_segment('here')
>>> new_url.as_string()
u'http://www.example.com/some/path/here?q=search+term'

Couple of other things:

• Since the URL class is immutable it can be used as a key in a dictionary

• It can be pickled and restored

• It supports equality operations

URL templates can be used either via a Template class:

>>> from purl import Template
>>> tpl = Template("http://example.com{/list*}")
>>> url = tpl.expand({'list': ['red', 'green', 'blue']})
>>> url.as_string()
u'http://example.com/red/green/blue'

or the expand function:

>>> from purl import expand
>>> expand(u"{/list*}", {'list': ['red', 'green', 'blue']})
u'/red/green/blue'

A wide variety of expansions are possible - refer to the RFC for more details.

Changelog

v0.8

• Support for RFC 6570 URI templates

v0.7

• All internal strings are unicode.

• Support for unicode chars in path, fragment, query, auth added.

v0.6

• Added append_query_param method

• Added remove_query_param method

v0.5

• Added support for Python 3.2/3.3 (thanks @pmcnr and @mitchellrj)

v0.4.1

• Added API docs

• Added to readthedocs.org

v0.4

• Modified constructor to accept full URL string as first arg

• Added add_path_segment method

v0.3.2

• Fixed bug port number in string when using from_string constructor

v0.3.1

• Fixed bug with passing lists to query param setter methods

v0.3

• Added support for comparison and equality

• Added support for pickling

• Added __slots__ so instances can be used as keys within dictionaries

Contribute

Clone and install testing dependencies:

$ python setup.py develop
$ pip install -r requirements.txt

Ensure tests pass:

$ ./runtests.sh

Or using tox:

$ tox

Hack away.