blackbull.env

blackbull.env

Immutable environment settings snapshot, declared once per setting.

Each Settings field is the whole declaration of one environment variable: its name, type, default, range, config-file key and description. get_settings, blackbull run --config and the reference page all read them from here. After changing the environment in a test, call reset_settings_cache().

DerivedCap

Bases: int

A connection cap auto derived from RLIMIT_NOFILE, not one an operator named; the server may lower it to the descriptors left.

Environment

Bases: StrEnum

Which deployment the process thinks it is, read from BLACKBULL_ENV.

Reachable as get_settings().env. A value that is not one of these three resolves to DEVELOPMENT rather than raising, so a misspelled production gets the looser of the two behaviours and says nothing about it — worth asserting on at startup if it matters to you.

Two behaviours turn on it, and both tighten in PRODUCTION: StaticFiles declines to serve anything, and the default error handler answers without exception detail; DEVELOPMENT shows that detail to a loopback, unproxied peer only. The fault-injection servers refuse to start there at all.

Settings dataclass

Immutable snapshot of all runtime settings.

Construct via get_settings rather than directly so that environment variables are read at the right time. A directly constructed Settings leaves max_connections uncapped.

header_deadline property

header_timeout as a deadline: None when it is disabled.

apply_event_loop_policy(cfg=None)

Install uvloop as the asyncio event loop policy if BB_UVLOOP=1.

Call this once before each asyncio.run() entry point. Safe to call multiple times (subsequent calls are no-ops when the policy is already set). If uvloop is not installed a warning is logged and the standard policy is kept; the server still starts.

get_settings() cached

Return cached process-wide settings.

Environment changes after the first call have no effect until reset_settings_cache(); tests changing them must reset in teardown.

read_setting(name)

One Settings field read from the environment now, uncached.

Use it at import and in logging: get_settings at import would cache values before blackbull run --config exports them.

reset_settings_cache()

Clear the cached Settings.

Call this in test teardown if the test mutated env vars that get_settings reads. Without this, the cached settings reflect whatever environment was visible the first time get_settings() ran in the process.

resolve_max_connections(raw)

Resolve BB_MAX_CONNECTIONS — auto, 0, or a number.

auto (the default) derives the cap from this process's own RLIMIT_NOFILE, less a reserve. An explicit number is honoured as given, not clamped to that budget: an operator who names a number means it. 0 disables the cap.

Why a derived default is safe to ship, and what it does not bound, is argued in docs/about/security-model.md (qualification 2).

setting(env, default, *, section, doc, minimum=None, parse=None, config=None, shown=None)

Declare one environment variable as a Settings field.

A value that does not parse, or is below minimum, falls back to default. parse replaces that rule and also receives None when the variable is unset. config is the [section] key that blackbull run --config maps onto env; shown is the default as the reference page states it, when it is a rule rather than a value.