GitHub

API reference for headers.

HTTP headers (Effect's Headers): an immutable mapping from lowercased header names to values, plus the header value formats the client reads (HTTP dates and Retry-After).

Lookups are case-insensitive (headers["Content-Type"]), and every update gives a new Headers::

headers = from_input({"Content-Type": "text/plain"}).set("X-Id", "1")
headers["x-id"]   # "1"

Values

AttributeTypeDescription
EMPTYHeaders

Types

TypeDefinitionDescription
Patterntype Pattern = str | re.Pattern[str]

A header (or URL parameter) name to redact: a name compared without case, or a regular expression searched in the name.

Inputtype Input = Mapping[str, str | Sequence[str] | None] | Iterable[tuple[str, str]] | Headers

What from_input takes: a mapping (a sequence value is joined with ", ", a None value is skipped) or (name, value) pairs.

RetryAftertype RetryAfter = RetryAfterDuration | RetryAfterDateTime

Classes

Functions

from_input

from_input(input=None) -> Headers

Headers from a mapping or (name, value) pairs. Names are lowercased; list values in a mapping and repeated names in pairs are joined with ", ", and None values are left out. A comma-joined set-cookie is not safe to forward as one header: read a client response's cookies instead.

ParameterTypeDescription
inputInput | None = None

Returns Headers

def from_input(input: Input | None = None) -> Headers:
    """Headers from a mapping or ``(name, value)`` pairs. Names are lowercased; list values
    in a mapping and repeated names in pairs are joined with ``", "``, and ``None`` values
    are left out. A comma-joined ``set-cookie`` is not safe to forward as one header: read a
    client response's ``cookies`` instead."""
    if input is None:
        return EMPTY
    if isinstance(input, Headers):
        return input
    if isinstance(input, Mapping):
        out: dict[str, str] = {}
        record = cast("Mapping[str, str | Sequence[str] | None]", input)
        for key, value in record.items():
            if isinstance(value, str):
                out[key.lower()] = value
            elif value is not None:
                out[key.lower()] = ", ".join(value)
        return Headers._unsafe(out)  # pyright: ignore[reportPrivateUsage]
    return Headers._unsafe(_header_lines.joined((name.lower(), value) for name, value in input))  # pyright: ignore[reportPrivateUsage]

is_redacted_name

is_redacted_name(name, patterns) -> bool
ParameterTypeDescription
namestr
patternsSequence[Pattern]

Returns bool

def is_redacted_name(name: str, patterns: Sequence[Pattern]) -> bool:
    lower = name.lower()
    for pattern in patterns:
        if isinstance(pattern, str):
            if pattern.lower() == lower:
                return True
        elif pattern.search(name) is not None:
            return True
    return False

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)

parse_http_date

parse_http_date(input) -> Result[datetime, HeaderParseError]

An HTTP date as an aware UTC datetime.

ParameterTypeDescription
inputstr

Returns Result[datetime, HeaderParseError]

def parse_http_date(input: str) -> Result[datetime, HeaderParseError]:
    """An HTTP date as an aware UTC ``datetime``."""
    parsed = _http_date(input.strip())
    if parsed is None:
        return Err(HeaderParseError.from_reason("InvalidHttpDate", input))
    return Ok(parsed)

format_http_date

format_http_date(value) -> str

value as an IMF-fixdate (Sun, 06 Nov 1994 08:49:37 GMT).

ParameterTypeDescription
valuedatetime

Returns str

def format_http_date(value: datetime) -> str:
    """``value`` as an IMF-fixdate (``Sun, 06 Nov 1994 08:49:37 GMT``)."""
    return format_datetime(value.astimezone(UTC).replace(microsecond=0), usegmt=True)

retry_after_duration

retry_after_duration(duration) -> RetryAfterDuration

A Retry-After of duration; negative is zero, infinite raises ValueError.

ParameterTypeDescription
durationDurationInput

Returns RetryAfterDuration

def retry_after_duration(duration: DurationInput) -> RetryAfterDuration:
    """A ``Retry-After`` of ``duration``; negative is zero, infinite raises
    ``ValueError``."""
    parsed = from_input_unsafe(duration)
    if not parsed.is_finite():
        raise ValueError("Cannot create a Retry-After value from an infinite duration")
    return RetryAfterDuration(zero if parsed.is_negative() else parsed)

retry_after_date_time

retry_after_date_time(date_time) -> RetryAfterDateTime
ParameterTypeDescription
date_timedatetime

Returns RetryAfterDateTime

def retry_after_date_time(date_time: datetime) -> RetryAfterDateTime:
    return RetryAfterDateTime(date_time)

parse_retry_after

parse_retry_after(input) -> Result[RetryAfter, HeaderParseError]

Whole seconds or an HTTP date; anything else (negative, fractional, exponent forms) is an InvalidRetryAfter.

ParameterTypeDescription
inputstr

Returns Result[RetryAfter, HeaderParseError]

def parse_retry_after(input: str) -> Result[RetryAfter, HeaderParseError]:
    """Whole seconds or an HTTP date; anything else (negative, fractional,
    exponent forms) is an ``InvalidRetryAfter``."""
    trimmed = input.strip()
    if is_digits(trimmed):
        whole = parse_digits(trimmed)
        if whole is None:  # more digits than int() reads
            return Err(HeaderParseError.from_reason("InvalidRetryAfter", input))
        # The millisecond form while it is exact; beyond that, whole nanoseconds.
        safe = whole * 1000 <= _MAX_SAFE
        return Ok(RetryAfterDuration(seconds(whole) if safe else nanos(whole * _NANOS_PER_SECOND)))
    parsed = _http_date(trimmed)
    if parsed is None:
        return Err(HeaderParseError.from_reason("InvalidRetryAfter", input))
    return Ok(RetryAfterDateTime(parsed))

format_retry_after

format_retry_after(value) -> str

Whole seconds rounded up, or an IMF-fixdate.

ParameterTypeDescription
valueRetryAfter

Returns str

def format_retry_after(value: RetryAfter) -> str:
    """Whole seconds rounded up, or an IMF-fixdate."""
    match value:
        case RetryAfterDuration(duration):
            whole = (duration.to_nanos_unsafe() + _NANOS_PER_SECOND - 1) // _NANOS_PER_SECOND
            return str(whole)
        case RetryAfterDateTime(date_time):
            return format_http_date(date_time)

retry_after_delay

retry_after_delay(value, now_millis) -> Duration

How long to wait from now_millis (epoch milliseconds); never negative.

ParameterTypeDescription
valueRetryAfter
now_millisfloat

Returns Duration

def retry_after_delay(value: RetryAfter, now_millis: float) -> Duration:
    """How long to wait from ``now_millis`` (epoch milliseconds); never
    negative."""
    match value:
        case RetryAfterDuration(duration):
            return duration
        case RetryAfterDateTime(date_time):
            millis = (date_time - _EPOCH) // timedelta(milliseconds=1)
            return millis_duration(max(0.0, millis - now_millis))