# Utils/Config

Shared configuration for the GRI FOSS ecosystem.

## Overview

This module provides a centralized configuration system that all GRI packages can use. Configuration is stored in a single TOML file at `~/.config/gri/config.toml`. Each package owns its own defaults - this module provides no hardcoded defaults.

## Features

- mtime-based cache invalidation (auto-reload on file change)
- Dot-separated key access (e.g., `gri-terrain.copernicus.cache_dir`)
- Path expansion (`~` expands to home directory)
- In-memory overrides via `set()`

## Import and Use

```python
from gri_utils import config

# Get value with package-provided default
cache_mb = config.get("gri-terrain.max_memory_cache_mb", 500.0)

# Get path value (returns Path object)
cache_dir = config.get_path("gri-terrain.copernicus.cache_dir")

# Set in-memory override (does not write to file)
config.set("gri-terrain.max_memory_cache_mb", 1000.0)
```

## Config File Location

The default config file location is:

```
~/.config/gri/config.toml
```

For testing or custom deployments, override with:

```python
config.set_config_path("/path/to/custom/config.toml")
```

## TOML Format

The config file uses standard TOML format with package names as top-level sections:

```toml
[gri-terrain]
max_memory_cache_mb = 500.0
interpolation = "bicubic"

[gri-terrain.copernicus]
cache_dir = "~/.cache/gri/terrain/copernicus"
max_cache_gb = 10.0
resolution = "90m"

[gri-tropo]
n_sur_dir = "/data/tropo/n_sur"

[gri-iono]
nequick_coeffs_path = "~/.cache/gri/iono/nequick"
```

Nested sections become dot-separated keys:

- `gri-terrain.max_memory_cache_mb` -> `500.0`
- `gri-terrain.copernicus.cache_dir` -> `"~/.cache/gri/terrain/copernicus"`
- `gri-terrain.copernicus.resolution` -> `"90m"`

## Why Use This?

1. **User customization**: Users can override package defaults without modifying code
2. **Environment portability**: Same code works across machines with different data paths
3. **Centralized config**: One file for all GRI packages instead of scattered configs
4. **Auto-reload**: Edit the config file and changes take effect immediately

## Example: gri-terrain

The gri-terrain package uses this config for cache directories and memory limits:

```python
from gri_utils import config

# In gri-terrain code
cache_dir = config.get_path(
    "gri-terrain.copernicus.cache_dir",
    Path.home() / ".cache" / "gri" / "terrain" / "copernicus"
)

max_memory_mb = config.get("gri-terrain.max_memory_cache_mb", 500.0)
```

Users can then customize via `~/.config/gri/config.toml`:

```toml
[gri-terrain]
max_memory_cache_mb = 2000.0  # More RAM available

[gri-terrain.copernicus]
cache_dir = "/fast-ssd/terrain-cache"  # Use fast local storage
```
