httpx.URL

class documentation

class URL:

url = httpx.URL("HTTPS://jo%40email.com:a%20secret@müller.de:1234/pa%20th?search=ab#anchorlink")

assert url.scheme == "https" assert url.username == "jo@email.com" assert url.password == "a secret" assert url.userinfo == b"jo%40email.com:a%20secret" assert url.host == "müller.de" assert url.raw_host == b"xn--mller-kva.de" assert url.port == 1234 assert url.netloc == b"xn--mller-kva.de:1234" assert url.path == "/pa th" assert url.query == b"?search=ab" assert url.raw_path == b"/pa%20th?search=ab" assert url.fragment == "anchorlink"

The components of a URL are broken down like this:

https://jo%40email.com:a%20secret@müller.de:1234/pa%20th?search=ab#anchorlink

[scheme] [ username ] [password] [ host ][port][ path ] [ query ] [fragment]: [ userinfo ] [ netloc ][ raw_path ]

Note that:

url.scheme is normalized to always be lowercased.
url.host is normalized to always be lowercased. Internationalized domain names are represented in unicode, without IDNA encoding applied. For instance:

url = httpx.URL("http://中国.icom.museum") assert url.host == "中国.icom.museum" url = httpx.URL("http://xn--fiqs8s.icom.museum") assert url.host == "中国.icom.museum"
url.raw_host is normalized to always be lowercased, and is IDNA encoded.

url = httpx.URL("http://中国.icom.museum") assert url.raw_host == b"xn--fiqs8s.icom.museum" url = httpx.URL("http://xn--fiqs8s.icom.museum") assert url.raw_host == b"xn--fiqs8s.icom.museum"
url.port is either None or an integer. URLs that include the default port for "http", "https", "ws", "wss", and "ftp" schemes have their port normalized to None.

assert httpx.URL("http://example.com") == httpx.URL("http://example.com:80") assert httpx.URL("http://example.com").port is None assert httpx.URL("http://example.com:80").port is None
url.userinfo is raw bytes, without URL escaping. Usually you'll want to work with url.username and url.password instead, which handle the URL escaping.
url.raw_path is raw bytes of both the path and query, without URL escaping. This portion is used as the target when constructing HTTP requests. Usually you'll want to work with url.path instead.
url.query is raw bytes, without URL escaping. A URL query string portion can only be properly URL escaped when decoding the parameter names and values themselves.

