Metadata-Version: 2.3
Name: canvod-utils
Version: 0.2.0
Summary: Utility functions and configuration management for canvodpy
Author: Nicolas François Bader
Author-email: Nicolas François Bader <nicolas.bader@geo.tuwien.ac.at>
License: Apache-2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: email-validator>=2.0
Requires-Dist: tenacity>=8.2.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# canvod-utils

Utility functions and configuration management for canvodpy.

## Features

- **Type-safe configuration**: Pydantic models with validation
- **YAML-based config**: Human-readable configuration files
- **CLI tools**: Easy configuration management
- **API-ready**: Same models work for files and APIs

## Installation

```bash
uv pip install -e packages/canvod-utils
```

## Quick Start

### 1. Initialize Configuration

```bash
just config-init
```

This creates:
- `config/processing.yaml` - Processing parameters and credentials
- `config/sites.yaml` - Research site definitions
- `config/sids.yaml` - Signal ID selection

### 2. Edit Configuration

```bash
# Edit in your preferred editor
just config-edit processing
just config-edit sites
just config-edit sids
```

Or edit files directly:
- Set `nasa_earthdata_acc_mail` (optional) in `config/processing.yaml` for NASA CDDIS access
- Set `gnss_site_data_root` per site in `config/sites.yaml`
- Define your research sites in `config/sites.yaml`

### 3. Validate Configuration

```bash
just config-validate
```

### 4. Use in Code

```python
from canvod.utils.config import load_config

# Load configuration
config = load_config()

# Access values
print(config.nasa_earthdata_acc_mail)
print(config.processing.aux_data.agency)

# FTP server selection (auto-detect based on nasa_earthdata_acc_mail)
servers = config.processing.aux_data.get_ftp_servers(config.nasa_earthdata_acc_mail)
for server_url, auth_email in servers:
    print(f"Server: {server_url}, Auth: {auth_email}")
```

## Configuration Structure

### processing.yaml

```yaml
credentials:
  nasa_earthdata_acc_mail: your.email@example.com  # Optional

aux_data:
  agency: COD
  product_type: final

processing:
  resource_mode: auto
  keep_rnx_vars: [SNR]
  aggregate_glonass_fdma: true
```

### sites.yaml

```yaml
sites:
  rosalia:
    gnss_site_data_root: /path/to/rosalia
    receivers:
      reference_01:
        type: reference
        directory: 01_reference/01_GNSS/01_raw
      canopy_01:
        type: canopy
        directory: 02_canopy/01_GNSS/01_raw
    vod_analyses:
      canopy_01_vs_reference_01:
        canopy_receiver: canopy_01
        reference_receiver: reference_01
```

### sids.yaml

```yaml
mode: all  # all, preset, custom
# preset: gps_galileo
# custom_sids: [G01|L1|C, G01|L2|W, ...]
```

## CLI Commands

```bash
# Initialize configuration
just config-init

# Validate configuration
just config-validate

# Show current configuration
just config-show
uv run canvodpy config show --section processing  # filtered view

# Edit configuration
just config-edit processing
just config-edit sites
just config-edit sids
```

## FTP Server Selection

- **If `nasa_earthdata_acc_mail` is set**: NASA CDDIS (primary) → ESA (fallback)
- **If `nasa_earthdata_acc_mail` is null**: ESA only (no authentication)
- ESA server is always available as fallback

## Configuration Priority

1. Package defaults (lowest priority)
2. User configuration files (highest priority)

## API-Ready Design

Same Pydantic models work for both local files and future API:

```python
# Local development (YAML files)
config = load_config()

# Future API usage (same models!)
@app.post("/process")
def process(config: CanvodConfig):
    return processor.run(config)
```

## Documentation

[Centralized documentation](../../docs/packages/utils/overview.md)

## Development

```bash
# Install dev dependencies
uv pip install -e "packages/canvod-utils[dev]"

# Run tests
pytest packages/canvod-utils/tests

# Lint and format
ruff check packages/canvod-utils
ruff format packages/canvod-utils
```
