Metadata-Version: 2.4
Name: casconf
Version: 0.2.0
Summary: Cascading Configuration Manager - deep-merge configuration files across multiple directories
Home-page: https://github.com/ConsoleCatzirl/casconf
Author: ConsoleCatzirl
License: MIT AND GPL-3.0-only
Project-URL: Homepage, https://github.com/ConsoleCatzirl/casconf
Project-URL: Documentation, https://github.com/ConsoleCatzirl/casconf#readme
Project-URL: Repository, https://github.com/ConsoleCatzirl/casconf.git
Project-URL: Issues, https://github.com/ConsoleCatzirl/casconf/issues
Project-URL: Changelog, https://github.com/ConsoleCatzirl/casconf/blob/main/ChangeLog
Keywords: configuration,config,merge,deep-merge,cascading,yaml,json,toml,ini,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: toml
Requires-Dist: tomli-w>=1.0; extra == "toml"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "toml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0; extra == "dev"
Requires-Dist: tomli-w>=1.0; extra == "dev"
Dynamic: home-page
Dynamic: license-file

# CasConf

**Cascading Configuration Manager**

CasConf is a flexible configuration management tool that deep-merges configuration files across multiple directories following a cascading pattern.

## Overview

CasConf scans a configurable list of directories for matching configuration files and intelligently deep-merges them based on discovery order. The result is a single, unified configuration that respects the cascade hierarchy you define.

### Key Features

- **Deep Merging**: Recursively merges nested configuration structures
- **Format Agnostic**: Supports JSON, YAML, TOML, and INI formats
- **Configurable Discovery**: Define your own directory scan order

## Use Cases

- Application configuration across development, staging, and production environments
- User-specific configuration overrides (system → user → project)
- Plugin or module configuration aggregation
- Multi-tenant configuration management
- Dotfile management and system configuration

## Documentation

- [USAGE.md](USAGE.md) - Getting started guide with examples
- [ARCHITECTURE.md](ARCHITECTURE.md) - System design and component overview
- [DESIGN.md](DESIGN.md) - Design decisions and rationale
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
- [API.md](API.md) - Library API reference

## Installation

```bash
# From PyPI (when published)
pip install casconf

# From source
pip install git+https://github.com/ConsoleCatzirl/casconf.git@main
```

## Basic Usage

### Command-Line Interface

```bash
# Merge configs and output to stdout (default)
casconf --discovery-config ./casconf.yaml

# Output to a file
casconf --discovery-config ./casconf.yaml --output ./merged.json

# Specify output format
casconf --discovery-config ./casconf.yaml --format yaml

# Configure with environment variables
export CASCONF_DISCOVERY=./casconf.yaml
export CASCONF_OUTPUT=./merged.json
export CASCONF_FORMAT=json
casconf

# Pipe to other tools
casconf | jq '.database'
```

### Library Usage

```python
from casconf import merge_configs

# Merge and return configuration data
config_data = merge_configs(discovery_config='./casconf.yaml')

# Merge and write to file in one call
merge_configs(
    discovery_config='./casconf.yaml',
    output='./output/config.json',
    output_format='json'
)
```

```python
from casconf import merge_configs, DiscoveryConfig

# Build a DiscoveryConfig programmatically (no file required)
discovery = DiscoveryConfig(
    directories=[
        '/etc/myapp/defaults',
        '/etc/myapp/$ENVIRONMENT',   # expanded at runtime, e.g. production
        '~/.config/myapp',
    ],
    patterns=['config.json', 'config.yaml'],
    merge_strategy='deep',
)

config = merge_configs(discovery_config=discovery)
```

## Discovery Configuration

CasConf uses a discovery configuration file to determine where to search for configuration files:

```yaml
# casconf.yaml
directories:
  - /etc/myapp/defaults        # site-wide defaults
  - /etc/myapp/$ENVIRONMENT    # environment-specific overrides, e.g. production, staging
  - /etc/myapp/$HOSTNAME       # host-specific overrides, e.g. web-01.example.com
  - ~/.config/myapp            # user overrides (highest priority)

patterns:
  - "config.json"
  - "config.yaml"
  - "*.conf.json"

merge_strategy: deep  # or 'shallow'
```

Directory paths support `~` expansion and `$VAR` / `${VAR}` environment variable expansion. Missing directories are skipped with a warning — no error is raised. See [USAGE.md](USAGE.md) for a full walkthrough.

## License

This project is dual-licensed:

- **MIT License**: When used as a standalone executable (CLI tool)
- **GNU General Public License v3.0 (GPL-3.0)**: When imported or linked as a library

See [LICENSE](LICENSE) for full details.

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

This project follows PEP 8 style guidelines and emphasizes simplicity and maintainability.
