URLs (Effect's Url): parsing and immutable updates of a Url.
A Url is JavaScript's URL as an immutable Python value, parsed and
normalized by the WHATWG URL Standard as Node parses it::
url = from_string("HTTPS://Example.com:443/a/../b c").unwrap()
url.href # "https://example.com/b%20c"Each setter runs URL's setter of the same name on a copy and gives the
copy back; mutate hands a MutableUrl copy to a function.
Re-exports#
Classes#
Functions#
parse#
parse(text, base=None) -> Urlnew URL(text, base); raises ValueError when text is not
a URL.
| Parameter | Type | Description |
|---|---|---|
text | str | |
base | str | Url | None = None |
Returns Url
def parse(text: str, base: str | Url | None = None) -> Url:
"""``new URL(text, base)``; raises ``ValueError`` when ``text`` is not
a URL."""
return Url(text, base)href#
href(url) -> str| Parameter | Type | Description |
|---|---|---|
url | Url |
Returns str
def href(url: Url) -> str:
return url.hreforigin#
origin(url) -> strurl.origin: scheme://host[:port] for http(s), ws(s)
and ftp URLs, "null" for the others.
| Parameter | Type | Description |
|---|---|---|
url | Url |
Returns str
def origin(url: Url) -> str:
"""``url.origin``: ``scheme://host[:port]`` for ``http(s)``, ``ws(s)``
and ``ftp`` URLs, ``"null"`` for the others."""
return url.originmake#
make(url, params, hash) -> Result[Url, UrlError]url with params appended to its query and hash (when
given) as its fragment.
| Parameter | Type | Description |
|---|---|---|
url | str | |
params | _params.UrlParams | |
hash | str | None |
Returns Result[Url, UrlError]
def make(url: str, params: _params.UrlParams, hash: str | None) -> Result[Url, UrlError]:
"""``url`` with ``params`` appended to its query and ``hash`` (when
given) as its fragment."""
parsed = Url.parse(url)
if parsed is None:
return Err(UrlError(ValueError(f"Invalid URL: {url!r}")))
record = parsed.record
if params.params:
record = _append_params(record, params)
if hash is not None:
record = setters.set_hash(record, hash)
return Ok(Url.from_record(record))from_string#
from_string(url, base=None) -> Result[Url, IllegalArgumentError]| Parameter | Type | Description |
|---|---|---|
url | str | |
base | str | Url | None = None |
Returns Result[Url, IllegalArgumentError]
def from_string(url: str, base: str | Url | None = None) -> Result[Url, IllegalArgumentError]:
parsed = Url.parse(url, base)
if parsed is not None:
return Ok(parsed)
suffix = "" if base is None else f' with base "{base}"'
return Err(IllegalArgumentError(f'Invalid URL: "{url}"{suffix}'))mutate#
mutate(url, f) -> Urlurl changed by f on a mutable copy.
| Parameter | Type | Description |
|---|---|---|
url | Url | |
f | Callable[[MutableUrl], object] |
Returns Url
def mutate(url: Url, f: Callable[[MutableUrl], object]) -> Url:
"""``url`` changed by ``f`` on a mutable copy."""
copy = MutableUrl(url)
f(copy)
return copy.freeze()set_hash#
set_hash(url, hash) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
hash | str |
Returns Url
def set_hash(url: Url, hash: str) -> Url:
return _set(url, lambda r: setters.set_hash(r, hash))set_host#
set_host(url, host) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
host | str |
Returns Url
def set_host(url: Url, host: str) -> Url:
return _set(url, lambda r: setters.set_host(r, host))set_hostname#
set_hostname(url, hostname) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
hostname | str |
Returns Url
def set_hostname(url: Url, hostname: str) -> Url:
return _set(url, lambda r: setters.set_hostname(r, hostname))set_href#
set_href(url, href) -> Urlhref parsed; raises ValueError when it is not a URL, as
URL's href setter throws.
| Parameter | Type | Description |
|---|---|---|
url | Url | |
href | str |
Returns Url
def set_href(url: Url, href: str) -> Url:
"""``href`` parsed; raises ``ValueError`` when it is not a URL, as
``URL``'s ``href`` setter throws."""
return parse(href)set_password#
set_password(url, password) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
password | str | Redacted[str] |
Returns Url
def set_password(url: Url, password: str | Redacted[str]) -> Url:
plain = password if isinstance(password, str) else redacted_value(password)
return _set(url, lambda r: setters.set_password(r, plain))set_username#
set_username(url, username) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
username | str |
Returns Url
def set_username(url: Url, username: str) -> Url:
return _set(url, lambda r: setters.set_username(r, username))set_pathname#
set_pathname(url, pathname) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
pathname | str |
Returns Url
def set_pathname(url: Url, pathname: str) -> Url:
return _set(url, lambda r: setters.set_pathname(r, pathname))set_port#
set_port(url, port) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
port | str | int |
Returns Url
def set_port(url: Url, port: str | int) -> Url:
return _set(url, lambda r: setters.set_port(r, str(port)))set_protocol#
set_protocol(url, protocol) -> UrlA new scheme; switching between a special scheme (http, ...) and
another is ignored, as URL ignores it.
| Parameter | Type | Description |
|---|---|---|
url | Url | |
protocol | str |
Returns Url
def set_protocol(url: Url, protocol: str) -> Url:
"""A new scheme; switching between a special scheme (``http``, ...) and
another is ignored, as ``URL`` ignores it."""
return _set(url, lambda r: setters.set_protocol(r, protocol))set_search#
set_search(url, search) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
search | str |
Returns Url
def set_search(url: Url, search: str) -> Url:
return _set(url, lambda r: setters.set_search(r, search))url_params#
url_params(url) -> _params.UrlParams| Parameter | Type | Description |
|---|---|---|
url | Url |
Returns _params.UrlParams
def url_params(url: Url) -> _params.UrlParams:
return _params.UrlParams(url.search_params)set_url_params#
set_url_params(url, input) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
input | _params.Input |
Returns Url
def set_url_params(url: Url, input: _params.Input) -> Url:
return set_search(url, _params.to_string(input))modify_url_params#
modify_url_params(url, f) -> Url| Parameter | Type | Description |
|---|---|---|
url | Url | |
f | Callable[[_params.UrlParams], _params.Input] |
Returns Url
def modify_url_params(url: Url, f: Callable[[_params.UrlParams], _params.Input]) -> Url:
return set_url_params(url, f(url_params(url)))