Metadata-Version: 2.4
Name: codechu-config
Version: 0.1.0
Summary: Schema-driven config with JSON+TOML backends, dotted-key access, atomic save, and migrations.
Author: Codechu
License: MIT License
        
        Copyright (c) 2026 Codechu
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/codechu/codechu-config-py
Project-URL: Source, https://github.com/codechu/codechu-config-py
Project-URL: Issues, https://github.com/codechu/codechu-config-py/issues
Keywords: config,configuration,schema,json,toml,settings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: toml
Requires-Dist: tomli_w>=1.0; extra == "toml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: tomli_w>=1.0; extra == "dev"
Dynamic: license-file

```text
              .    .  c o d e c h u  .    .
           .   \  |  /  c o n f i g  \  |   .
        ((((( ── (( ⚙ )) ──────────── (( ⚙ )) ── )))))
           '   /  |  \                /  |   '
              '    '  schema · dotted · atomic
```

> *Schema-first config. Validates on set. Saves atomically. Migrates on load.*

# codechu-config

Schema-driven configuration for Python. JSON + TOML backends, dotted-key
access, atomic save, and forward migrations. Pure stdlib (`tomli_w` is
the only optional dependency, needed only when writing TOML).

```bash
pip install codechu-config           # JSON-only
pip install "codechu-config[toml]"   # adds TOML write support
```

## What it gives you

- **Schema validation** — types, choices, ranges, required fields, all
  enforced on every `set`.
- **Dotted keys** — `cfg.set("watchdog.threshold", 90)` writes nested
  structure; `cfg.get("watchdog.threshold")` reads it back.
- **Atomic save** — tempfile-in-same-dir + `fsync` + `os.replace`. A
  crash mid-write leaves the previous content intact, never garbage.
  If [`codechu-fs`](https://github.com/codechu/codechu-fs-py) is
  installed it is used transparently; otherwise the stdlib fallback
  ships in-package.
- **Migrations** — point the `Config` at a list of callables; they run
  in order whenever the on-disk `_version` differs from the schema's
  default.
- **JSON + TOML** — JSON by default (zero deps). TOML reads via stdlib
  `tomllib` (Python 3.11+); TOML writes need the optional `tomli_w`.
- **Dict sugar** — `cfg["language"] = "tr"`, `"language" in cfg`.

## Quick start

```python
from codechu_config import Config, Field, Schema

schema = Schema({
    "_version": Field(int, default=1),
    "language": Field(str, default="en", choices=["en", "tr"]),
    "watchdog.threshold": Field(int, default=90, range=(0, 100)),
    "watchdog.enabled": Field(bool, default=True),
})

cfg = Config(schema, "~/.config/myapp/config.json").load()
cfg.set("language", "tr")
cfg.set("watchdog.threshold", 75)
cfg.save()                       # atomic
```

### Bulk update with all-or-nothing semantics

```python
try:
    cfg.update({"language": "tr", "watchdog.threshold": 200})
except ValidationError:
    pass                         # nothing changed; original values intact
```

### Migrations

```python
def v1_to_v2(data):
    data["language"] = data.pop("lang", "en")
    data["_version"] = 2
    return data

cfg = Config(schema, path, migrations=[v1_to_v2]).load()
```

Migrations run only when the on-disk `_version` does not match the
schema default. Each migration is responsible for bumping `_version`.

### TOML backend

```python
cfg = Config(schema, "~/.config/myapp/config.toml", format="toml").load()
```

Reading TOML uses the stdlib `tomllib` (Python 3.11+). Writing TOML
requires `pip install codechu-config[toml]`.

## API reference

### `Field`

| Parameter | Purpose |
|---|---|
| `type` | Coerced + checked type: `str`, `int`, `float`, `bool`, `list`, `dict`, or `None` for any. |
| `default` | Used when the key is absent on load. |
| `choices` | Iterable of allowed values; checked after coercion. |
| `range` | `(low, high)` inclusive numeric bounds. |
| `required` | If `True`, missing keys raise on load/validate. |
| `doc` | Human description for tooling. |

### `Schema`

| Method | Purpose |
|---|---|
| `Schema({name: Field, ...})` | Build a schema. Names may be dotted (`"watchdog.threshold"`). |
| `.defaults()` | Fresh nested dict of all defaults. |
| `.validate(data)` | Return a coerced + validated copy; raise `ValidationError` on failure. |
| `.field(name)` | Look up a single field. |

### `Config`

| Method | Purpose |
|---|---|
| `Config(schema, path, format="json", migrations=None)` | Construct. |
| `.load()` | Read file (or use defaults), migrate, validate. |
| `.save()` | Atomically write current state. |
| `.get(key, default=None)` | Dotted-key read. |
| `.set(key, value)` | Validated dotted-key write. |
| `.update({key: value, ...})` | All-or-nothing bulk update. |
| `cfg[key]` / `cfg[key] = value` | Dict sugar over `get` / `set`. |
| `.as_dict()` | Deep-ish copy of current data. |

## Exceptions

- `ConfigError` — base.
- `ValidationError` — raised by `Field`, `Schema`, and `Config.set`.
- `MigrationError` — raised when a migration callable fails or returns
  a non-dict.

## License

MIT — see [LICENSE](LICENSE).

Part of [Codechu](https://github.com/codechu).
