Repository navigation
API Reference
Import from the submodules: interpose.settings, interpose.secret and interpose.metrics. The package itself exports only __version__ and __description__. Anything starting with _ is internal.
Setting(key, default, help, *, secret=False, is_list=False, check=None): one setting, a frozen dataclass.
-
key: dotted lower case,[a-z0-9_]+joined by dots (listen.port). -
default: astr,intorbool. Its type is the setting's type. A list setting's default is"". -
help: Markdown, as users read it in the generated settings table. -
secret: the value resolves to aSecret. Only for str settings. -
is_list: the value is atuple[str, ...], from a YAML list or a comma-separated string. -
check: a callable that gets the coerced value and raisesValueError(reason)if it's invalid. -
env(property): the environment variable, the prefix plus the upper-cased key with dots as underscores (MYAPP_LISTEN_PORT).prefixis set bySettings, never by hand.
Settings(prefix, settings, *, default_path): a Sequence[Setting], each one bound to prefix.
-
config_env:prefix + "CONFIG", the variable that names the YAML file. Alsoprefixanddefault_path. - Raises
ValueErrorfor a bad or duplicate key, a key part YAML doesn't read as a string (on,no,null,1), two settings that would read the same variable (a.banda_b;x_fileandx's_FILE; a keyconfig), a list setting whose default isn't"", or a secret setting that isn't a str setting. -
resolve(path=None, environ=None) -> Resolved: readspath(else$<PREFIX>CONFIG, elsedefault_path; missing means defaults) andenviron(elseos.environ), and resolves every setting. RaisesConfigError.
r = SETTINGS.resolve(Path("config.yaml"), {"MYAPP_LISTEN_PORT": "9090"})
r.values["listen.port"], r.sources["listen.port"] # (9090, "MYAPP_LISTEN_PORT")Resolved(values, sources): frozen, read-only mappings keyed by setting key, in declaration order.
-
values[key]: the typed value, aValue(str | int | bool | tuple[str, ...] | Secret). -
sources[key]:"<PREFIX><KEY>_FILE","<PREFIX><KEY>","file"or"default".
ConfigError: the configuration can't be read, or a value in it is invalid. The message names the key, the expected type and the source, and never holds a secret setting's value.
Checks, for check=. Each raises ValueError, which resolve() turns into ConfigError("<key>: <reason>"):
| Check | Passes |
|---|---|
port |
an int from 1 to 65535 |
positive |
an int above 0 |
non_negative |
an int, 0 or more |
one_of(*choices) |
a str equal to one of choices, in any case (the value keeps its case) |
Secret(value: str): a secret value.
-
str(),repr(),format()and f-strings give********(MASK);reveal()gives the value. - Equal to another
Secretwith the same value (compared in constant time), never to a plainstr. Hashable. Falsy when the value is empty. - Raises
TypeErrorfor anything but astr.
read_secret_dir(directory: Path) -> Mapping[str, Secret]: each regular file in directory (symlinks followed) as a Secret, keyed by file name, minus one trailing newline. Dot-entries are skipped, which covers a Kubernetes secret volume's ..data. A missing directory gives an empty mapping. Raises ConfigError if the directory or a file can't be read.
MASK: "********".
Prometheus text exposition (format 0.0.4). Every label takes its values from a declared set, so the series count is fixed by code and configuration, never by traffic.
Label(name, values=()): a label name and the only values it may take.
-
name: matches[a-zA-Z_][a-zA-Z0-9_]*, not starting with__. -
values: an iterable ofstr(a list, not a bare string:Label("kind", "ca")is aTypeError); read back as afrozenset[str].value in labeltests one. -
declare(*values): allow more values, from configuration (the middleware names a reload brings), never from measured data. Values are never removed. OneLabelcan be shared by several metrics, so onedeclarecovers all of them.
Counter(name, help, labels=()): inc(*values, amount=1.0). amount must be finite and zero or more.
Gauge(name, help, labels=(), read=None): set(value, *values), add(amount, *values). With read (a callable returning {label values: number}), the samples come from it when the gauge renders.
Histogram(name, help, buckets, labels=()): observe(value, *values). Classic cumulative buckets (inclusive), plus _sum and _count; +Inf is added for you. Buckets are finite, distinct and sorted for you. NaN is refused. samples() gives each label set's count.
-
labelsis a sequence ofLabel. Each call passes one value per label, in order. A value outside its label's set, or the wrong number of values, raisesValueError, which names the metric and the label but never the value. - Declaration errors are
ValueError(orTypeErrorfor a label that isn't aLabel): a bad metric or label name, a repeated label name, a histogram label calledle, bad buckets.
Registry(metrics=()): the metrics one endpoint exports.
-
register(metric) -> metric: adds it and returns it. A second metric with the same name, or one whose samples clash with another's (a counterfoo_countnext to a histogramfoo), raisesValueError. - Iterates in registration order;
len()counts the metrics. -
render() -> str: every metric's# HELP,# TYPEand samples (sorted by label values), joined by newlines and ending in one;""when empty.
CONTENT_TYPE: "text/plain; version=0.0.4; charset=utf-8", for an HTTP response's Content-Type.
from interpose.metrics import CONTENT_TYPE, Counter, Label, Registry
OUTCOME = Label("outcome", ["ok", "denied", "error"])
REGISTRY = Registry()
CALLS = REGISTRY.register(Counter("myapp_calls_total", "Calls, by outcome.", (OUTCOME,)))
CALLS.inc("ok")
CALLS.inc("example.org") # ValueError: label 'outcome' got a value outside its declared set
body = REGISTRY.render() # serve with CONTENT_TYPE, or as a fileinterpose doesn't serve the text: an HTTP endpoint or a virtual file is the project's.
The public API follows semantic versioning: breaking changes only in a major release (a minor one before 1.0), and they're announced in the CHANGELOG.
Everything above is stable within 0.1.x. The message text of ConfigError and ValueError is for people: match on the exception type, not the words.
interpose | Shared mechanism for metalayerlab interceptors — a policy-configurable async middleware pipeline, the layered settings loader, Secret values, and Prometheus text exposition.
GitHub • Releases • Issues • Changelog • Contributing
This wiki is generated from docs/wiki/ on every push to main: edits made here are overwritten. Change it with a pull request.
- 🧅 One middleware loop; fail open or closed is policy, per project and per middleware
- 🥞 One lookup order:
_FILE> environment > YAML > default - 🧱 Strict types: no silent
0for a YAML0.5 - 🧭 Where each value came from, for every setting
- 🔒
Secret: masked in logs, reprs and errors - 📈 Prometheus text with labels from declared value sets