API

Note

All doctests in this documentation use Python 3.3 syntax.

class urlobject.URLObject

A URL.

This class contains properties and methods for accessing and modifying the constituent components of a URL. URLObject instances are immutable, as they derive from the built-in unicode, and therefore all methods return new objects; you need to consider this when using URLObject in your own code.

>>> from urlobject import URLObject
>>> u = URLObject("http://www.google.com/")
>>> print(u)
http://www.google.com/

URL objects feature properties for directly accessing different parts of the URL: scheme, netloc, username, password, hostname, port, path, query and fragment.

All of these have a with_* method for adding/replacing them, and some have a without_* method for removing them altogether. The query string and path also have a variety of methods for doing more fine-grained inspection and manipulation.

scheme

This URL’s scheme.

>>> print(URLObject("http://www.google.com").scheme)
http

with_scheme(scheme)

Add or replace this URL’s scheme.

>>> print(URLObject("http://www.google.com").with_scheme("ftp"))
ftp://www.google.com
>>> print(URLObject("//www.google.com").with_scheme("https"))
https://www.google.com

netloc

The full network location of this URL.

This value incorporates username, password, hostname and port.

>>> print(URLObject("http://user:pass@www.google.com").netloc)
user:pass@www.google.com

with_netloc(netloc)

Add or replace this URL’s netloc.

>>> print(URLObject("http://www.google.com/a/b/c").with_netloc("www.amazon.com"))
http://www.amazon.com/a/b/c

username

This URL’s username, if any.

>>> print(URLObject("http://user@www.google.com").username)
user
>>> print(URLObject("http://www.google.com").username)
None

with_username(username)

Add or replace this URL’s username.

>>> print(URLObject("http://user@www.google.com").with_username("user2"))
http://user2@www.google.com

without_username()

Remove this URL’s username.

>>> print(URLObject("http://user@www.google.com/").without_username())
http://www.google.com/

password

This URL’s password, if any.

>>> print(URLObject("http://user:somepassword@www.google.com").password)
somepassword
>>> print(URLObject("http://user@www.google.com").password)
None

with_password(password)

Add or replace this URL’s password.

>>> print(URLObject("http://user:somepassword@www.google.com").with_password("passwd"))
http://user:passwd@www.google.com

without_password()

Remove this URL’s password.

>>> print(URLObject("http://user:pwd@www.google.com").without_password())
http://user@www.google.com

hostname

This URL’s hostname.

>>> print(URLObject("http://www.google.com").hostname)
www.google.com

with_hostname(hostname)

Add or replace this URL’s hostname.

>>> print(URLObject("http://www.google.com/a/b/c").with_hostname("cdn.amazon.com"))
http://cdn.amazon.com/a/b/c

port

This URL’s port number, or None.

>>> URLObject("http://www.google.com:8080").port
8080
>>> print(URLObject("http://www.google.com").port)
None

default_port

The destination port number for this URL.

If no port number is explicitly given in the URL, this will return the default port number for the scheme if one is known, or None. The mapping of schemes to default ports is defined in urlobject.ports.DEFAULT_PORTS.

For URLs with explicit port numbers, this just returns the value of port.

>>> URLObject("https://www.google.com").default_port
443
>>> URLObject("http://www.google.com").default_port
80
>>> URLObject("http://www.google.com:126").default_port
126

with_port(port)

Add or replace this URL’s port.

>>> print(URLObject("http://www.google.com/a/b/c").with_port(8080))
http://www.google.com:8080/a/b/c

without_port()

Remove this URL’s port.

>>> print(URLObject("http://www.google.com:8080/a/b/c").without_port())
http://www.google.com/a/b/c

auth

The username and password of this URL as a 2-tuple.

>>> URLObject("http://user:password@www.google.com").auth
('user', 'password')
>>> URLObject("http://user@www.google.com").auth
('user', None)
>>> URLObject("http://www.google.com").auth
(None, None)

with_auth(*auth)

Add or replace this URL’s username and password.

With two arguments, this method adds/replaces both username and password. With one argument, it adds/replaces the username and removes any password.

>>> print(URLObject("http://user:password@www.google.com").with_auth("otheruser", "otherpassword"))
http://otheruser:otherpassword@www.google.com
>>> print(URLObject("http://www.google.com").with_auth("user"))
http://user@www.google.com

without_auth()

Remove any username and password on this URL.

>>> print(URLObject("http://user:password@www.google.com/a/b/c").without_auth())
http://www.google.com/a/b/c

path

This URL’s path.

>>> print(URLObject("http://www.google.com/a/b/c").path)
/a/b/c
>>> print(URLObject("http://www.google.com").path)

with_path(path)

Add or replace this URL’s path.

>>> print(URLObject("http://www.google.com/a/b/c").with_path("c/b/a"))
http://www.google.com/c/b/a

root

The root node of this URL.

This is just a synonym for url.with_path('/').

>>> print(URLObject("http://www.google.com/a/b/c").root)
http://www.google.com/

parent

The direct parent node of this URL.

