GitHub

url_params

API reference for url_params.

URL query parameters (Effect's UrlParams): ordered (name, value) pairs, where a value may be Redacted to keep it out of logs while it is still sent.

from_input takes a mapping or pairs; values are coerced the way JavaScript's String does (True is "true", None is "null", 1.0 is "1"), a sequence value adds one pair per item and a nested mapping adds a[b] keys::

params = from_input({"q": "effect", "page": 2}).append("tag", "a")
to_string(params)   # "q=effect&page=2&tag=a"

Re-exports

Values

AttributeTypeDescription
EMPTYUrlParams

Types

TypeDefinitionDescription
Valuetype Value = str | Redacted[str]
Paramtype Param = tuple[str, Value]
Coercibletype Coercible = str | int | float | bool | Redacted[str] | None
CoercibleRecordtype CoercibleRecord = Mapping[str, Coercible | Sequence[Coercible] | CoercibleRecord]
Inputtype Input = UrlParams | CoercibleRecord | Iterable[tuple[str, Coercible]]

Classes

Functions

unwrap

unwrap(value) -> str

A value as sent: a Redacted one written out.

ParameterTypeDescription
valueValue

Returns str

def unwrap(value: Value) -> str:
    """A value as sent: a ``Redacted`` one written out."""
    return value if isinstance(value, str) else redacted_value(value)

make

make(params) -> UrlParams
ParameterTypeDescription
paramsIterable[Param]

Returns UrlParams

def make(params: Iterable[Param]) -> UrlParams:
    return UrlParams(params)

from_input

from_input(input) -> UrlParams
ParameterTypeDescription
inputInput

Returns UrlParams

def from_input(input: Input) -> UrlParams:
    if isinstance(input, UrlParams):
        return input
    return UrlParams(
        (key if isinstance(key, str) else f"{key[0]}[{']['.join(key[1:])}]", value)
        for key, value in _nested(input)
    )

to_string

to_string(input) -> str

The parameters as a query string, without the ?, as URLSearchParams writes them (only *-._ and alphanumerics stay, a space is +); Redacted values are written out.

ParameterTypeDescription
inputInput

Returns str

def to_string(input: Input) -> str:
    """The parameters as a query string, without the ``?``, as
    ``URLSearchParams`` writes them (only ``*-._`` and alphanumerics stay,
    a space is ``+``); ``Redacted`` values are written out."""
    return _form.serialize((k, _unwrap(v)) for k, v in from_input(input))

parse

parse(query) -> UrlParams

A query string (? optional) as URLSearchParams reads it: + is a space and bad escapes stay as written.

ParameterTypeDescription
querystr

Returns UrlParams

def parse(query: str) -> UrlParams:
    """A query string (``?`` optional) as ``URLSearchParams`` reads it:
    ``+`` is a space and bad escapes stay as written."""
    return UrlParams(_form.parse(to_well_formed(query).removeprefix("?")))

current_redacted_names

current_redacted_names() -> tuple[Pattern, ...]

CurrentRedactedNames of the running fiber, or the default.

Returns tuple[Pattern, ...]

def current_redacted_names() -> tuple[Pattern, ...]:
    """``CurrentRedactedNames`` of the running fiber, or the default."""
    from pyfect._fiber import current_fiber

    fiber = current_fiber()
    return CurrentRedactedNames.default() if fiber is None else fiber.get_ref(CurrentRedactedNames)

redact_url

redact_url(url, redacted_names=None) -> str

url with its userinfo replaced by REDACTED:REDACTED and the values of the redacted query parameters by REDACTED (by default those of the running fiber's CurrentRedactedNames).

ParameterTypeDescription
urlstr
redacted_namesSequence[Pattern] | None = None

Returns str

def redact_url(url: str, redacted_names: Sequence[Pattern] | None = None) -> str:
    """``url`` with its userinfo replaced by ``REDACTED:REDACTED`` and the
    values of the redacted query parameters by ``REDACTED`` (by default
    those of the running fiber's ``CurrentRedactedNames``)."""
    names = current_redacted_names() if redacted_names is None else redacted_names
    if "@" in url:
        url = _redact_userinfo(url)
    query_start = url.find("?")
    if query_start == -1 or not names:
        return url
    hash_start = url.find("#")
    if hash_start != -1 and hash_start < query_start:
        return url
    query_end = len(url) if hash_start == -1 else hash_start
    return (
        url[: query_start + 1]
        + _redact_query(url[query_start + 1 : query_end], names)
        + url[query_end:]
    )