Skip to main content
Settings machinery: the base class, the cache-reset registry, and the owned-prefix audit. Leaf settings live next to the impl they configure (tai42_kit.llm, tai42_kit.clients, tai42_kit.logging).

DEFAULT_ENV_FILE

tai42_kit.settings.env_file.DEFAULT_ENV_FILE

ENV_IGNORE_EMPTY

tai42_kit.settings.base.ENV_IGNORE_EMPTY
tai42_kit.settings.owned_prefix.KUBERNETES_SERVICE_LINK_SUFFIX_RE

TAI_DEFAULT_ENV_PREFIX

tai42_kit.settings.default_namespace.TAI_DEFAULT_ENV_PREFIX

DefaultNamespaceMixin

tai42_kit.settings.default_namespace.DefaultNamespaceMixin
Adds the TAI_DEFAULT_* per-field fallback to a settings class. Declare tai_default_fields ({field_name: default_key}) on the subclass to enable it. An empty map (the default) leaves the source pipeline untouched, so a class that mixes this in without a map behaves as one that does not. Attributes

Members

settings_customise_sources

tai42_kit.settings.default_namespace.DefaultNamespaceMixin.settings_customise_sources
Append the TAI_DEFAULT_* fallback sources beneath the specific settings sources. The specific sources are the next class’s in the MRO (the settings base’s, whose dotenv slot holds the kit’s cached dotenv source). Parameters

EnvNameIndex

tai42_kit.settings.env_names.EnvNameIndex
The env names a set of env readers reads, resolved to the scalar fields they set. Built with of; immutable.

Members

of

tai42_kit.settings.env_names.EnvNameIndex.of
The index of readers; a nested reader that is not among them sets nothing. Parameters

fields_set_by

tai42_kit.settings.env_names.EnvNameIndex.fields_set_by
Every scalar field of the index’s readers the env name name can set; empty when it sets none. Parameters

EnvReader

tai42_kit.settings.reader_descriptions.EnvReader
One pydantic-settings class as the settings layer reads it from the env; names and shapes, never values. Attributes

EnvReaderField

tai42_kit.settings.reader_descriptions.EnvReaderField
One field of an env reader: the env names that set it and how a delimited path names it. Attributes

KeyMaterial

tai42_kit.settings.base.KeyMaterial

ReloadClass

tai42_kit.settings.base.ReloadClass

RespawnClassBindings

tai42_kit.settings.registry.RespawnClassBindings
An opaque token for the respawn-class bindings held at one moment. Made by respawn_class_bindings and read only by restore_respawn_class_bindings.

SettingsClassInfo

tai42_kit.settings.registry.SettingsClassInfo
A registered settings class, identified by its qualified name. Attributes

SettingsFieldInfo

tai42_kit.settings.registry.SettingsFieldInfo
One env-configurable field on a settings class, as plain data. Attributes

SettingsFieldRef

tai42_kit.settings.env_names.SettingsFieldRef
One scalar settings field: its reader’s qualified name and the field’s name. Attributes

StaleHolder

tai42_kit.settings.cache_registry.StaleHolder
A still-live cached settings instance stamped with a retired epoch. settings_type and holders are module.qualname strings (the settings class, and the type of each object still referencing the instance). Attributes

TaiBaseSettings

tai42_kit.settings.base.TaiBaseSettings
Base for env-configurable settings groups; concrete subclasses self-register. A settings class reads the env file named by its tai_env_file class attribute (default .env), unless that file is the file config mode’s stored env; the file is parsed once per file identity. A subclass that sets model_config['env_file'] is refused at import. Attributes

Members

settings_customise_sources

tai42_kit.settings.base.TaiBaseSettings.settings_customise_sources
Put the kit’s cached dotenv source in the dotenv slot. The source reads tai_env_file, or no file when that file is the stored env or its reads are suspended (env_file_in_effect). Every other option of the source is read from settings_cls.model_config, as the framework’s own source reads it. Parameters

with_fallbacks

