Client overview¶
param-manager is the Python library that consumes the API. It is published on
PyPI at version 0.6.0 and installed inside your application.
from param_manager import ParamManager
pm = ParamManager.get_instance()
timeout = pm.get_param('MY_APP', 'TIMEOUT_HTTP')
What it solves¶
Reading configuration from a remote service adds a new dependency to your application's critical path. The library exists so that dependency degrades instead of failing:
- Two-level cache, so most reads never touch the network.
- Circuit breaker, to stop hammering a server that is sick.
- Local TinyDB copy, which answers when the API does not.
- Transparent decryption of sensitive parameters.
The price is that the value you read may be stale. How stale is your call — see Cache and offline mode.
How a read is resolved¶
The chain below is walked until one step answers. The order is not accidental: each step costs more than the previous one, and the last one exists so that the absence of the API is degradation rather than failure.
flowchart TD
accTitle: Resolution of a get_param in the client
accDescr: A read tries the parameter cache first, then the application cache, then checks the circuit breaker, and only then goes to the network. Each check that succeeds returns the value through its own path; a network failure arms the breaker and falls back to the local TinyDB.
A["ParamManager<br/>multiton by instance_name"] --> D1{"parameter cache<br/>still valid?"}
D1 -- yes --> R1["return from the parameter cache"]
D1 -- no --> D2{"application cache<br/>still valid?"}
D2 -- yes --> R2["promote to the parameter cache<br/>and return the value"]
D2 -- no --> D3{"breaker in cooldown?<br/>recent API error"}
D3 -- yes --> R3["local TinyDB — offline mode<br/>params_<instance>.json"]
D3 -- no --> B["GET /parameters/apps/.../params/...<br/>requests · timeout · verify_ssl<br/>optional auth headers"]
B --> D4{"response 200 OK?"}
D4 -- no --> R4["404, timeout, connection or 5xx<br/>arm the breaker and call<br/>_handle_api_error: TinyDB or None"]
D4 -- yes --> R5["is it an envelope? decrypt<br/>AES-GCM + CHAVE_CUSTODIA_APP<br/>write cache and TinyDB, return"]
Writes have none of this. They always hit the network, always with a token, and never consult the cache:
flowchart LR
accTitle: Write path in the client
accDescr: The four write operations bypass the cache and TinyDB, require a token, and go straight to the API.
W["create_app · upsert_params<br/>delete_param · delete_app"] --> T["_auth_headers<br/>token required"]
T --> API["API"]
W -. never consults .-x CACHE["cache · TinyDB"]
The detail of each step — cache validity, what arms and what disarms the breaker, and what happens in each failure mode — is in Cache and offline mode.
Multiton, not singleton¶
ParamManager is not a singleton. It is a multiton: one instance per
instance_name, held in a class dictionary guarded by a lock.
production = ParamManager.get_instance(instance_name='producao')
staging = ParamManager.get_instance(instance_name='homolog')
The two have independent URLs, credentials, caches and local files.
The library's old documentation says 'Singleton'
The param-manager README and older pages on its site claim the class
implements the Singleton pattern, with __instance and a one-hour cache.
That describes a version that no longer exists. What holds is what is here.
__init__ returns early once an instance has been initialized, so constructing
ParamManager(instance_name='x') twice returns the same object without redoing
anything.
The public surface¶
The package exports exactly two names:
Reading¶
| Method | Returns |
|---|---|
get_param(app_name, param_name, save_cache=True) |
The value, already decrypted |
get_all_params(app_name) |
A name-to-value map |
Writing¶
| Method | Note |
|---|---|
create_app(name, description=None) |
Expects 201 from the server |
upsert_params(app_name, param_name, *, value, param_type, ...) |
One parameter per call |
delete_param(app_name, param_name) |
|
delete_app(app_name) |
Writes always hit the network, always with a token, and never consult the cache.
Cache¶
| Method | Note |
|---|---|
clear_cache(app_name=None, param_name=None) |
With no argument, clears everything |
get_cache_info() |
Cache state, validity and error marks |
Methods the old documentation promises and that do not exist
update_param(...) and get_param_schema(...) appear in the tutorial on
the param-manager site. Neither exists. To change a value, use
upsert_params.
Python versions¶
requires-python = ">=3.10", with no ceiling. A pure library cannot know it
will break on a version that does not exist yet, and the old ceiling, <=3.14,
rejected even 3.14.1.
The floor moved from 3.8 to 3.10 for security, not syntax:
python-dotenv==1.2.2 fixes PYSEC-2026-2270 and is not published below 3.10. On
3.9 the reachable ceiling is still vulnerable; on 3.8, worse. Lowering the floor
means going back to shipping the flaw.