json-config-hotreload

Thread-safe JSON configuration with automatic hot-reload. Zero dependencies beyond stdlib.

---

Why?

Config files change at runtime -- auto-tuners tweak thresholds, admins edit settings, CI/CD pipelines push new values. Your application should not need a restart to pick up those changes.

json-config-hotreload watches the st_mtime of each config file and transparently re-reads it when the timestamp advances. Everything is protected by a threading lock, so concurrent access from multiple threads is safe.

Features

• mtime-based reload -- every get() compares the cached mtime against the file on disk. If the file is newer, it is re-read automatically.
• Thread-safe -- all cache reads and writes are guarded by a threading.Lock.
• Zero dependencies -- pure stdlib (json, pathlib, threading, logging).
• Singleton + instance API -- use the convenient module-level functions or create your own JsonConfigCache instances.
• Explicit invalidation -- call invalidate() or invalidate_all() to force a reload on the next access.
• Graceful degradation -- missing files return {}. Malformed JSON returns the last known good value (or {} on first load).

Installation

pip install json-config-hotreload

Or install from source:

git clone https://github.com/TjTheDj2011/json-config-hotreload.git
cd json-config-hotreload
pip install .

Usage

Basic (module-level singleton)

from json_config_hotreload import get_json_config

config = get_json_config("settings.json", config_dir="/etc/myapp")
max_retries = config.get("max_retries", 3)

The first call reads from disk. Subsequent calls return the cached dict unless the file's mtime has changed.

Custom cache instance

from json_config_hotreload import JsonConfigCache

cache = JsonConfigCache(config_dir="/etc/myapp")
db_config = cache.get("database.json")

Invalidation

from json_config_hotreload import invalidate_config

# Force the singleton to re-read on next access
invalidate_config("settings.json")

# Or on a custom instance
cache.invalidate("database.json")
cache.invalidate_all()

Per-call directory override

cache = JsonConfigCache(config_dir="/etc/myapp")

# Read from the default directory
app_cfg = cache.get("app.json")

# Read from a different directory just this once
test_cfg = cache.get("app.json", config_dir="/tmp/test-configs")

How it works

JsonConfigCache keeps an in-memory dict mapping each filename to a _ConfigEntry holding the parsed data, the file's st_mtime at load time, and the resolved path. On every get() call the file's current mtime is checked via Path.stat(). If the mtime is newer than the cached value, the file is re-read and parsed; otherwise the cached dict is returned immediately. All access is serialized through a threading.Lock so concurrent reads from multiple threads are safe.

Running tests

pip install pytest
pytest

License

MIT -- see LICENSE for details.