API Reference

Everything the package exports, in one place. Where a call has an async twin it sits in the same row, because the pair is the point: the synchronous one is right from a thread, a script or a test, and the _async one hands the blocking half to an executor so the event loop is never the thing waiting.

from dynamic_config import DynamicConfig, dynamic_config, set_executor, changed_paths

DynamicConfig(model, key, *, executor=None, secrets=())

Generic[M], so every method that hands a model back hands back your model rather than Any.

DynamicConfig.from_settings(model, key, *, executor=None)

A configuration whose sources come from a pydantic_settings.BaseSettings class's own SettingsConfigDict — its files, its .env, its variable names — so an existing settings class keeps working and gains layering, provenance and hot reload. Refuses what has no engine equivalent (secrets_dir, cli_parse_args, an overridden settings_customise_sources) instead of dropping it. Chain more sources onto the result as usual. See pydantic-settings.

Sources

Each returns the configuration, so they chain. All of them raise once anything has loaded — sources are how a configuration is identified.

A remote store, written in Python

The eight store crates stay in Rust; the door does not. Any object with fetch() and describe() is a remote store here — see RemoteSource.

The same four methods take a compiled store from the opt-in second wheel (pip install dynamic-config-py[remote]): Etcd(...) and Vault(...) from dynamic_config.remote are RemoteSource implementations like any other, and their API is on its own page because they are a separate distribution.

Fetching is explicit, exactly as it is in Rust: a load merges the document that was last fetched and touches no network. The remote layer sits above the files and below the environment.

class OurService(RemoteSource):
    def fetch(self):
        return httpx.get(URL, timeout=5).text, Format.JSON

    def describe(self):
        return "our service"

config = DynamicConfig(Database, key="db").remote(OurService())
config.refresh_remote()
config.init()

Three things a caller has to know, each of which has a test:

• The timeout is the fetch() implementation's. Nothing on the Rust side can interrupt Python that has decided not to return, so the deadline belongs to the client the method calls.
• A raising fetch() is reported, not fatal. It arrives as RemoteError — or AuthError, if that is what was raised — with the original attached as __cause__. Its message is not repeated: a store's exception routinely carries the URL it called. The previous document and the previous model both keep serving.
• A fetch() may read its own configuration — current(), snapshot(), explain() — because no lock is held across it. The one thing it may not do is call refresh_remote(), which is refused by name rather than left to recurse.

describe() is asked once, when the source is installed, because the engine reads it on the load path and a load must not re-enter Python.

Lifecycle

changed_async, changes and events are answered by a notifier thread rather than by polling, so cancelling one is immediate and an idle service does no work at all — see how a wait is answered.

current() and try_current() have no async twin because there is nothing to await: the model is cached on the object, so the read is an attribute lookup on the loop and on a thread alike.

watch has a twin for a narrower reason than the others: the watcher is a thread either way, so what watch_async moves off the loop is only starting it — resolving directories, registering each with the notification backend, spawning the carrier thread. That is syscalls rather than I/O, and it measures a fraction of a millisecond natively; but it grows with the number of directories, and poll_interval takes a baseline scan of everything it watches first, which is single-digit milliseconds over a large directory and worse over the network filesystems that are the reason to poll. A startup handler runs once and would survive either call; the async one is the same work with the wait on a worker.

Watch.stop() has no twin, and that is not an omission: it drops the backend, which closes the channel the watcher thread is parked on, and returns without joining it or waiting out a debounce window. Under a tenth of a millisecond, so a shutdown handler can call it directly.

Runtime layers

The two layers that bracket every source: defaults lose to everything, overrides beat everything.

These take effect on the next load, so a set_override after init() wants a reload() behind it. overrides(...) is the exception, and that is what it is for: it reloads on entry and again on exit.

Diagnostics

Telemetry

Both are a handful of atomic loads: no source is re-read and nothing blocks, which is what makes them cheap enough for a scrape. Exposition renders either as Prometheus text — see Telemetry.

Properties

repr(config) is those three and nothing else — <DynamicConfig Database key='db' generation=3> — which is what a debugger session wants and what a log line can survive: shape, never values, generation=0 meaning nothing has installed yet.

