confumo 0.1.5

Platform-aware configuration management (CLI flags + env + YAML/JSON deep-merge)

Confumo

Confumo derives from "Confuse more". It's a thin Python module that merges command-line flags, environment variables, and YAML/JSON files into a single, deep-merged configuration object. The object is always a singleton per application name and can be exposed at module scope so existing code keeps working.

One line to register your flags, one line to expose the config to the rest of your project.

Highlights

✨	Description
Merged sources	argparse • ENV vars • YAML/JSON • defaults
Singleton registry	Only one ArgumentParser run per app_name
Auto flag inheritance	Base class + mix-ins + leaf class all show up in --help
Lazy “print-once” help	Libraries defer --help; root application prints merged help
Module-level proxy	from my_app.config import log_level still works
Deep-merge	Powered by confuse
Cross-platform paths	Uses platformdirs

Installation

pip install confumo

1 · Define a config class

# ui_layer/config.py
import argparse
from confumo import Confumo

class UIConfig(Confumo):
    def add_args(self, p: argparse.ArgumentParser):
        p.add_argument('--theme', choices=['light', 'dark', 'auto'], default='auto')
        p.add_argument('--font', default='Roboto')

    def _init_subclass(self):
        self.theme = self.args.theme
        self.font = self.cfg['font'].get(str)

    def to_dict(self):
        return {'theme': self.theme, 'font': self.font}

2 · Expose it (library mode)

UIConfig is meant to be reused by many apps, so the library defers --help printing:

# ui_layer/config.py  (bottom of file)
config = Confumo.expose(
    'ui_layer',
    UIConfig,
    globals(),
    root=False,
)

Now any package can do:

from ui_layer import config
print(config.theme)

and the singleton is shared process-wide.

3 · Extend it in an application

# cool_app/config.py
import argparse
from confumo import Confumo
from ui_layer.config import UIConfig

class CoolAppConfig(UIConfig):
    def add_args(self, p: argparse.ArgumentParser):
        p.add_argument('--log_level', default='INFO',
                       choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'])
        p.add_argument('--library_path', default='~/Pictures')

    def _init_subclass(self):
        super()._init_subclass()
        self.log_level = self.cfg['log_level'].get(str)
        self.library_path = self.cfg['library_path'].get(str)

    def to_dict(self):
        base = super().to_dict()
        base.update({'log_level': self.log_level,
                     'library_path': self.library_path})
        return base

config = Confumo.expose(
    'cool_app',
    CoolAppConfig,
    globals(),
    publish_to=('ui_layer.config',),
)

Running the application:

python cool_app/main.py --help

prints all flags exactly once.

4 · Access the config

from cool_app import config
print(config.library_path)

from confumo import Confumo
cfg = Confumo.get('cool_app', CoolAppConfig)

Both lines refer to the same singleton.

Precedence order

1. CLI flags (--foo bar)
2. Environment variables (COOL_APP__FOO=bar)
3. YAML file (-c settings.yml) or default path
4. Defaults hard-coded in your subclass

confuse handles deep-merging dicts and lists.

Persist the merged config

path = config.save_yaml()  # ~/.config/cool_app/cool_app_config.yaml (Linux)

The file contains the fully merged state for later inspection.

Testing helpers

config.copy() returns a shallow clone whose attribute changes do not affect the singleton.

License

This repository ships under 0BSD; see LICENSE.

Licensing / provenance notice

This repository may include AI-generated material and minimal human-authored material. To the extent any portion of this repository is not copyrightable, it is made available without restriction.

No third-party source or license texts are currently bundled in-tree. Any third-party material added later remains subject to its original terms.