Skip to content

yggdrasil.io.request

request

PreparedRequest 

PreparedRequest(
    method: str,
    url: URL,
    headers: MutableMapping[str, str],
    tags: MutableMapping[str, str],
    buffer: Optional[Holder],
    sent_at: Optional[datetime],
    sender: Optional[UserInfo] = None,
    auth: Optional[Authorization] = None,
    send_config: Optional["SendConfig"] = None,
    session: "Session | None" = None,
)

Immutable-ish request descriptor — fields are normalized in init.

_session is a transient back-reference used by :meth:attach_session; it's deliberately excluded from :meth:__getstate__ so a request stays portable when pickled to Spark executors and re-binds via attach_session once it lands on the worker. Per-request request/response hooks live on the owning :class:Session (_prepare_request / _prepare_response).

sender property 

sender: UserInfo | None

:class:UserInfo snapshot for the side issuing this request.

Defaults to UserInfo.current() at construction time. Use :meth:with_sender to swap it for a different snapshot (returns a new request — :class:PreparedRequest is immutable-ish, so the underlying field is read-only).

send_config_or_default property 

send_config_or_default: 'SendConfig'

Return :attr:send_config or the shared default singleton.

local_cache_config property 

local_cache_config: 'CacheConfig | None'

Per-request local :class:CacheConfig, delegated to :attr:send_config.

remote_cache_config property 

remote_cache_config: 'CacheConfig | None'

Per-request remote :class:CacheConfig, delegated to :attr:send_config.

holder property 

holder: Optional[Holder]

The :class:Holder backing the request body — alias for :attr:buffer.

auth property writable 

auth: Optional[Authorization]

The :class:Authorization handler bound to this request, if any.

When set, :meth:prepare_authorization resolves it lazily into the Authorization header just before the request is sent — every send picks up a freshly-minted header value.

partition_key property 

partition_key: int

xxh3_64 of the joined :meth:partition_values — int64 partition column.

body_hash property 

body_hash: int

xxh3_64 digest of the body bytes; 0 when body is absent.

Non-nullable in the schema — callers that need a "missing" signal should branch on :attr:buffer or :attr:body_size.

private_url_hash property 

private_url_hash: int

xxh3_64 of (method, URL) exactly as captured (userinfo + full query).

public_url_hash property 

public_url_hash: int

xxh3_64 of (method, URL) after anonymize('remove') — userinfo and sensitive query params dropped, so this hash is stable across the cache's anonymize step. Method is mixed in so verbs don't collide.

hash property 

hash: int

xxh3_64 over (method, url, headers, body) — overall identity, including sensitive bits (userinfo, Authorization, …).

Use :attr:public_hash for matches that should survive cache anonymization (drops userinfo / sensitive query params / sensitive headers).

public_hash property 

public_hash: int

xxh3_64 over the anonymize='remove' projection of (method, url, headers, body) — the cross-system identity that survives cache anonymization.

with_sender 

with_sender(sender: UserInfo | Mapping[str, Any] | None) -> 'HTTPRequest'

Return a copy of this request with :attr:sender replaced.

Accepts a :class:UserInfo, a struct-shaped mapping (matching :data:USERINFO_STRUCT), or None to clear the snapshot.

open 

open(mode: str = 'rb+') -> Optional[IO]

Open a fresh :class:IO cursor over the request's holder.

Returns None when the request has no body. Dispatches to the format-specific leaf via the holder's media type. The returned cursor is non-owning.

prepare_authorization 

prepare_authorization() -> 'HTTPRequest'

Resolve the bound :class:Authorization handler into the header.

No-op when no handler is bound. Calls handler.authorization each time, so handlers that refresh internally (e.g. MSAL) emit the current token on every send.

partition_values 

partition_values() -> dict[str, Any]

Hook for subclasses to define what feeds partition_key.

Returns the ordered mapping that gets fed to :attr:partition_key's xxh3_64 digest. Override to bucket requests differently — e.g. by tenant id, by url.host only, by a fixed shard. Order is stable: the helper concatenates values in iteration order so two configs that disagree on key ordering hash to different partitions.

Default: {"host": url.host, "path": url.path} — every call to the same endpoint shares one partition leaf.

values_to_arrow_batch classmethod 

values_to_arrow_batch(requests: 'Iterable[PreparedRequest]') -> pa.RecordBatch

Build one :class:pa.RecordBatch from N requests in a single C++ pass.

Counterpart to :meth:Response.values_to_arrow_batch — same rationale: collect arrow_values once per request, hand the list of dicts to pyarrow, get back one RecordBatch with N rows. Replaces the pa.Table.from_batches([r.to_arrow_batch(...) for r in N]) shape with a single C++ struct walk; at 64 rows this is ~30x faster than per-row builds plus a downstream concat.

from_record classmethod 

from_record(
    record: "Mapping[str, Any]", *, normalize: bool = True
) -> "HTTPRequest"

Build a :class:PreparedRequest from a row-shaped mapping.