>>> print(URLObject("http://www.google.com/a/b/c").parent)
http://www.google.com/a/b/
>>> print(URLObject("http://www.google.com/a/b/").parent)
http://www.google.com/a/

is_leaf

Whether this URL’s path is a leaf node or not.

A leaf node is simply one without a trailing slash. Leaf-ness affects things like relative URL resolution (c.f. relative()) and server-side routing.

>>> URLObject("http://www.google.com/a/b/c").is_leaf
True
>>> URLObject('http://www.google.com/a/').is_leaf
False
>>> URLObject('http://www.google.com').is_leaf
False

add_path_segment(segment)

>>> print(URLObject("http://www.google.com").add_path_segment("a"))
http://www.google.com/a

add_path(partial_path)

>>> print(URLObject("http://www.google.com").add_path("a/b/c"))
http://www.google.com/a/b/c

query

This URL’s query string.

>>> print(URLObject("http://www.google.com").query)

>>> print(URLObject("http://www.google.com?a=b").query)
a=b

with_query(query)

Add or replace this URL’s query string.

>>> print(URLObject("http://www.google.com").with_query("a=b"))
http://www.google.com?a=b

without_query()

Remove this URL’s query string.

>>> print(URLObject("http://www.google.com?a=b&c=d").without_query())
http://www.google.com

query_list

This URL’s query as a list of name/value pairs.

This attribute is read-only. Changes you make to the list will not propagate back to the URL.

>>> URLObject("http://www.google.com?a=b&c=d").query_list
[('a', 'b'), ('c', 'd')]

query_dict

This URL’s query as a dict mapping names to values.

Each name will have only its last value associated with it. For all the values for a given key, see query_multi_dict.

>>> dictsort(URLObject("http://www.google.com?a=b&c=d").query_dict)
{'a': 'b', 'c': 'd'}
>>> dictsort(URLObject("http://www.google.com?a=b&a=c").query_dict)
{'a': 'c'}

query_multi_dict

This URL’s query as a dict mapping names to lists of values.

All values associated with a given name will be represented, in order, in that name’s list.

>>> dictsort(URLObject("http://www.google.com?a=b&c=d").query_multi_dict)
{'a': ['b'], 'c': ['d']}
>>> dictsort(URLObject("http://www.google.com?a=b&a=c").query_multi_dict)
{'a': ['b', 'c']}

add_query_param(name, value)

Add a single query parameter.

You can add several query parameters with the same name to a URL.

>>> print(URLObject("http://www.google.com").add_query_param("a", "b"))
http://www.google.com?a=b
>>> print(URLObject("http://www.google.com").add_query_param("a", "b").add_query_param("a", "c"))
http://www.google.com?a=b&a=c

add_query_params(*args, **kwargs)

Add multiple query parameters.

Accepts anything you would normally pass to dict(): iterables of name/value pairs, keyword arguments and dictionary objects.

>>> print(URLObject("http://www.google.com").add_query_params([('a', 'b'), ('c', 'd')]))
http://www.google.com?a=b&c=d
>>> print(URLObject("http://www.google.com").add_query_params(a="b"))
http://www.google.com?a=b

set_query_param(name, value)

Set a single query parameter, overriding it if it exists already.

>>> print(URLObject("http://www.google.com?a=b&c=d").set_query_param("a", "z"))
http://www.google.com?c=d&a=z

set_query_params(*args, **kwargs)

Set query parameters, overriding existing ones.

Accepts anything you would normally pass to dict(): iterables of name/value pairs, keyword arguments and dictionary objects.

>>> print(URLObject("http://www.google.com?a=b&c=d").set_query_params([('a', 'z'), ('d', 'e')]))
http://www.google.com?c=d&a=z&d=e
>>> print(URLObject("http://www.google.com?a=b").set_query_params(a="z"))
http://www.google.com?a=z

del_query_param(name)

Remove any and all query parameters with the given name from the URL.

>>> print(URLObject("http://www.google.com?a=b&c=d&c=e").del_query_param("c"))
http://www.google.com?a=b

del_query_params(params)

Remove multiple query params from the URL.

>>> print(URLObject("http://www.google.com?a=b&c=d&d=e").del_query_params(["c", "d"]))
http://www.google.com?a=b

fragment

This URL’s fragment.

>>> print(URLObject("http://www.google.com/a/b/c#fragment").fragment)
fragment

with_fragment(fragment)

Add or replace this URL’s fragment.

>>> print(URLObject("http://www.google.com/a/b/c#fragment").with_fragment("new_fragment"))
http://www.google.com/a/b/c#new_fragment

without_fragment()

Remove this URL’s fragment.

>>> print(URLObject("http://www.google.com/a/b/c#fragment").without_fragment())
http://www.google.com/a/b/c

relative(other)

Resolve another URL relative to this one.

For example, if you have a browser currently pointing to http://www.google.com/a/b/c/, then an HTML element like <a href="../d/e/f"> would resolve to http://www.google.com/a/b/d/e/f using this function.

>>> print(URLObject("http://www.google.com/a/b/c/").relative("../d/e/f"))
http://www.google.com/a/b/d/e/f