GitHub

API reference for url.

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) -> Url

new URL(text, base); raises ValueError when text is not a URL.

ParameterTypeDescription
textstr
basestr | 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
ParameterTypeDescription
urlUrl

Returns str

def href(url: Url) -> str:
    return url.href

origin

origin(url) -> str

url.origin: scheme://host[:port] for http(s), ws(s) and ftp URLs, "null" for the others.

ParameterTypeDescription
urlUrl

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.origin

make

make(url, params, hash) -> Result[Url, UrlError]

url with params appended to its query and hash (when given) as its fragment.

ParameterTypeDescription
urlstr
params_params.UrlParams
hashstr | 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]
ParameterTypeDescription
urlstr
basestr | 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) -> Url

url changed by f on a mutable copy.

ParameterTypeDescription
urlUrl
fCallable[[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
ParameterTypeDescription
urlUrl
hashstr

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
ParameterTypeDescription
urlUrl
hoststr

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
ParameterTypeDescription
urlUrl
hostnamestr

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) -> Url

href parsed; raises ValueError when it is not a URL, as URL's href setter throws.

ParameterTypeDescription
urlUrl
hrefstr

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
ParameterTypeDescription
urlUrl
passwordstr | 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
ParameterTypeDescription
urlUrl
usernamestr

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
ParameterTypeDescription
urlUrl
pathnamestr

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
ParameterTypeDescription
urlUrl
portstr | 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) -> Url

A new scheme; switching between a special scheme (http, ...) and another is ignored, as URL ignores it.

ParameterTypeDescription
urlUrl
protocolstr

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(url, search) -> Url
ParameterTypeDescription
urlUrl
searchstr

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
ParameterTypeDescription
urlUrl

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
ParameterTypeDescription
urlUrl
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
ParameterTypeDescription
urlUrl
fCallable[[_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)))