casconf 0.2.0

Cascading Configuration Manager - deep-merge configuration files across multiple directories

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 - Getting started guide with examples
• ARCHITECTURE.md - System design and component overview
• DESIGN.md - Design decisions and rationale
• CONTRIBUTING.md - Contribution guidelines
• API.md - Library API reference

Installation

# From PyPI (when published)
pip install casconf

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

Basic Usage

Command-Line Interface

# 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

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'
)

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:

# 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 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 for full details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

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