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#
| Attribute | Type | Description |
|---|---|---|
EMPTY | Headers |
Types#
| Type | Definition | Description |
|---|---|---|
Pattern | type 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. |
Input | type Input = Mapping[str, str | Sequence[str] | None] | Iterable[tuple[str, str]] | Headers | What |
RetryAfter | type RetryAfter = RetryAfterDuration | RetryAfterDateTime |
Classes#
Functions#
from_input#
from_input(input=None) -> HeadersHeaders 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.
| Parameter | Type | Description |
|---|---|---|
input | Input | 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| Parameter | Type | Description |
|---|---|---|
name | str | |
patterns | Sequence[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 Falsecurrent_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.
| Parameter | Type | Description |
|---|---|---|
input | str |
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) -> strvalue as an IMF-fixdate (Sun, 06 Nov 1994 08:49:37 GMT).
| Parameter | Type | Description |
|---|---|---|
value | datetime |
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) -> RetryAfterDurationA Retry-After of duration; negative is zero, infinite raises
ValueError.
| Parameter | Type | Description |
|---|---|---|
duration | DurationInput |
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| Parameter | Type | Description |
|---|---|---|
date_time | datetime |
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.
| Parameter | Type | Description |
|---|---|---|
input | str |
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) -> strWhole seconds rounded up, or an IMF-fixdate.
| Parameter | Type | Description |
|---|---|---|
value | RetryAfter |
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) -> DurationHow long to wait from now_millis (epoch milliseconds); never
negative.
| Parameter | Type | Description |
|---|---|---|
value | RetryAfter | |
now_millis | float |
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))