Documentation for acme_config

acme_config.schema

App configuration schema declaration.

Apps subclass AppConfig to declare what configuration they need. Fields are loaded from .env files and environment variables automatically via pydantic-settings, with optional CLI flag mapping.

AppConfig

Bases: BaseSettings

Base class for app configuration.

Subclass this and declare fields to define what configuration your app needs. Values are resolved from (in order of precedence): defaults < .env file < environment variables < CLI args < explicit overrides.

Example::

class MyConfig(AppConfig):
    model_config = {"env_prefix": "MYAPP_"}

    bucket_name: str = ConfigField(description="S3 bucket", cli_flag="--bucket")
    debug: bool = ConfigField(default=False, description="Debug mode")
    db_password: str = ConfigField(description="DB password", secret=True)

Required: set model_config = {"env_prefix": "PREFIX_"} in your subclass.

ConfigField(default=..., *, description='', cli_flag=None, secret=False, **kwargs)

Declare a configuration field with metadata.

Parameters:

Name	Type	Description	Default
default	Any	Default value. Use ... (Ellipsis) for required fields.	...
description	str	Human-readable description of this config option.	''
cli_flag	str | None	CLI argument name (e.g. "--bucket-name"). If set, build_cli_parser() will generate this argument automatically.	None
secret	bool	If True, value is redacted in describe_config() output.	False
**kwargs	Any	Additional arguments passed to pydantic Field.	{}

acme_config.resolver

Config resolution: merge .env, environment, CLI args, and overrides.

build_cli_parser(config_class, prog=None, description=None)

Generate an argparse parser from a config class.

Only fields with cli_flag set will become CLI arguments.

Parameters:

Name	Type	Description	Default
config_class	type[AppConfig]	The AppConfig subclass to generate a parser for.	required
prog	str | None	Program name for the parser.	None
description	str | None	Description for the parser.	None

resolve_config(config_class, cli_args=None, overrides=None, env_file=None)

Create a config instance with full precedence resolution.

Resolution order (later overrides earlier): 1. Field defaults 2. .env file 3. Environment variables 4. CLI args (if provided) 5. Explicit overrides (if provided)

Parameters:

Name	Type	Description	Default
config_class	type[T]	The AppConfig subclass to instantiate.	required
cli_args	dict[str, Any] | None	Dict of CLI argument values (e.g. from argparse). Keys with None values are skipped (not provided).	None
overrides	dict[str, Any] | None	Dict of explicit override values (highest priority).	None
env_file	str | None	Path to .env file. If None, uses the class default.	None

acme_config.features

Feature flag support.

Apps subclass FeatureFlags to declare boolean features that can be toggled via environment variables.

FeatureFlags

Bases: BaseSettings

Base class for feature flag declarations.

Subclass this and declare boolean fields for each feature. Values are loaded from environment variables using the configured prefix.

Example::

class MyFeatures(FeatureFlags):
    model_config = {"env_prefix": "MYAPP_FEATURE_"}

    new_dashboard: bool = FeatureFlag(
        default=False, description="Enable new dashboard UI"
    )
    parallel_processing: bool = FeatureFlag(
        default=True, description="Use parallel data processing"
    )

Required: set model_config = {"env_prefix": "APP_FEATURE_"} in your subclass.

is_enabled(flag_name)

Check if a feature flag is enabled by name.

Parameters:

Name	Type	Description	Default
flag_name	str	The field name of the flag.	required

Raises:

Type	Description
AttributeError	If the flag doesn't exist.

FeatureFlag(default=False, *, description='', **kwargs)

Declare a feature flag.

Parameters:

Name	Type	Description	Default
default	bool	Whether the feature is enabled by default.	False
description	str	Human-readable description of the feature.	''

list_flags(features)

List all feature flags with their current state.

Returns a list of dicts with keys: name, value, description, default. Useful for admin/debug endpoints.

acme_config.inspect

Config inspection utilities.

Generate manifests, dotenv templates, validate environments, and describe config instances with secret redaction.

describe_config(config)

Pretty-print a config instance with secret fields redacted.

Useful for startup logging to confirm which config values are active.

generate_dotenv_template(config_class)

Generate a .env.example template from a config class.

generate_manifest(config_class)

Generate an env.manifest from a config class.

Produces a machine-readable manifest listing all env vars the app expects.

validate_env(config_class)

Check the current environment for missing required config.

Returns a list of issue descriptions. Empty list means all is well.