purl¶

purl.URL is a simple, immutable URL class that can make your life easier.

API¶

There’s only two classes to be aware of.

class purl.URL(url_str=None, host=None, username=None, password=None, scheme=None, port=None, path=None, query=None, fragment=None)¶

The constructor can be used in two ways:

Pass a URL string:

>>> URL('http://www.google.com/search?q=testing').as_string()
u'http://www.google.com/search?q=testing'

Pass keyword arguments:

>>> URL(host='www.google.com', path='/search', query='q=testing').as_string()
u'http://www.google.com/search?q=testing'

If you pass both a URL string and keyword args, then the values of keyword args take precedence.

add_path_segment(value)¶

Add a new path segment to the end of the current string

Parameters:	value (string) – the new path segment to use

Example:

>>> u = URL('http://example.com/foo/')
>>> u.add_path_segment('bar').as_string()
u'http://example.com/foo/bar'

append_query_param(key, value)¶

Append a query parameter

Parameters:	key (string) – The query param key value (string) – The new value

domain(value=None)¶

Return the host

Parameters:	value (string) – new host string

fragment(value=None)¶

Return or set the fragment (hash)

Parameters:	value (string) – the new fragment to use
Returns:	string or new `URL` instance

classmethod from_string(url_str)¶

Factory method to create a new instance based on a passed string

This method is deprecated now

has_query_param(key)¶

Test if a given query parameter is present

Parameters:	key (string) – key to test for

has_query_params(keys)¶

Test if a given set of query parameters are present

Parameters:	keys (list) – keys to test for

host(value=None)¶

Return the host

Parameters:	value (string) – new host string

netloc()¶: Return the netloc

password(value=None)¶

Return or set the password

Parameters:	value (string) – the new password to use
Returns:	string or new `URL` instance

path(value=None)¶

Return or set the path

Parameters:	value (string) – the new path to use
Returns:	string or new `URL` instance

path_segment(index, value=None, default=None)¶

Return the path segment at the given index

Parameters:	index (integer) – value (string) – the new segment value default (string) – the default value to return if no path segment exists with the given index

path_segments(value=None)¶

Return the path segments

Parameters:	value (list) – the new path segments to use

port(value=None)¶

Return or set the port

Parameters:	value (string) – the new port to use
Returns:	string or new `URL` instance

query(value=None)¶

Return or set the query string

Parameters:	value (string) – the new query string to use
Returns:	string or new `URL` instance

query_param(key, value=None, default=None, as_list=False)¶

Return or set a query parameter for the given key

The value can be a list.

Parameters:	key (string) – key to look for default (string) – value to return if `key` isn’t found as_list (boolean) – whether to return the values as a list value (string) – the new query parameter to use

query_params(value=None)¶

Return or set a dictionary of query params

Parameters:	value (dict) – new dictionary of values

remove_query_param(key, value=None)¶

Remove a query param from a URL

Set the value parameter if removing from a list.

Parameters:	key (string) – The key to delete value (string) – The value of the param to delete (of more than one)

scheme(value=None)¶

Return or set the scheme.

Parameters:	value (string) – the new scheme to use
Returns:	string or new `URL` instance

subdomain(index, value=None)¶

Return a subdomain or set a new value and return a new URL instance.

Parameters:	index (integer) – 0-indexed subdomain value (string) – New subdomain

subdomains(value=None)¶

Returns a list of subdomains or set the subdomains and returns a new URL instance.

Parameters:	value (list) – a list of subdomains

username(value=None)¶

Return or set the username

Parameters:	value (string) – the new username to use
Returns:	string or new `URL` instance

class purl.Template(url_str)¶