Note
All doctests in this documentation use Python 3.3 syntax.
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.
This URL’s scheme.
>>> print(URLObject("http://www.google.com").scheme)
http
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
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
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
This URL’s username, if any.
>>> print(URLObject("http://user@www.google.com").username)
user
>>> print(URLObject("http://www.google.com").username)
None
Add or replace this URL’s username.
>>> print(URLObject("http://user@www.google.com").with_username("user2"))
http://user2@www.google.com
Remove this URL’s username.
>>> print(URLObject("http://user@www.google.com/").without_username())
http://www.google.com/
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
Add or replace this URL’s password.
>>> print(URLObject("http://user:somepassword@www.google.com").with_password("passwd"))
http://user:passwd@www.google.com
Remove this URL’s password.
>>> print(URLObject("http://user:pwd@www.google.com").without_password())
http://user@www.google.com
This URL’s hostname.
>>> print(URLObject("http://www.google.com").hostname)
www.google.com
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
This URL’s port number, or None.
>>> URLObject("http://www.google.com:8080").port
8080
>>> print(URLObject("http://www.google.com").port)
None
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
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
Remove this URL’s port.
>>> print(URLObject("http://www.google.com:8080/a/b/c").without_port())
http://www.google.com/a/b/c
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)
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
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
This URL’s path.
>>> print(URLObject("http://www.google.com/a/b/c").path)
/a/b/c
>>> print(URLObject("http://www.google.com").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
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/
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/
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
>>> print(URLObject("http://www.google.com").add_path_segment("a"))
http://www.google.com/a
>>> print(URLObject("http://www.google.com").add_path("a/b/c"))
http://www.google.com/a/b/c
This URL’s query string.
>>> print(URLObject("http://www.google.com").query)
>>> print(URLObject("http://www.google.com?a=b").query)
a=b
Add or replace this URL’s query string.
>>> print(URLObject("http://www.google.com").with_query("a=b"))
http://www.google.com?a=b
Remove this URL’s query string.
>>> print(URLObject("http://www.google.com?a=b&c=d").without_query())
http://www.google.com
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')]
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'}
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 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 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 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 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
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
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
This URL’s fragment.
>>> print(URLObject("http://www.google.com/a/b/c#fragment").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
Remove this URL’s fragment.
>>> print(URLObject("http://www.google.com/a/b/c#fragment").without_fragment())
http://www.google.com/a/b/c
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