Testing

overrides(**values)

The override layer, scoped to a with block:

with config.overrides(pool_size=1, host="localhost"):
    ...        # reloaded on entry, with those values pinned
               # the previous overrides are restored and reloaded on exit

The long hand is set_override, reload, clear_overrides, reload — four lines whose last two are easy to forget, and forgetting them leaks into the next test through whatever configuration the module built.

• Restores rather than clears. The exit puts back the layer the block found, so a nested with composes and an override set before the block still stands after it.
• Restores on an exception too. A failing assertion inside the block does not decide what the next test sees.
• __ is a dot, the same nesting rule the environment layer uses: pool__max_size=1 means pool.max_size. A field whose own name contains __ cannot be spelled this way — use set_override.
• With no arguments it pins nothing and still restores, which wraps a block that calls set_override itself.

The pytest plugin

The package ships one, and pytest finds it through a pytest11 entry point — installing dynamic-config-py is the whole setup:

def test_the_service_reads_its_file(dynamic_config_workspace):
    (dynamic_config_workspace / "app.toml").write_text('[db]\nport = 5432\n')
    config = DynamicConfig(Database, key="db").file("app.toml")

    assert config.init_and_current().port == 5432

Nothing is autouse — a plugin that arrives with the wheel should not change what a test sees until the test asks. The environment one is usually wanted for every test, which is one fixture in your own conftest.py:

@pytest.fixture(autouse=True)
def _clean_environment(dynamic_config_env):
    dynamic_config_env("APP_")

A suite that turns entry-point discovery off — CI images increasingly set PYTEST_DISABLE_PLUGIN_AUTOLOAD — asks for it by name instead: -p dynamic_config.pytest, on the command line or in addopts.

dynamic_config.pytest imports pytest and the standard library and nothing else — not Pydantic, and not the rest of this package's public surface. It is auto-loaded in every pytest run of every environment the package is installed in, so a dependency there would be a dependency for all of them; the binding's own suite runs on these two fixtures, and a subprocess test imports the module with Pydantic made unimportable.

Module functions

__version__ and __engine_version__

The wheel's version, and the version of the dynamic-config crate compiled into it. The two move independently — the Python package versions on its own schedule — so a bug report can name both.

set_executor(executor)

Process-wide choice of which thread pool pays for the blocking half of the async calls. None restores the loop's own. The pool stays the caller's: it is never shut down here, including at exit. Waiting for a reload uses no executor at all, so this sizes loads and refreshes only — see Async & asyncio.

configure_executor(workers=2, *, thread_name_prefix="dynamic-config")

set_executor with the pool built for you, and owned: the threads are named dynamic-config-blocking-N, and the pool is shut down at interpreter exit. Calling it again replaces the pool and closes the previous one. Returns the pool.

executor(pool=None, *, workers=2)

The choice as a block, restored on the way out. A pool this builds is closed at the end of the block; a pool passed in is left alone, because it is the caller's.

with dynamic_config.executor(workers=4):
    await config.init_async()

secret_paths(model)

Every dotted path in model that is declared secret, in whichever vocabulary the declaration uses: a SecretStr or SecretBytes — through Optional, unions, containers, nested models, Pydantic dataclasses and RootModel — a dataclass field's metadata={"secret": True}, or a msgspec.Meta(extra={"secret": True}). This is what seeds the redaction, and it is derived rather than declared twice, so nobody keeps a second list in step with the first. A field lists every name a file could carry it under (each alias and the field name), because a secret spelled the other way is still a secret; see Aliases.

Values

A configuration with no schema class: pass Values where a model goes, and every load hands back one of these — a Mapping read by dotted path. See Values: a configuration with no schema for what it gives up, and the schemaless chapter for the Rust half.

Values.sub(path)

The subtree at path, as a Values of its own — relative paths below it, so a subsystem can be handed a section without being told where it sits. Empty when the path holds nothing, and empty when it holds a value rather than a table; in is how to tell those apart.

changed_paths(previous, current)

Which paths differ between two models (or mappings), as Change values. Paths only, never values — including for secrets, whose values are compared but never reported.

@dynamic_config(...)