HTTPRequest 

HTTPRequest(
    method: str,
    url: URL,
    headers: MutableMapping[str, str],
    tags: MutableMapping[str, str],
    buffer: Optional[Holder],
    sent_at: Optional[datetime],
    sender: Optional[UserInfo] = None,
    auth: Optional[Authorization] = None,
    send_config: Optional["SendConfig"] = None,
    session: "Session | None" = None,
)

Immutable-ish request descriptor — fields are normalized in init.

_session is a transient back-reference used by :meth:attach_session; it's deliberately excluded from :meth:__getstate__ so a request stays portable when pickled to Spark executors and re-binds via attach_session once it lands on the worker. Per-request request/response hooks live on the owning :class:Session (_prepare_request / _prepare_response).

sender property 

sender: UserInfo | None

:class:UserInfo snapshot for the side issuing this request.

Defaults to UserInfo.current() at construction time. Use :meth:with_sender to swap it for a different snapshot (returns a new request — :class:PreparedRequest is immutable-ish, so the underlying field is read-only).

send_config_or_default property 

send_config_or_default: 'SendConfig'

Return :attr:send_config or the shared default singleton.

local_cache_config property 

local_cache_config: 'CacheConfig | None'

Per-request local :class:CacheConfig, delegated to :attr:send_config.

remote_cache_config property 

remote_cache_config: 'CacheConfig | None'

Per-request remote :class:CacheConfig, delegated to :attr:send_config.

holder property 

holder: Optional[Holder]

The :class:Holder backing the request body — alias for :attr:buffer.

auth property writable 

auth: Optional[Authorization]

The :class:Authorization handler bound to this request, if any.

When set, :meth:prepare_authorization resolves it lazily into the Authorization header just before the request is sent — every send picks up a freshly-minted header value.

partition_key property 

partition_key: int

xxh3_64 of the joined :meth:partition_values — int64 partition column.

body_hash property 

body_hash: int

xxh3_64 digest of the body bytes; 0 when body is absent.

Non-nullable in the schema — callers that need a "missing" signal should branch on :attr:buffer or :attr:body_size.

private_url_hash property 

private_url_hash: int

xxh3_64 of (method, URL) exactly as captured (userinfo + full query).

public_url_hash property 

public_url_hash: int

xxh3_64 of (method, URL) after anonymize('remove') — userinfo and sensitive query params dropped, so this hash is stable across the cache's anonymize step. Method is mixed in so verbs don't collide.

hash property 

hash: int

xxh3_64 over (method, url, headers, body) — overall identity, including sensitive bits (userinfo, Authorization, …).

Use :attr:public_hash for matches that should survive cache anonymization (drops userinfo / sensitive query params / sensitive headers).

public_hash property 

public_hash: int

xxh3_64 over the anonymize='remove' projection of (method, url, headers, body) — the cross-system identity that survives cache anonymization.

with_sender 

with_sender(sender: UserInfo | Mapping[str, Any] | None) -> 'HTTPRequest'

Return a copy of this request with :attr:sender replaced.

Accepts a :class:UserInfo, a struct-shaped mapping (matching :data:USERINFO_STRUCT), or None to clear the snapshot.

open 

open(mode: str = 'rb+') -> Optional[IO]

Open a fresh :class:IO cursor over the request's holder.

Returns None when the request has no body. Dispatches to the format-specific leaf via the holder's media type. The returned cursor is non-owning.

prepare_authorization 

prepare_authorization() -> 'HTTPRequest'

Resolve the bound :class:Authorization handler into the header.

No-op when no handler is bound. Calls handler.authorization each time, so handlers that refresh internally (e.g. MSAL) emit the current token on every send.

partition_values 

partition_values() -> dict[str, Any]

Hook for subclasses to define what feeds partition_key.

Returns the ordered mapping that gets fed to :attr:partition_key's xxh3_64 digest. Override to bucket requests differently — e.g. by tenant id, by url.host only, by a fixed shard. Order is stable: the helper concatenates values in iteration order so two configs that disagree on key ordering hash to different partitions.

Default: {"host": url.host, "path": url.path} — every call to the same endpoint shares one partition leaf.

values_to_arrow_batch classmethod 

values_to_arrow_batch(requests: 'Iterable[PreparedRequest]') -> pa.RecordBatch

Build one :class:pa.RecordBatch from N requests in a single C++ pass.

Counterpart to :meth:Response.values_to_arrow_batch — same rationale: collect arrow_values once per request, hand the list of dicts to pyarrow, get back one RecordBatch with N rows. Replaces the pa.Table.from_batches([r.to_arrow_batch(...) for r in N]) shape with a single C++ struct walk; at 64 rows this is ~30x faster than per-row builds plus a downstream concat.

from_record classmethod 

from_record(
    record: "Mapping[str, Any]", *, normalize: bool = True
) -> "HTTPRequest"

Build a :class:PreparedRequest from a row-shaped mapping.