or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdsources.mdtemplates.mdviews.md
tile.json

tessl/pypi-confuse

Painless YAML configuration library for Python applications with validation, type checking, and multi-source data merging

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/confuse@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-confuse@2.0.0

index.mddocs/

Confuse

A comprehensive Python library for creating flexible, hierarchical configuration systems with validation, type checking, and multi-source data merging. Confuse provides transparent validation through a dictionary-like API, supports layered configuration from multiple sources, automatically discovers platform-specific configuration directories, and integrates seamlessly with command-line argument parsing and environment variables.

Package Information

  • Package Name: confuse
  • Language: Python
  • Installation: pip install confuse

Core Imports

import confuse

Common for configuration management:

from confuse import Configuration, ConfigView

For validation templates:

from confuse import Integer, String, Filename, Choice

Basic Usage

import confuse

# Create a configuration for your application
config = confuse.Configuration('myapp', read=True)

# Read values with validation
number = config['port'].get(int)  # Get port as integer
name = config['name'].as_str()    # Get name as string

# Set values programmatically
config['debug'] = True
config.set({'logging': {'level': 'INFO'}})

# Use templates for complex validation
template = {
    'database': {
        'host': str,
        'port': confuse.Integer(default=5432),
        'ssl': bool,
    },
    'features': confuse.StrSeq(),  # List of strings
    'output_dir': confuse.Filename(),  # Validated file path
}

# Get validated configuration
validated = config.get(template)
print(f"Database: {validated.database.host}:{validated.database.port}")
print(f"Features: {validated.features}")
print(f"Output directory: {validated.output_dir}")

Architecture

Confuse uses a layered architecture that enables flexible configuration management:

  • Configuration: Main class managing multiple data sources in priority order
  • ConfigView: Query interface providing dictionary-like and attribute-style access
  • Sources: Different input types (YAML files, environment variables, command-line args)
  • Templates: Type validation and conversion system with built-in and custom validators
  • Layered Priority: User config overrides system config which overrides built-in defaults

This design allows seamless merging of configuration data from multiple sources while providing type safety and validation throughout the application.

Capabilities

Configuration Management

Core configuration system that manages multiple data sources, handles file reading, and provides platform-aware configuration directory discovery.

class Configuration:
    def __init__(self, appname, modname=None, read=True, loader=yaml_util.Loader): ...
    def config_dir(self): ...
    def user_config_path(self): ...
    def read(self, user=True, defaults=True): ...
    def set_file(self, filename, base_for_paths=False): ...
    def set_env(self, prefix=None, sep='__'): ...
    def dump(self, full=True, redact=False): ...
    def reload(self): ...

class LazyConfig(Configuration):
    def __init__(self, appname, modname=None): ...

Configuration Management

Views and Data Access

Dictionary-like interface for querying configuration data with support for nested access, type conversion, and validation.

class ConfigView:
    def get(self, template=REQUIRED): ...
    def exists(self): ...
    def keys(self): ...
    def items(self): ...
    def values(self): ...
    def set(self, value): ...
    def add(self, value): ...
    def set_args(self, namespace, dots=False): ...
    def as_str(self): ...
    def as_filename(self): ...
    def as_number(self): ...
    def as_choice(self, choices): ...

Views and Data Access

Type Validation

Comprehensive template system for validating and converting configuration values with built-in templates for common types and support for custom validation logic.

class Template:
    def __init__(self, default=REQUIRED): ...
    def value(self, view, template=None): ...

class Integer(Template): ...
class Number(Template): ...
class String(Template):
    def __init__(self, default=REQUIRED, pattern=None, expand_vars=False): ...

class Choice(Template):
    def __init__(self, choices, default=REQUIRED): ...

class Filename(Template):
    def __init__(self, default=REQUIRED, cwd=None, relative_to=None, 
                 in_app_dir=False, in_source_dir=False): ...

class Sequence(Template):
    def __init__(self, subtemplate): ...

class MappingTemplate(Template):
    def __init__(self, mapping): ...

Type Validation

Sources and Integration

Support for multiple configuration data sources including YAML files, environment variables, and command-line arguments with automatic type conversion and priority handling.

class ConfigSource:
    def __init__(self, value, filename=None, default=False, base_for_paths=False): ...

class YamlSource(ConfigSource):  
    def __init__(self, filename=None, default=False, base_for_paths=False, 
                 optional=False, loader=yaml_util.Loader): ...

class EnvSource(ConfigSource):
    def __init__(self, prefix, sep='__', lower=True, handle_lists=True,
                 parse_yaml_docs=False, loader=yaml_util.Loader): ...

Sources and Integration

Exception Handling

class ConfigError(Exception): ...
class NotFoundError(ConfigError): ...
class ConfigValueError(ConfigError): ...
class ConfigTypeError(ConfigValueError): ...
class ConfigTemplateError(ConfigError): ...
class ConfigReadError(ConfigError): ...

Configuration errors provide detailed information about missing values, type mismatches, and file reading problems to help with debugging configuration issues.

Utility Functions

Core utility functions for platform support, data processing, and configuration handling.

def iter_first(sequence):
    """Get the first element from an iterable or raise ValueError."""

def namespace_to_dict(obj):
    """Convert argparse.Namespace or optparse.Values to dict representation."""

def build_dict(obj, sep='', keep_none=False):
    """Recursively build nested dictionary from namespace/dict with key splitting."""

def find_package_path(name):
    """Return path to package containing the named module."""

def xdg_config_dirs():
    """Return list of XDG configuration directory paths."""

def config_dirs():
    """Return platform-specific configuration directory candidates in priority order."""

def parse_as_scalar(value, loader=yaml_util.Loader):
    """Parse value as YAML scalar for consistent type conversion."""

def restore_yaml_comments(data, default_data):
    """Restore comments from default YAML to generated data."""

Constants

Core constants used throughout the library for configuration file names, redaction, and platform-specific behavior.

REQUIRED = object()  # Sentinel indicating no default value for templates
CONFIG_FILENAME = 'config.yaml'           # Default configuration filename
DEFAULT_FILENAME = 'config_default.yaml'  # Default package configuration filename
ROOT_NAME = 'root'                        # Name for root configuration view
REDACTED_TOMBSTONE = 'REDACTED'           # Placeholder for redacted sensitive values

# Platform-specific directory constants
UNIX_DIR_FALLBACK = '~/.config'                    # Unix/Linux config directory fallback
WINDOWS_DIR_VAR = 'APPDATA'                        # Windows environment variable for config dir
WINDOWS_DIR_FALLBACK = '~\\AppData\\Roaming'       # Windows config directory fallback
MAC_DIR = '~/Library/Application Support'          # macOS config directory