Metadata-Version: 2.4
Name: dworshak-config
Version: 0.2.1
Summary: Get and set two-key plaintext configuration values stored to JSON file path.
Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
License-Expression: MIT
Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/dworshak-config
Project-URL: Repository, https://github.com/city-of-memphis-wastewater/dworshak-config
Keywords: configuration,config,DworshakConfig,dworshak
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: typer
Requires-Dist: typer>=0.21.1; extra == "typer"
Requires-Dist: rich>=14.3.2; extra == "typer"
Requires-Dist: typer-helptree>=0.1.10; extra == "typer"
Dynamic: license-file

# dworshak-config

**dworshak-config** is a lightweight, zero-dependency library for managing nested JSON configurations. It serves as the standard storage backend for the Dworshak ecosystem, providing a stable way to persist non-sensitive application settings.

By decoupling storage from user interaction, `dworshak-config` ensures that your scripts can retrieve settings silently when they exist, leaving the "how to ask for them" to its sister package, [dworshak-prompt](https://github.com/City-of-Memphis-Wastewater/dworshak-prompt).

## Features

* **Zero Dependencies:** Pure Python standard library (`json` and `pathlib`).
* **Service-Oriented:** Organizes settings by `service` and `item` (e.g., `config["postgres"]["port"]`).
* **Atomic Persistence:** Automatically handles directory creation and pretty-printed JSON writes.
* **Fail-Safe Loading:** Gracefully handles corrupted or missing configuration files.

## Installation

```bash
uv add dworshak-config
# or
pip install dworshak-config

```

## Usage

### Basic I/O

The `DworshakConfig` is the primary interface for reading and writing data.

```python
from dworshak_config import DworshakConfig

# Uses default path: ~/.dworshak/config.json
cfg = DworshakConfig()

# Store a value
cfg.set_value("aws", "region", "us-east-1")

# Retrieve a value (returns None if missing)
region = cfg.get_value("aws", "region")
print(f"Targeting: {region}")

```

### Custom Configuration Paths

Perfect for project-specific settings that shouldn't live in the global Dworshak folder.

```python
from dworshak_config import DworshakConfig

# Point to a specific project file
project_cfg = DworshakConfig("./.my_project/config.json")
project_cfg.set_value("internal", "debug_mode", True)

```

## The Ecosystem Integration

While `dworshak-config` handles the **persistence**, it is designed to be orchestrated by `dworshak-prompt` for interactive workflows.

```python
# In your application using dworshak-prompt
from dworshak_prompt import DworshakGet

# This will:
# 1. Check ~/.dworshak/config.json for 'api_url'
# 2. If missing, prompt the user (Console/GUI/Web)
# 3. Save the answer back to config.json automatically
api_url = DworshakGet.config("my_service", "api_url")

```

## Configuration Schema

Data is stored in a clean, human-readable nested JSON format:

```json
{
    "aws": {
        "region": "us-east-1",
        "output": "json"
    },
    "rjn_api": {
        "base_url": "https://api.example.com"
    }
}

```

---

## Sister Projects

* **CLI/Orchestrator:** [dworshak](https://github.com/City-of-Memphis-Wastewater/dworshak)
* **Interactive UI:** [dworshak-prompt](https://github.com/City-of-Memphis-Wastewater/dworshak-prompt)
* **Secrets Storage:** [dworshak-secret](https://github.com/City-of-Memphis-Wastewater/dworshak-secret)

