Package index • biohttp

Make a call

The entry points. Each one assembles the request, applies the shared defaults, performs it, and caches a success.

get_json(): GET a JSON endpoint
post_json(): POST a JSON body
get_text(): GET a text endpoint

Ask many questions at once

For many questions to one source. Only the entries the cache is missing reach the network.

get_json_many(): GET many JSON endpoints as one batch
post_json_many(): POST many JSON bodies as one batch
get_text_many(): GET many text endpoints as one batch
perform_many(): Perform many requests as one batch

Build and perform your own request

For a call the wrappers do not cover.

req_defaults(): Apply the shared request options
perform(): Perform a request and normalize the result
perform_text(): Perform a request and return the body as text
user_agent(): Build a User-Agent that identifies your caller
is_transient(): Is a response worth retrying

The result envelope

One return shape for every outcome. Nothing here raises on an HTTP or a parse failure.

envelope(): Build a result envelope
status_ok() status_no_data() status_stale() status_rate_limited() status_timeout() status_skipped() status_error(): Envelope constructors, one per status
STATUS_LEVELS: The seven envelope statuses
body_or_null(): The parsed body, or NULL
classify_http(): Turn an HTTP status code into a status
classify_condition(): Turn a failed connection into a status

Failures

One sentence per outcome, in one place. Set biohttp.status_message to supply your own wording or to localise.

status_message(): The user-facing sentence for an outcome
http_error_message(): A user-facing sentence for a failed call
graphql_error(): Catch a GraphQL query error inside a 200

Credentials

For a service that takes its key in the query string rather than a header. See SECURITY.md for the rule on which belongs where.

redact_secrets(): Remove secret values from a string

Circuit breaker

Per-host state. Only a transport failure counts against a host; a 5xx or an unreadable body does not.

breaker_open(): Is a host's breaker open
breaker_record(): Record a call outcome against a host
breaker_reset(): Clear all breaker state

Rate limiting

Pauses, one per host. If a source sends Retry-After, we use it. When a host says you are asking too often, the batched path waits before it tries again instead of going straight back in.

ratelimit_record(): Record a pause for a host
ratelimit_wait(): Wait out a host's recorded pause
ratelimit_reset(): Clear all recorded pauses

Cache

Success-only, memory by default, opt-in disk tier.

cache(): The cache store
cache_key(): Build a cache key
cached(): Serve from cache, or fetch and cache a success
cache_reset(): Empty the cache

What the transport did

Counts per host. Use these if you want to know how much of a batch was a second try, and how often a source pushed back.

transport_stats(): How many requests went out, per host
transport_stats_reset(): Clear the request counts

Utilities

is_blank(): Is a value blank
pluck_at(): Pull a value out of a nested list

Migration

For an app moving off its own HTTP layer. Deprecated on arrival.

as_legacy_envelope(): Convert an envelope to the old four-field shape

Package

biohttp biohttp-package: biohttp: Normalized HTTP Transport with Circuit Breaking and Caching