purl

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

API

There’s only one class 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:

1. Pass a URL string:

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

2. Pass keyword arguments:

   >>> URL(host='www.google.com', path='/search', query='q=testing')
   u'http://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')
u'http://example.com/foo/bar'

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()

Return the password

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 a query parameter for the given key

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 a dictionary of query params

Parameters:value (dict) – new dictionary of values

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()

Return the username