varstore

Hierarchical variable store with optional recursive shell-style template rendering.

Formerly varmgr. The expand engine from the mrjk/python-expandvars fork is included as batteries (varstore.expand) — no separate expandvars install is required.

Table of Contents

• Goal
• Install
• Core concepts
• Quickstart
• Template rendering
• String-only expand API
• Inspection
• Migration from varmgr
• Development
• Running tests
• Release

Goal

varstore manages configuration variables across sources, scopes, and layers:

• Sources with numeric priority (level, lower = higher priority)
• Scopes listing sources and nested scopes
• Layers of key/value data per source
• Raw lookup (StoreManager) vs rendered lookup (RenderableStoreManager)
• Default template engine = shell expandvars ($VAR / ${VAR}); alternate py_stringtemplate available

Install

Python 3.10+. Zero hard runtime dependencies beyond the stdlib.

pip install mrjk.varstore

Import as varstore:

from varstore import StoreManager, RenderableStoreManager, Source

Editable / from source:

mise trust && mise install
uv sync --all-groups

Core concepts

Sources

Named origins with optional priority level (lower = higher priority):

Source("app_cli", level=300, help="Application main CLI")
Source("app_defaults", level=999, help="Application defaults")

Scopes

Scopes list sources (and other scopes) to resolve against:

store.set_scopes({
    "scope_app": ["app_cli", "app_env", "app_defaults"],
    "scope_project": ["project_cli", "project_env", "project_defaults", "scope_app"],
})

Layers

Key/value payloads attached to a registered source:

store.set_layer("app_cli", {"app_name": "myapp", "debug": True})

Resolution APIs

1. StoreManager — raw storage: get_value / get_values return stored values as-is (templates are not expanded).
2. RenderableStoreManager — same raw API, plus get_renderer(scope).render_var(...) / render_values(...) for expansion.

Quickstart

from varstore import StoreManager, Source

store = StoreManager()

store.add_sources([
    Source("app_cli", level=300, help="Application main CLI"),
    Source("app_env", level=300, help="Application environment variables"),
    Source("app_defaults", level=999, help="Application defaults"),
])

store.set_scopes({
    "scope_app": ["app_cli", "app_env", "app_defaults"],
})

store.set_layer("app_cli", {
    "app_name": "myapp",
    "debug": True,
})

app_name = store.get_value("app_name")  # "myapp"

Template rendering

get_value always returns the raw stored value. Use a Renderer to expand templates.

from varstore import RenderableStoreManager, Source

store = RenderableStoreManager()

# ... add_sources / set_scopes ...

store.set_layer("project_env", {
    "project_name": "myproject",
    "env": "prod",
    "stack_name": "${project_name}-${env}",
})

assert store.get_value("stack_name") == "${project_name}-${env}"

renderer = store.get_renderer(scope_name="scope_project")
assert renderer.render_var("stack_name") == "myproject-prod"

values = renderer.render_values()

Default engine is expandvars (shell-style). Alternate Python string.Template:

renderer = store.get_renderer(scope_name="scope_project", engine="py_stringtemplate")

Circular references raise TemplateRenderingCircularValueError. Undefined vars raise UndefinedVarError (customizable via render settings).

String-only expand API

For expansion without a store:

from varstore.expand import expand, expandvars, ExpandParser

expandvars("$HOME/bin")
expand("${FOO:-default}", environ={"FOO": "bar"})
ExpandParser(environ={"PATH": "/usr/bin"}).expand("$PATH:/opt/bin")

Inspection

store.show_sources_help()
layers = store.inspect_var("log_level", scope="scope_project")
names = store.get_source_names(scope="scope_stack")
value, report = renderer.render_var("stack_name", debug=True)

Migration from varmgr

Behavior of sources, scopes, layers, priority, and expand syntax is unchanged.

Development

mise trust && mise install
uv sync --all-groups

With mise activated, task and uv are on your PATH. After uv sync, project tools live in .venv.

task               # list root tasks
task test_core     # unit + coverage + lint (no docs)
task test          # full CI gate (core + docs)
task fix_lint      # auto-fix formatters
task docs          # serve docs (Zensical)

More targets: cd ci && task, cd docs && task.

Running tests

task test_core
# or
uv run pytest

Release

./scripts/release.sh patch   # bump, commit, tag
git push && git push --tags

Tag push v* triggers PyPI publish (configure Trusted Publishing / pypi environment). Docs: Zensical under docs/ (task docs).