Method	`__eq__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__init__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`copy_add_param`	Undocumented
Method	`copy_merge_params`	Undocumented
Method	`copy_remove_param`	Undocumented
Method	`copy_set_param`	Undocumented
Method	`copy_with`	Copy this URL, returning a new URL with some components altered. Accepts the same set of parameters as the components that are made available via properties on the `URL` class.
Method	`join`	Return an absolute URL, using this URL as the base.
Property	`fragment`	The URL fragments, as used in HTML anchors. As a string, without the leading '#'.
Property	`host`	The URL host as a string. Always normalized to lowercase, with IDNA hosts decoded into unicode.
Property	`is_absolute_url`	Return `True` for absolute URLs such as 'http://example.com/path', and `False` for relative URLs such as '/path'.
Property	`is_relative_url`	Return `False` for absolute URLs such as 'http://example.com/path', and `True` for relative URLs such as '/path'.
Property	`netloc`	Either or `<host>:` as bytes. Always normalized to lowercase, and IDNA encoded.
Property	`params`	The URL query parameters, neatly parsed and packaged into an immutable multidict representation.
Property	`password`	The URL password as a string, with URL decoding applied. For example: "a secret"
Property	`path`	The URL path as a string. Excluding the query string, and URL decoded.
Property	`port`	The URL port as an integer.
Property	`query`	The URL query string, as raw bytes, excluding the leading b"?".
Property	`raw`	The URL in the raw representation used by the low level transport API. See `BaseTransport.handle_request`.
Property	`raw_host`	The raw bytes representation of the URL host. Always normalized to lowercase, and IDNA encoded.
Property	`raw_path`	The complete URL path and query string as raw bytes. Used as the target when constructing HTTP requests.
Property	`raw_scheme`	The raw bytes representation of the URL scheme, such as b"http", b"https". Always normalised to lowercase.
Property	`scheme`	The URL scheme, such as "http", "https". Always normalised to lowercase.
Property	`userinfo`	The URL userinfo as a raw bytestring. For example: b"jo%40email.com:a%20secret".
Property	`username`	The URL username as a string, with URL decoding applied. For example: "jo@email.com"
Instance Variable	`_uri_reference`	Undocumented

def __eq__(self, other):

Undocumented

Parameters
other:`typing.Any`	Undocumented
Returns
`bool`	Undocumented

def __hash__(self):

Undocumented

Returns
`int`	Undocumented

def __init__(self, url='', **kwargs):

Undocumented

Parameters
url:`typing.Union[URL, str, RawURL]`	Undocumented
**kwargs:`typing.Any`	Undocumented

def __repr__(self):

Undocumented

Returns
`str`	Undocumented

def __str__(self):

Undocumented

Returns
`str`	Undocumented

def copy_add_param(self, key, value=None):

Undocumented

Parameters
key:`str`	Undocumented
value:`typing.Any`	Undocumented
Returns
`URL`	Undocumented

def copy_merge_params(self, params):

Undocumented

Parameters
params:`QueryParamTypes`	Undocumented
Returns
`URL`	Undocumented

def copy_remove_param(self, key):

Undocumented

Parameters
key:`str`	Undocumented
Returns
`URL`	Undocumented

def copy_set_param(self, key, value=None):

Undocumented

Parameters
key:`str`	Undocumented
value:`typing.Any`	Undocumented
Returns
`URL`	Undocumented

def copy_with(self, **kwargs):

Copy this URL, returning a new URL with some components altered. Accepts the same set of parameters as the components that are made available via properties on the URL class.

For example:

url = httpx.URL("https://www.example.com").copy_with(username="jo@gmail.com", password="a secret") assert url == "https://jo%40email.com:a%20secret@www.example.com"

Parameters
**kwargs:`typing.Any`	Undocumented
Returns
`URL`	Undocumented

def join(self, url):

Return an absolute URL, using this URL as the base.

Eg.

url = httpx.URL("https://www.example.com/test") url = url.join("/new/path") assert url == "https://www.example.com/new/path"

Parameters
url:`URLTypes`	Undocumented
Returns
`URL`	Undocumented

@property
fragment: str =

The URL fragments, as used in HTML anchors. As a string, without the leading '#'.

@property
host: str =

The URL host as a string. Always normalized to lowercase, with IDNA hosts decoded into unicode.

Examples:

url = httpx.URL("http://www.EXAMPLE.org") assert url.host == "www.example.org"

url = httpx.URL("http://中国.icom.museum") assert url.host == "中国.icom.museum"

url = httpx.URL("http://xn--fiqs8s.icom.museum") assert url.host == "中国.icom.museum"

url = httpx.URL("https://[::ffff:192.168.0.1]") assert url.host == "::ffff:192.168.0.1"

@property
is_absolute_url: bool =

Return True for absolute URLs such as 'http://example.com/path', and False for relative URLs such as '/path'.

@property
is_relative_url: bool =

Return False for absolute URLs such as 'http://example.com/path', and True for relative URLs such as '/path'.

@property
netloc: bytes =

Either or <host>: as bytes. Always normalized to lowercase, and IDNA encoded.

This property may be used for generating the value of a request "Host" header.

@property
params: QueryParams =

The URL query parameters, neatly parsed and packaged into an immutable multidict representation.

@property
password: str =

The URL password as a string, with URL decoding applied. For example: "a secret"

@property
path: str =

The URL path as a string. Excluding the query string, and URL decoded.

For example:

url = httpx.URL("https://example.com/pa%20th") assert url.path == "/pa th"

@property
port: typing.Optional[int] =

The URL port as an integer.

Note that the URL class performs port normalization as per the WHATWG spec. Default ports for "http", "https", "ws", "wss", and "ftp" schemes are always treated as None.

For example:

assert httpx.URL("http://www.example.com") == httpx.URL("http://www.example.com:80") assert httpx.URL("http://www.example.com:80").port is None

@property
query: bytes =

The URL query string, as raw bytes, excluding the leading b"?".

This is necessarily a bytewise interface, because we cannot perform URL decoding of this representation until we've parsed the keys and values into a QueryParams instance.

For example:

url = httpx.URL("https://example.com/?filter=some%20search%20terms") assert url.query == b"filter=some%20search%20terms"

@property
raw: RawURL =

The URL in the raw representation used by the low level transport API. See BaseTransport.handle_request.

Provides the (scheme, host, port, target) for the outgoing request.

@property
raw_host: bytes =

The raw bytes representation of the URL host. Always normalized to lowercase, and IDNA encoded.

Examples:

url = httpx.URL("http://www.EXAMPLE.org") assert url.raw_host == b"www.example.org"

url = httpx.URL("http://中国.icom.museum") assert url.raw_host == b"xn--fiqs8s.icom.museum"

url = httpx.URL("http://xn--fiqs8s.icom.museum") assert url.raw_host == b"xn--fiqs8s.icom.museum"

url = httpx.URL("https://[::ffff:192.168.0.1]") assert url.raw_host == b"::ffff:192.168.0.1"

@property
raw_path: bytes =

The complete URL path and query string as raw bytes. Used as the target when constructing HTTP requests.

For example:

GET /users?search=some%20text HTTP/1.1 Host: www.example.org Connection: close

@property
raw_scheme: bytes =

The raw bytes representation of the URL scheme, such as b"http", b"https". Always normalised to lowercase.

@property
scheme: str =

The URL scheme, such as "http", "https". Always normalised to lowercase.

@property
userinfo: bytes =

The URL userinfo as a raw bytestring. For example: b"jo%40email.com:a%20secret".

@property
username: str =

The URL username as a string, with URL decoding applied. For example: "jo@email.com"

_uri_reference =

Undocumented