Metadata-Version: 2.4
Name: dworshak-config
Version: 0.2.5
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.2.6; extra == "typer"
Dynamic: license-file

# dworshak-config

**dworshak-config** is a lightweight 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"
    }
}

```

---

## CLI

The [dworshak](https://github.com/City-of-Memphis-Wastewater/dworshak) layer is the intended primary CLI entry point, but the `dworshak-config` CLI can be used directly.

See the `dworshak-config` Typer CLI structure.
```
dworshak-config helptree
```

<p align="center">
  <img src="https://raw.githubusercontent.com/City-of-Memphis-Wastewater/dworshak-config/main/assets/dworshak-config_v0.2.5_helptree.svg" width="100%" alt="Screenshot of the dworshak-config CLI helptree">
</p>

`helptree` is utility funtion for Typer CLIs, imported from the `typer-helptree` library.

- GitHub: https://github.com/City-of-Memphis-Wastewater/typer-helptree
- PyPI: https://pypi.org/project/typer-helptree/

---

<a id="sister-project-dworshak-secret"></a>

## Sister Projects in the Dworshak Ecosystem

* **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)
* **Plaintext Pathed Configs:** [dworshak-config](https://github.com/City-of-Memphis-Wastewater/dworshak-config)
* **Classic .env Injection:** [dworshak-env](https://github.com/City-of-Memphis-Wastewater/dworshak-env)

```python
pipx install dworshak
pip install dworshak-secret
pip install dworshak-config
pip install dworshak-env
pip install dworshak-prompt

```
