class-attribute
instance-attribute
_FRAGMENT_QUOTER = _Quoter(safe='?/:@', requote=False)
class-attribute
instance-attribute
_FRAGMENT_REQUOTER = _Quoter(safe='?/:@')
class-attribute
instance-attribute
_PATH_QUOTER = _Quoter(
safe="@:", protected="/+", requote=False
)
class-attribute
instance-attribute
_PATH_REQUOTER = _Quoter(safe='@:', protected='/+')
class-attribute
instance-attribute
_PATH_SAFE_UNQUOTER = _Unquoter(ignore='/%', unsafe='+')
class-attribute
instance-attribute
_PATH_UNQUOTER = _Unquoter(unsafe='+')
class-attribute
instance-attribute
_QS_UNQUOTER = _Unquoter(qs=True)
class-attribute
instance-attribute
_QUERY_PART_QUOTER = _Quoter(
safe="?/:@", qs=True, requote=False
)
class-attribute
instance-attribute
_QUERY_QUOTER = _Quoter(
safe="?/:@", protected="=+&;", qs=True, requote=False
)
class-attribute
instance-attribute
_QUERY_REQUOTER = _Quoter(
safe="?/:@", protected="=+&;", qs=True
)
class-attribute
instance-attribute
_QUOTER = _Quoter(requote=False)
class-attribute
instance-attribute
_REQUOTER = _Quoter()
class-attribute
instance-attribute
_UNQUOTER = _Unquoter()
class-attribute
instance-attribute
__slots__ = ('_cache', '_val')
instance-attribute
_val: SplitResult
__bool__() -> bool
__bytes__() -> bytes
__eq__(other: object) -> bool
__ge__(other: object) -> bool
__getstate__() -> Tuple[SplitResult]
__gt__(other: object) -> bool
__hash__() -> int
__init_subclass__()
__le__(other: object) -> bool
__lt__(other: object) -> bool
__new__(
val: Union[str, SplitResult, URL] = "",
*,
encoded: bool = False,
strict: Union[bool, None] = None
) -> Self
__repr__() -> str
__setstate__(state)
__str__() -> str
_cache_netloc() -> None
Cache the netloc parts of the URL.
_default_port() -> Union[int, None]
Default port for the scheme or None if not known.
classmethod
_encode_host(
host: str,
human: bool = False,
validate_host: bool = True,
) -> str
_get_str_query(
*args: Any, **kwargs: Any
) -> Union[str, None]
_get_str_query_from_iterable(
items: Iterable[Tuple[Union[str, istr], str]]
) -> str
Return a query string from an iterable.
_make_child(
paths: Sequence[str], encoded: bool = False
) -> URL
add paths to self._val.path, accounting for absolute vs relative paths, keep existing, but do not create new, empty segments
classmethod
_make_netloc(
user: Union[str, None],
password: Union[str, None],
host: Union[str, None],
port: Union[int, None],
encode: bool = False,
encode_host: bool = True,
requote: bool = False,
) -> str
classmethod
_normalize_path(path: str) -> str
_parsed_query() -> List[Tuple[str, str]]
Parse query part of URL.
_port_not_default() -> Union[int, None]
The port part of URL normalized to None if its the default port.
classmethod
_query_seq_pairs(
quoter: Callable[[str], str],
pairs: Iterable[Tuple[str, QueryVariable]],
) -> Iterator[str]
staticmethod
_query_var(v: QueryVariable) -> str
cached
classmethod
_split_netloc(
netloc: str,
) -> Tuple[
Union[str, None],
Union[str, None],
Union[str, None],
Union[int, None],
]
Split netloc into username, password, host and port.
staticmethod
_validate_authority_uri_abs_path(
host: str, path: str
) -> None
Ensure that path in URL with authority starts with a leading slash.
Raise ValueError if not.
absolute() -> bool
A check for absolute URLs.
Return True for absolute ones (having scheme or starting with //), False otherwise.
authority() -> str
Decoded authority part of URL.
Empty string for relative URLs.
classmethod
build(
*,
scheme: str = "",
authority: str = "",
user: Union[str, None] = None,
password: Union[str, None] = None,
host: str = "",
port: Union[int, None] = None,
path: str = "",
query: Union[Query, None] = None,
query_string: str = "",
fragment: str = "",
encoded: bool = False
) -> URL
Creates and returns a new URL
explicit_port() -> Union[int, None]
Port part of URL, without scheme-based fallback.
None for relative URLs or URLs without explicit port.
extend_query(*args: Any, **kwargs: Any) -> URL
Return a new URL with query part combined with the existing.
This method will not remove existing query parameters.
Example:
url = URL('http://example.com/?a=1&b=2') url.extend_query(a=3, c=4) URL('http://example.com/?a=1&b=2&a=3&c=4')
fragment() -> str
Decoded fragment part of URL.
Empty string if fragment is missing.
host() -> Union[str, None]
Decoded host part of URL.
None for relative URLs.
host_subcomponent() -> Union[str, None]
Return the host subcomponent part of URL.
None for relative URLs.
https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
Examples:
- http://example.com:8080 -> example.com
- http://example.com:80 -> example.com
- https://127.0.0.1:8443 -> 127.0.0.1
- https://[::1]:8443 -> [::1]
- http://[::1] -> [::1]
human_repr() -> str
Return decoded human readable string for URL representation.
is_absolute() -> bool
A check for absolute URLs.
Return True for absolute ones (having scheme or starting with //), False otherwise.
Is is preferred to call the .absolute property instead as it is cached.
is_default_port() -> bool
A check for default port.
Return True if port is default for specified scheme, e.g. 'http://python.org' or 'http://python.org:80', False otherwise.
Return False for relative URLs.
Join URLs
Construct a full (“absolute”) URL by combining a “base URL” (self) with another URL (url).
Informally, this uses components of the base URL, in particular the addressing scheme, the network location and (part of) the path, to provide missing components in the relative URL.
joinpath(*other: str, encoded: bool = False) -> URL
Return a new URL with the elements in other appended to the path.
name() -> str
The last part of parts.
origin() -> URL
Return an URL with scheme, host and port parts only.
user, password, path, query and fragment are removed.
parts() -> Tuple[str, ...]
A tuple containing decoded path parts.
('/',) for absolute URLs if path is missing.
password() -> Union[str, None]
Decoded password part of URL.
None if password is missing.
path() -> str
Decoded path of URL.
/ for absolute URLs without path part.
path_qs() -> str
Decoded path of URL with query.
path_safe() -> str
Decoded path of URL.
/ for absolute URLs without path part.
/ (%2F) and % (%25) are not decoded
port() -> Union[int, None]
Port part of URL, with scheme-based fallback.
None for relative URLs or URLs without explicit port and scheme without default port substitution.
query() -> MultiDictProxy[str]
A MultiDictProxy representing parsed query parameters in decoded representation.
Empty value if URL has no query part.
query_string() -> str
Decoded query part of URL.
Empty string if query is missing.
raw_authority() -> str
Encoded authority part of URL.
Empty string for relative URLs.
raw_fragment() -> str
Encoded fragment part of URL.
Empty string if fragment is missing.
raw_host() -> Union[str, None]
Encoded host part of URL.
None for relative URLs.
When working with IPv6 addresses, use the host_subcomponent property instead
as it will return the host subcomponent with brackets.
raw_name() -> str
The last part of raw_parts.
raw_parts() -> Tuple[str, ...]
A tuple containing encoded path parts.
('/',) for absolute URLs if path is missing.
raw_password() -> Union[str, None]
Encoded password part of URL.
None if password is missing.
raw_path() -> str
Encoded path of URL.
/ for absolute URLs without path part.
raw_path_qs() -> str
Encoded path of URL with query.
raw_query_string() -> str
Encoded query part of URL.
Empty string if query is missing.
raw_suffix() -> str
raw_suffixes() -> Tuple[str, ...]
raw_user() -> Union[str, None]
Encoded user part of URL.
None if user is missing.
relative() -> URL
Return a relative part of the URL.
scheme, user, password, host and port are removed.
scheme() -> str
Scheme for absolute URLs.
Empty string for relative URLs or URLs starting with //
suffix() -> str
suffixes() -> Tuple[str, ...]
update_query(*args: Any, **kwargs: Any) -> URL
Return a new URL with query part updated.
This method will overwrite existing query parameters.
Example:
url = URL('http://example.com/?a=1&b=2') url.update_query(a=3, c=4) URL('http://example.com/?a=3&b=2&c=4')
user() -> Union[str, None]
Decoded user part of URL.
None if user is missing.
with_fragment(fragment: Union[str, None]) -> URL
Return a new URL with fragment replaced.
Autoencode fragment if needed.
Clear fragment to default if None is passed.
with_host(host: str) -> URL
Return a new URL with host replaced.
Autoencode host if needed.
Changing host for relative URLs is not allowed, use .join() instead.
with_name(name: str) -> URL
Return a new URL with name (last part of path) replaced.
Query and fragment parts are cleaned up.
Name is encoded if needed.
with_password(password: Union[str, None]) -> URL
Return a new URL with password replaced.
Autoencode password if needed.
Clear password if argument is None.
with_path(path: str, *, encoded: bool = False) -> URL
Return a new URL with path replaced.
with_port(port: Union[int, None]) -> URL
Return a new URL with port replaced.
Clear port to default if None is passed.
with_query(*args: Any, **kwargs: Any) -> URL
Return a new URL with query part replaced.
Accepts any Mapping (e.g. dict, multidict.MultiDict instances) or str, autoencode the argument if needed.
A sequence of (key, value) pairs is supported as well.
It also can take an arbitrary number of keyword arguments.
Clear query if None is passed.
with_suffix(suffix: str) -> URL
Return a new URL with suffix (file extension of name) replaced.
Query and fragment parts are cleaned up.
suffix is encoded if needed.
with_user(user: Union[str, None]) -> URL
Return a new URL with user replaced.
Autoencode user if needed.
Clear user/password if user is None.
without_query_params(*query_params: str) -> URL
Remove some keys from query part and return new URL.