Skip to main content

An immutable URL class for easy URL-building and manipulation

Project description

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:

https://secure.travis-ci.org/codeinthehole/purl.png https://img.shields.io/pypi/v/purl.svg

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 git@github.com:codeinthehole/purl.git
$ cd purl
$ mkvirtualenv purl  # requires virtualenvwrapper
(purl) $ make

Ensure tests pass using:

(purl) $ pytest

or:

$ tox

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

purl-1.6.tar.gz (12.2 kB view details)

Uploaded Source

Built Distribution

purl-1.6-py2.py3-none-any.whl (10.4 kB view details)

Uploaded Python 2Python 3

File details

Details for the file purl-1.6.tar.gz.

File metadata

  • Download URL: purl-1.6.tar.gz
  • Upload date:
  • Size: 12.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: Python-urllib/3.7

File hashes

Hashes for purl-1.6.tar.gz
Algorithm Hash digest
SHA256 ba0babadbd0c981c495a45715c544ad34cdad35102e99fb4fcd7a78625627ce3
MD5 199e61930b68d2198242d84ee014257b
BLAKE2b-256 73140cdd603d9fa6e59f2b88584eec8550f688c37b5e070a1672e08aaa05bb88

See more details on using hashes here.

File details

Details for the file purl-1.6-py2.py3-none-any.whl.

File metadata

  • Download URL: purl-1.6-py2.py3-none-any.whl
  • Upload date:
  • Size: 10.4 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: Python-urllib/3.7

File hashes

Hashes for purl-1.6-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 41be5f8eff8688d0046edf47f5307aee00272bcbb2678e93808939c94773d4d1
MD5 907e625cd5b5fdad77714df247a91c1f
BLAKE2b-256 538b88c5b02c8985d43cb0e0bee0a8d2a5bf1e1b787145c76a47bcbd55511d8f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page