tai42_kit.settings.base.TaiBaseSettings.with_fallbacks
Return a dict with defaults added for missing keys (never override user config). Parameters

load_with_fallbacks

tai42_kit.settings.base.TaiBaseSettings.load_with_fallbacks
Parse user_config JSON (or empty) and merge it over the defaults. Parameters

UnknownOwnedSettingError

tai42_kit.settings.owned_prefix.UnknownOwnedSettingError
An env name under an owned settings prefix names no registered setting.

bind_respawn_class_env

tai42_kit.settings.registry.bind_respawn_class_env
Bind every registered respawn-class field under the process env as it is now. Called once a lifespan applied its env, before it builds the resources behind those values: a group registered later binds its own fields at its registration. Overwrites every binding an earlier bind recorded.

bind_unbound_respawn_class_env

tai42_kit.settings.registry.bind_unbound_respawn_class_env
Bind every registered respawn-class field that holds no binding under the process env as it is now. Called once the resources behind the current env are committed: a group whose binding a restore dropped is bound under the env those resources were built under. A field already bound keeps its binding. Nothing is bound while no lifespan has bound the respawn-class env.

changes_only_by_respawn

tai42_kit.settings.registry.changes_only_by_respawn
Whether every value of the registered settings group cls changes only by a process respawn or restart. True when cls is registered and every field’s reload class is recycle or excluded; a field that references a nested group is judged by that group’s own registered fields, recursively. False for an unregistered class (a plain BaseSettings, a registry_exclude base, a class with no fields), for a nested group that is unregistered or references back into the groups being judged, and for any hot field.

declare_env_reader

tai42_kit.settings.reader_descriptions.declare_env_reader
Declare cls a reader of the applied env, with every nested settings class it reaches. Each class is described (describe_env_reader) and enters env_readers, not the settings registry; each description reaches the on_env_reader_described listeners, cls first. A listener’s exception propagates.

decode_env_readers

tai42_kit.settings.reader_descriptions.decode_env_readers
The env readers encode_env_readers encoded in body; a body of another shape raises. Parameters

describe_env_reader

tai42_kit.settings.reader_descriptions.describe_env_reader
The description of the pydantic-settings class cls: every env name it reads and how it nests. A field whose type has no resolvable JSON-schema type raises, naming the field.

encode_env_readers

tai42_kit.settings.reader_descriptions.encode_env_readers
The canonical JSON of a set of env readers: the same set gives the same text in any order. Parameters

env_file_identity

tai42_kit.settings.env_file.env_file_identity
The identity of the regular file at path, or None when there is none. A missing path, a directory, a FIFO, or a path stat cannot reach answers None, as Path.is_file() answers False for each. Parameters

env_file_in_effect

tai42_kit.settings.env_file.env_file_in_effect
The env file a settings construction reads: declared, or none when it is not read. declared is not read when it resolves to the file config mode’s stored env, or when its reads are suspended (env_file_reads_suspended). Parameters

env_file_reads_suspended

tai42_kit.settings.env_file.env_file_reads_suspended
Read the env file at path in no settings construction inside the block. path is resolved on entry (a relative path against the working directory, symlinks followed), and a settings class whose env file resolves to the same file reads no env file inside the block; an env file at any other path is still read. Blocks nest, each adding its path. The state is held in a context variable: a task created inside the block copies the context and so skips the file too, while a thread started with threading.Thread starts from an empty context and reads it, unless the interpreter makes threads inherit the context (sys.flags.thread_inherit_context). Parameters

env_readers

tai42_kit.settings.reader_descriptions.env_readers
Every env reader of this process: each registered settings group and each declared reader, sorted.

fold_env_name

tai42_kit.settings.base.fold_env_name
name as the settings layer matches env names: upper-cased. A settings group reads env names case-insensitively (pydantic-settings’ default), so app_args_port and APP_ARGS_PORT set the same field; the registry records each name upper-cased. A test of an env name against a set of settings names folds both sides here. Parameters tai42_kit.settings.owned_prefix.is_kubernetes_service_link
True when the upper-cased key is <NAME>_<suffix> for a <NAME> in names. <suffix> must match KUBERNETES_SERVICE_LINK_SUFFIX_RE. Parameters

