The constructor runs basic type checks. All strings are expected
to be decoded (unicode in Python 2). All arguments are
optional, defaulting to appropriately empty values. A full list of
constructor arguments is below.
scheme (unicode) – The text name of the scheme.
host (unicode) – The host portion of the network location
port (int) – The port part of the network location. If
None or no port is passed, the port will default to
the default port of the scheme, if it is known. See the
SCHEME_PORT_MAP and register_default_port()
for more info.
path (tuple) – A tuple of strings representing the
slash-separated parts of the path.
query (tuple) – The query parameters, as a dictionary or
as an iterable of key-value pairs.
fragment (unicode) – The fragment part of the URL.
rooted (bool) – Whether or not the path begins with a slash.
userinfo (unicode) – The username or colon-separated
uses_netloc (bool) – Indicates whether two slashes appear
between the scheme and the host (http://eg.com vs
mailto:email@example.com). Set automatically based on scheme.
All of these parts are also exposed as read-only attributes of
URL instances, along with several useful methods.
Somewhat unexpectedly, URLs are a far more permissive
format than most would assume. Many strings which don’t
look like URLs are still valid URLs. As a result, this
method only raises URLParseError on invalid port
and IPv6 values in the host portion of the URL.
By default, the URL text will not include a password, if one
is set. RFC 3986 considers using URLs to represent such
sensitive information as deprecated. Quoting from RFC 3986,
“Applications should not render as clear text any data after the
first colon (“:”) character found within a userinfo subcomponent
unless the data after the colon is the empty string (indicating no
with_password (bool) – Whether or not to include the
password in the URL text. Defaults to False.
The serialized textual representation of this URL,
such as u"http://example.com/some/path?some=query".
As a general Python issue, “narrow” (UCS-2) builds of
Python may not be able to fully decode certain URLs, and
the in those cases, this method will return a best-effort,
partially-decoded, URL which is still valid. This issue
does not affect any Python builds 3.4+.
A new instance with its path segments, query parameters, and
hostname decoded for display purposes.
The scheme is a string, and the first part of an absolute URL, the
part before the first colon, and the part which defines the
semantics of the rest of the URL. Examples include “http”,
“https”, “ssh”, “file”, “mailto”, and many others. See
register_scheme() for more info.
The host is a string, and the second standard part of an absolute
URL. When present, a valid host must be a domain name, or an
IP (v4 or v6). It occurs before the first slash, or the second
colon, if a port is provided.
Tuple of pairs, created by splitting the ampersand-separated
mapping of keys and optional values representing
non-hierarchical data used to identify the resource. Keys are
always strings. Values are strings when present, or None when
Whether or not the path starts with a forward slash (/).
This is taken from the terminology in the BNF grammar,
specifically the “path-rootless”, rule, since “absolute path”
and “absolute URI” are somewhat ambiguous. path does
not contain the implicit prefixed "/" since that is
somewhat awkward to work with.
Registers new scheme information, resulting in correct port and
slash behavior from the URL object. There are dozens of standard
schemes preregistered, so this function is mostly meant for
proprietary internal customizations or stopgaps on missing
standards information. If a scheme seems to be missing, please
file an issue!