purl 1.6

Description:

purl 1.6

A simple, immutable URL class with a clean API for interrogation and
manipulation. Supports Pythons 2.7, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8 and pypy.
Also supports template URLs as per RFC 6570
Contents:


Docs
Install
Use
Changelog
Contribute





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

# Mutate (creates a new instance)
>>> new_url = u.path_segment(0, 'tangentlabs')
>>> new_url is u
False
>>> new_url.path_segment(0)
'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()
'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()
'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
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()
'http://example.com/red/green/blue'
or the expand function:
>>> from purl import expand
>>> expand(u"{/list*}", {'list': ['red', 'green', 'blue']})
'/red/green/blue'
A wide variety of expansions are possible - refer to the RFC for more details.


Changelog

v1.6 - 2021-05-15

Use pytest insteed of nose.
Fix warning around regex string.



v1.5 - 2019-03-10

Allow @ in passwords.



v1.4 - 2018-03-11

Allow usernames and passwords to be removed from URLs.



v1.3.1

Ensure paths always have a leading slash.



v1.3

Allow absolute URLs to be converted into relative.



v1.2

Support password-less URLs.
Allow slashes to be passed as path segments.



v1.1

Support setting username and password via mutator methods



v1.0.3

Handle some unicode compatibility edge-cases



v1.0.2

Fix template expansion bug with no matching variables being passed in. This
ensures purl.Template works correctly with the URLs returned from the
Github API.



v1.0.1

Fix bug with special characters in paths not being escaped.



v1.0

Slight tidy up. Document support for PyPy and Python 3.4.



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, create a virtualenv then install purl and the packages required for
testing:
$ git clone [email protected]:codeinthehole/purl.git
$ cd purl
$ mkvirtualenv purl # requires virtualenvwrapper
(purl) $ make
Ensure tests pass using:
(purl) $ pytest
or:
$ tox