Skip to main content

Extending Configuration

Extending Configuration

Internal Extension

Add one project setting without creating a mismatch among initialization, resolution, runtime behavior, and reference docs.

Command[tool.custy]

Category

Developer Guide

Quick Command

template -> user config -> resolver -> consumer
TOMLConfigLoaderconfiguration precedence
Packaged Source
app/templates/config.toml
Project Copy
.config/custy/config.toml
Root Namespace
tool.custy
Default Priority
CLI -> config -> built-in

Overview​

custy init copies the packaged configuration resource into a user's project. At runtime, ConfigLoader parses the project-owned file, extracts [tool.custy], and lets command resolvers select explicit CLI values before project values and built-in defaults.

Configuration Lifecycle

Workflow Timeline

1
Define the packaged setting
Add the key, safe default, and useful comment to app/templates/config.toml under the correct [tool.custy] table.
completed
2
Initialize a project copy
Custy's initialization registry copies the packaged resource to .config/custy/config.toml according to init overwrite and prompt policy.
completed
3
Load the namespace
ConfigLoader parses TOML and exposes the contents beneath tool.custy.
current
4
Resolve an effective value
A command resolver or typed subsystem resolver reads the exact nested path and applies fallback behavior.
pending
5
Consume and verify
Core behavior uses the value, tests cover precedence and validation, and public docs explain scope, defaults, and status.
pending

Choose the Correct Namespace

Configuration Ownership

Project

Use tool.custy.project for project-wide source and identity choices.

CLI Defaults

Use tool.custy.cli for paths, templates, execution, versioning, push, backup, cleanup, and command-level defaults.

Changelog Engine

Use tool.custy.changelog for collection, cleaning, release handling, mapping, links, and rendering.

Git Remotes

Use tool.custy.git for default, primary, and backup remote policy.

Logging

Use tool.custy.logging for console and rotating-file output behavior.

Initialization

Use tool.custy.init for generation, overwrite, and prompting defaults.

Resolve the Setting

Use ConfigLoader.resolve() for a value that can be supplied by the CLI, project configuration, or a built-in fallback.

Resolution example
python
effective_value = config.resolve(
  cli_value=cli_args.example_value,
  config_keys=["cli", "example", "value"],
  default="safe-default",
)

Use get() for optional nested reads, require() when absence must fail, and get_section() when a subsystem owns a complete mapping. Paths passed to the loader start below [tool.custy].

Carry the Value to Runtime

Before You Begin

  • CLI declarationRequired

    Add an optional Typer value when one-run override is useful; leave it unspecified when configuration fallback should remain possible.

  • Resolved modelRequired

    Add a typed field to the command dataclass or subsystem configuration model.

  • Resolver pathRequired

    Use exactly the table and key written by the packaged template.

  • Workflow transportRequired

    Extend WorkflowConfig and WorkflowEngineBuilder only when the value must cross from the CLI into pipeline-backed core behavior.

  • Runtime consumerRequired

    Apply the effective value in one responsible service, engine, renderer, provider, or handler.

  • Initialization behaviorRequired

    Verify fresh init output and deliberate force or prompt handling when the packaged template changes.

Typed Subsystem Configuration

The changelog subsystem converts nested mappings into dataclasses through ChangelogConfigResolver. For a new changelog property, update the matching dataclass, the appropriate _load_*() method and default, the consumer, and focused resolver and behavior tests. Normalize invalid shapes intentionally; do not assume every TOML value has the expected dictionary or enum form.

Testing and Documentation

  • Test explicit CLI precedence, configured values, missing keys, and the built-in default.
  • Test invalid TOML, invalid types or enum values, and required-value failures according to the intended contract.
  • Test the actual consumer so a key cannot appear implemented while remaining unused.
  • Verify a newly initialized project receives the intended key and comment.
  • Update the matching configuration namespace page and the complete property reference with type, default, effect, and implementation status.
  • Update command options, examples, safety, and troubleshooting when the new value changes user behavior.

Continue

Related Commands

Commands commonly used together with this command.

All Properties

Keep the full generated and supported key inventory synchronized.