keyed_settings_cache

tai42_kit.settings.cache_registry.keyed_settings_cache
Cache a one-argument settings accessor per key, cleared on reset and re-read when the env file changes. An entry is served while the env file keeps the identity it had when the entry was built; the env file is the one settings read (env_file_in_effect), so a file they do not read, such as the stored env, rebuilds nothing. reset_all_settings() drops every entry. A settings instance is epoch-stamped on construction like settings_cache’s. A build that raises stores nothing, so the next call builds again. One accessor exists per qualified name, re-bound by a re-import exactly as settings_cache’s. Parameters tai42_kit.settings.owned_prefix.kubernetes_service_link_names
The <NAME> of every Service whose link family is present in environ. Empty unless KUBERNETES_SERVICE_HOST is in environ. Otherwise each <NAME> for which BOTH <NAME>_SERVICE_HOST and <NAME>_PORT are in environ (keys compared upper-cased). Parameters

not_configured_message

tai42_kit.settings.require.not_configured_message
The named-error message for an unset connection setting. default_var is the field’s TAI_DEFAULT_* alternative, named in the message when the field participates in the shared namespace; omit it for a field that only its own env var can set. Parameters

on_env_reader_described

tai42_kit.settings.reader_descriptions.on_env_reader_described
Subscribe listener to every env reader described from now on; returns listener. Called with the description of each settings group registered (after the on_settings_registered listeners, before any value of it is read) and of each declared reader. Subscribing the same listener again does nothing. Parameters

on_settings_registered

tai42_kit.settings.registry.on_settings_registered
Subscribe listener to every settings group registered from now on; returns listener. The listener is called with a copy of each registration (a re-import’s re-registration included), once the group is in registered_settings and before any value of it is read. Subscribing the same listener again does nothing. Parameters

owned_env_prefixes

tai42_kit.settings.owned_prefix.owned_env_prefixes
Every env prefix a registered group declares owned.

present_env_value

tai42_kit.settings.base.present_env_value
The value the settings layer reads for var; None when absent or empty. Every spelling of var in env counts (fold_env_name): an empty one is absent (the kit’s empty-is-absent rule) and of the others the last one wins, as the settings layer’s env source reads them. Parameters

refuse_unknown_owned_env

tai42_kit.settings.owned_prefix.refuse_unknown_owned_env
Raise UnknownOwnedSettingError naming every unknown key; no-op when none. source names where the keys were read (it leads the message). Parameters

register_settings_reset

tai42_kit.settings.cache_registry.register_settings_reset
Register a hook that resets settings-derived state on global reset. Parameters

registered_settings

tai42_kit.settings.registry.registered_settings
Snapshot of every registered settings group, in registration order. Returns model copies so callers cannot mutate the registry’s internals.

require

tai42_kit.settings.require.require
The configured value, or raise the named error when it is None. Parameters

require_secret

tai42_kit.settings.require.require_secret
The secret’s plaintext, or raise on unset OR empty — fail CLOSED. A secret that gates a trust boundary must not be satisfiable by an empty value, so both the unset and the empty cases raise. Parameters

reset_all_settings

tai42_kit.settings.cache_registry.reset_all_settings
Drop every registered settings cache, then run the reset hooks.

respawn_class_bindings

tai42_kit.settings.registry.respawn_class_bindings
The respawn-class bindings held now, for restore_respawn_class_bindings to put back.

respawn_class_env_drift

tai42_kit.settings.registry.respawn_class_env_drift
The env vars of the bound respawn-class fields whose value now differs from the value they were bound under. Each value is read as the settings layer reads it, under every name that sets the field (settings_field_env_value): the field’s own names, its nested groups’ JSON names and its delimited names, from the process env now and from the env the field was bound under. Such a value takes effect only in a respawned process. Empty while nothing is bound.

restamp_settings_born_after

