staticconfiguration 1.0.1
Strongly typed, persistent global configuration for single-machine Python applications.
Requires Python: >=3.10

# staticconfiguration

Persistent, typed, static configuration for Python applications.

`staticconfiguration` is a small, opinionated library designed to manage a
specific subset of configuration values that are genuinely global, persistent,
and shared across unrelated parts of an application.

It is not a general configuration system, and it is not a replacement for
dependency injection.

If you’ve ever had a settings module that “worked fine” until it didn’t,
or a DI graph where configuration slowly took over the system,
this library is for you.

## What this library is

- Persistent global configuration stored in local JSON.
- Strongly typed, schema-driven configuration (with explicit encoder/decoder support for complex types).
- Static access (no instances, no containers).
- Safe multiprocess access via file locking.
- Automatic, deterministic schema migration with safe defaults.
- Designed for single-machine applications.

Typical use cases include application preferences, UI state, feature flags, timeouts, and similar cross-cutting configuration data.

## What this library is not

- Not a dependency injection framework.
- Not a distributed configuration system.
- Not a secrets manager.
- Not optimized for high-frequency reads or large payloads.
- Not suitable for network filesystems or multi-machine deployments.

If dependency injection works well for your use case, it should be preferred.

---

## Introduction

This project started while developing a desktop application with multiple
subsystems that needed access to the same configuration values.

At first, dependency injection was used everywhere. It worked, but over time
the dependency graph became noisy, fragile, and dominated by configuration
plumbing rather than domain logic.

The underlying issue was simple:

**Some configuration values are inherently global.**

Forcing them through dependency injection did not make them safer—it only hid
their global nature behind additional plumbing.

Even when modeled as a “settings” object injected everywhere, the result is
still a mutable global state: a single shared object that any subsystem can
read or modify.

Making them truly global, however, introduced new problems: concurrency,
persistence, schema evolution, and recovery from failure.

`staticconfiguration` is an attempt to address that narrow problem directly:

**how to make global configuration explicit, constrained, and safe.**

---

## Installation

```bash
pip install staticconfiguration
```

---

## Basic usage

Configuration is declared using a regular Python class decorated with `@staticconfig`. Each field is defined explicitly using a `Data` descriptor.

```python
from staticconfiguration import staticconfig, Data

@staticconfig
class AppSettings:
    __config_path__ = "~/.config/myapp"
    __config_file__ = "settings.json"
    __version__ = "1.0.0"
    __development__ = False

    api_url = Data(
        name="api_url",
        data_type=str,
        default="https://api.example.com",
    )

    timeout = Data(
        name="timeout",
        data_type=int,
        default=30,
    )
```

Read and write values statically:

```python
timeout = AppSettings.get(AppSettings.timeout)
AppSettings.set(AppSettings.timeout, 60)
```

All operations interact directly with disk. No in-memory cache is used by design,
to avoid stale reads and hidden state.

---

## Important design notes

The following behaviors are intentional and should be understood before using the library:

- **All reads and writes acquire an exclusive file lock**, including reads.
- **Configuration is read directly from disk on every access**.
- **Corrupted configuration files are backed up and reset to defaults**.
- **`concurrency_unsafe=True` disables all safety guarantees** and is a deliberate expert-only escape hatch.

Each of these points is documented in detail in the documentation.

---

## Documentation

The complete documentation is available on Read the Docs:

**https://staticconfiguration.readthedocs.io/**

Key sections:

- **Quickstart**: Minimal setup and usage examples.
- **Core concepts**: Design philosophy, scope, and trade-offs.
- **Concurrency model**: Locking strategy, guarantees, and limitations.
- **Schema migration**: Deterministic, schema-driven migration behavior.
- **Corruption recovery**: How the library behaves when the configuration file is unreadable.
- **Performance and validation**: Observed behavior under real multiprocess stress and chaos testing.
- **FAQ**: Common questions and design rationale.
- **API reference**: Full autogenerated API documentation.

---

## Project status

- **Stable release**: v1.0.1
- Designed for single-machine environments.
- Local filesystem required.
- **License**: MPL-2.0

---

## License

Copyright (c) 2025 David Muñoz Pecci.

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).