Attaches a configuration to a model class and returns the class.

Every argument is keyword-only, and every one of them is one fluent call on the configuration it builds — the decorator is the declaration-shaped spelling, not a second set of behaviour.

It attaches config, current, try_current, reload, source_of and explain to the class, and refuses a model that declares a field with one of those names.

examples/21_decorator_whole_document.py runs every row of that table, and shows whole_document=True against a file with no header.

Configured

The mixin that makes those six visible to a type checker and to an editor — class Database(Configured, BaseModel). Runtime behaviour is unchanged; what changes is that Database.current() is typed as Database rather than being an attr-defined error, and that Database.config is DynamicConfig[Database] — so everything reached through it, changes() and changed_async() included, stays the model's own type. See the decorator.

Types

Origin

kind (file, env, inline, remote, runtime, unknown), detail (the path, the variable, the store). str() renders it as the crate does: in /etc/app.toml, from APP_DB_PORT.

Explanation

path, rows (a tuple of Contribution: layer, value, origin), winner. str() is the table; repr() is shape only, because a repr lands in a log by accident and this is the one object that carries values.

Report

key, resolved (tuple of Resolved: path, origin), unknown (tuple of UnknownKey: path, suggestion), failure, unknown_checked, and the is_clean property. str(report) renders the table the Rust crate prints — paths and origins, never values.

unknown_checked is False when there was no field list to compare a document against, which is a Values configuration: an empty unknown from one is not an all-clear, and the rendering says unknown keys: not checked (no field list) rather than letting it read as one.

Snapshot

to_dict(), source_of(path), contains(path), leaf_paths(), top_level_keys(), is_empty(), diff(other) → Change values.

Change

path and kind (added, removed, changed).

ConfigStatus, RemoteStatus, Failure

What status() and remote_status() hand back, and the failure either may carry. Frozen dataclasses of counts, durations and fixed enums — never a value, never a store address. Field by field in Telemetry.

Exposition

One or more configurations' status as a Prometheus text body: Exposition().add(name, config).add_remote(name, config).render(), plus add_with/add_remote_with for labels of your own. Built per scrape and thrown away. The metric names are API; see Telemetry.

RemoteSource

The ABC a store written in Python subclasses. Two abstract methods, so a class missing one cannot be instantiated at all — a TypeError where the store is constructed, rather than something a deployment discovers at its first refresh:

Name the store, never the credential that reaches it: describe() is what source_of(...) reports and what every remote error carries.

AsyncRemoteSource

The same door for a store whose client is async: async def fetch() and a synchronous describe(). refresh_remote_async() awaits fetch() on the calling loop and hands the document to the engine afterwards, so an async client runs on the loop it was built on; a cancelled refresh cancels the fetch, and a raising fetch() reaches the caller as its own exception rather than as RemoteError. The synchronous refresh_remote() raises on such a store rather than driving it from a private loop. See Async & asyncio.

Format

Format.JSON, Format.TOML, Format.YAML — a str enum, so a plain "json" is accepted too.

ConfigGroup

Several configurations under one lifecycle: ConfigGroup(db, cache, queue, concurrency=None).

concurrency bounds how many members load at once; None — the default — loads them one at a time. The group owns lifecycle, not storage: the read path is still db.current().

Dispatch and Backpressure

str enums naming where a reload hook runs and what happens when installs outrun it: Dispatch.INLINE / EXECUTOR / ASYNCIO, and Backpressure.EVERY / LATEST / SERIAL / CANCEL_PREVIOUS. A value outside the set is a ValueError naming the ones inside it. See Callbacks.

Reloaded and ReloadFailed

What events() yields — frozen dataclasses, both carrying generation and at (a Unix timestamp).

No event carries a value, the same rule explain() and check() follow: a value in an event is a secret in a log.

Watch

running, stop(), detach(), and a context manager that stops on exit.

HookGuard

close(), hook, and a context manager that unregisters on exit. It is also callable, forwarding to the hook — which is what lets @config.on_reload decorate a function without taking it away.

Exceptions

DynamicConfigError is the base — catching it catches everything. Each instance carries kind, path, origin_kind and origin.