tai42_kit.settings.cache_registry.restamp_settings_born_after
Stamp every live settings instance constructed after mark with the current epoch. A serving generation built off to the side reads its settings while the epoch it will serve under is not yet current, so those instances carry the epoch it replaces. Once its epoch is current, the builder re-stamps everything constructed since the mark it took when the build began: a sweep of the replaced epoch then judges only the instances read before the build, and the new generation’s own instances are judged when its epoch retires. Parameters

restore_respawn_class_bindings

tai42_kit.settings.registry.restore_respawn_class_bindings
Put back the respawn-class bindings bindings holds, dropping every binding made since. A group registered since keeps its registration and holds no binding until it registers again (a module re-import) or bind_unbound_respawn_class_env binds it, under the env then. A module that stays imported never registers again, so its fields stay unbound until that call. Parameters

settings_birth_mark

tai42_kit.settings.cache_registry.settings_birth_mark
The birth number of the most recently stamped settings instance (0 before any). Every instance stamped after this call has a larger birth number, so the mark separates what was constructed before it from what is constructed after it (see restamp_settings_born_after).

settings_cache

tai42_kit.settings.cache_registry.settings_cache
Cache a zero-arg settings accessor, register it for reset, and epoch-stamp it. Stamping happens on the CONSTRUCTION path (cache miss), so the stamp records the epoch the instance was born under; a cached hit returns the same stamped instance, and a reset clears the cache so the next call rebuilds and re-stamps under the then-current epoch. One accessor exists per qualified name: decorating a function whose name is already registered (a module re-import) re-binds that accessor to the new function, clears its cache and returns the same wrapper. Parameters

settings_field_env_value

tai42_kit.settings.env_names.settings_field_env_value
The value env gives the scalar field field of the settings group group; None when none. group is the group’s qualified name. Read as the settings layer reads it. In precedence order, highest first: the registered groups that nest group (outermost first), each through its JSON name with its delimited names merged over it; then the field’s own names (_own_layers). Objects from several of these merge key by key, as the settings layer combines them. Empty values are absent. The value is in env form: a string read from one name as it is, anything else JSON-encoded. A name whose value must be JSON and is not raises, and so does a nested-group reference, which holds no value of its own. Parameters

settings_fields_set_by

tai42_kit.settings.env_names.settings_fields_set_by
Every registered scalar settings field the env name name can set; empty when it sets none. Parameters

sweep_stale_settings

tai42_kit.settings.cache_registry.sweep_stale_settings
Report every settings instance stamped with retired_epoch that something still holds. The roster holds only settings whose values can change within the process, so the sweep judges only those. Walks the roster for instances whose stamp is the retired epoch and are still alive. When any is found, cyclic garbage is collected first, so an instance that only unreachable objects keep (the finished frame of a cancelled task awaiting collection) is freed rather than reported. Each instance still alive after that is reachable, which is a stale-config leak: it is logged at ERROR naming its holders (a referrer’s type, or the function and file:line of a frame or coroutine that keeps it) and returned, so a probe/e2e can assert zero. Nothing is dropped. Parameters

unbind_respawn_class_env

tai42_kit.settings.registry.unbind_respawn_class_env
Drop the bound respawn-class env (a lifespan’s end); nothing is bound until the next bind.

unknown_owned_env_keys

tai42_kit.settings.owned_prefix.unknown_owned_env_keys
(key, prefix) for each key under an owned prefix that no registered group accepts, sorted by key. Comparison is upper-cased; the accepted set is the union of accepted_env_vars of every registered group (any prefix), so an alias declared elsewhere is accepted. A key under several owned prefixes is reported with the longest. With service_link_env (the process environment), an unaccepted key for which is_kubernetes_service_link(key, kubernetes_service_link_names(service_link_env)) holds is not reported: the container runtime injects a Service’s link family into every pod of its namespace, and a Service named like an owned prefix yields names under it. A lone <NAME>_PORT or <NAME>_SERVICE_HOST, or any key outside a Kubernetes pod, is reported like any unknown name. Parameters