002. Hierarchical Configuration Following Package Structure

Status

Accepted

Context

Applications and libraries need independent diagnostic configuration without conflicts. The standard library logging module addresses this through logger hierarchies, but has limitations:

  • Library developers are strongly advised against custom log levels

  • Logger propagation defaults to enabled, causing noise pollution

  • Configuration is mutable and can be changed by any code

  • Libraries must explicitly opt-out of propagation to avoid interfering with applications

The diagnostic system needs:

  • Library isolation: Libraries configure diagnostics without affecting application or other libraries

  • Application control: Applications can enable/disable library diagnostics selectively

  • Hierarchical inheritance: Subpackages inherit parent configuration with local overrides

  • Immutable configuration: Configuration errors detected at setup time, not runtime

Decision

Implement hierarchical configuration following Python package structure:

Address-Based Registry: Configuration keyed by module/package address ("myapp", "myapp.subsystem", "library"). Each address specifies active flavors, max trace level, printer factory, and compositor factory.

Hierarchical Inheritance: When resolving configuration for "myapp.subsystem.module", search in order:

  1. Exact match ("myapp.subsystem.module")

  2. Parent package ("myapp.subsystem")

  3. Grandparent package ("myapp")

  4. Global configuration (None key)

First match for each configuration property wins. This allows fine-grained overrides without duplicating entire configurations.

Immutable Accretive Registry: Use accretive dictionary (append-only) for address registrations. Libraries register during import. Applications can update active flavors but cannot delete library registrations.

Per-Flavor Overrides: Each address can specify per-flavor configuration (custom compositor, context inclusion). Enables “all errors use logging but notes use stderr” scenarios.

Alternatives

Flat Global Configuration

Single global configuration with no hierarchy.

Rejected: Libraries and applications conflict. No way for libraries to provide defaults that applications can override. Requires every module to explicitly configure or use globals (violates library-friendly goal).

Prefix-Based Matching

Allow wildcard patterns ("myapp.*", "library.*.debug").

Rejected: Adds regex complexity. Matching order becomes ambiguous (which pattern takes precedence?). Harder to reason about configuration resolution. Python package hierarchy already provides natural specificity ordering.

Logger-Style Propagation

Follow logging model: messages propagate up hierarchy with per-level enable/disable.

Rejected: Propagation causes noise pollution (why logging recommends libraries disable it). Inverted control flow harder to reason about. Disabling propagation in libraries shifts responsibility to library authors rather than application users.

Configuration Files

Load configuration from TOML/YAML/INI files.

Rejected: Adds deployment complexity (where is config file? how to specify path?). Library configuration awkward (do libraries ship config files?). Runtime file parsing. Does not eliminate need for programmatic API (testing, dynamic configuration). File-based config can be added later as optional convenience.

Consequences

Positive Consequences

  • Library independence: Each library registers its own configuration without seeing or affecting others.

  • Application control: Applications modify active flavors for specific addresses to enable library diagnostics.

  • Inheritance clarity: Configuration resolution follows Python’s own package hierarchy, matching developer mental model.

  • Immutability safety: Accretive registry prevents configuration changes after registration (except explicit updates by applications).

  • Testability: Tests can register temporary configurations that shadow defaults without mutation.

Negative Consequences

  • Registration timing: Libraries must register before application installation if using builtins pattern (documented deployment pattern).

  • Memory overhead: Each address stores full configuration even if mostly inheriting from parent (mitigated by sharing immutable objects).

  • Discovery complexity: No introspection API to list all registered addresses (could be added if needed).

Neutral Consequences

  • Search cost: Configuration resolution walks up package hierarchy (typically 2-4 steps, negligible for diagnostic output).

  • Granularity trade-off: Per-module configuration possible but not required (most users configure at package level).