Module

debug.config_inspector

Configuration Inspector and Diff Tool.

Advanced configuration comparison and analysis beyond the basicbengal config diff. Supports comparing arbitrary config sources, explaining effective values, and identifying potential configuration issues.

Example usage:

inspector = ConfigInspector(site)
diff = inspector.compare(source1="local", source2="production")
print(diff.format_detailed())
View source
4 Classes

Classes

ConfigDiff dataclass
A single configuration difference.
1

A single configuration difference.

Attributes

Name Type Description
path str
type Literal['added', 'removed', 'changed']
old_value Any
new_value Any
old_origin str | None
new_origin str | None
impact str | None

Methods 1

format
Format the diff for display.
0 str 
def format(self) -> str

Format the diff for display.

Returns

str

ConfigComparisonResult dataclass
Result of comparing two configurations.
6

Result of comparing two configurations.

Attributes

Name Type Description
source1 str
source2 str
diffs list[ConfigDiff]
config1 dict[str, Any]
config2 dict[str, Any]

Methods 6

has_changes property
Check if there are any differences.
bool 
def has_changes(self) -> bool

Check if there are any differences.

Returns

bool

added property
Get added keys.
list[ConfigDiff] 
def added(self) -> list[ConfigDiff]

Get added keys.

Returns

list[ConfigDiff]

removed property
Get removed keys.
list[ConfigDiff] 
def removed(self) -> list[ConfigDiff]

Get removed keys.

Returns

list[ConfigDiff]

changed property
Get changed keys.
list[ConfigDiff] 
def changed(self) -> list[ConfigDiff]

Get changed keys.

Returns

list[ConfigDiff]

format_summary
Format a summary of differences.
0 str 
def format_summary(self) -> str

Format a summary of differences.

Returns

str

format_detailed
Format detailed diff output.
0 str 
def format_detailed(self) -> str

Format detailed diff output.

Returns

str

KeyExplanation dataclass
Explanation of how a config key got its value.
1

Explanation of how a config key got its value.

Attributes

Name Type Description
key_path str
effective_value Any
origin str | None
layer_values list[tuple[str, Any]]
is_default bool
deprecated bool
deprecation_message str | None

Methods 1

format
Format the explanation.
0 str 
def format(self) -> str

Format the explanation.

Returns

str

ConfigInspector
Advanced configuration inspector and diff tool. Provides: - Deep comparison between any config sou…
12

Advanced configuration inspector and diff tool.

Provides:

  • Deep comparison between any config sources
  • Origin tracking for each value
  • Impact analysis for differences
  • Key-level explanation of value resolution
  • Default value detection
  • Deprecation warnings
Inherits from DebugTool

Attributes

Name Type Description
name str
description str
IMPACT_PATTERNS dict[str, str]

Methods 5

run
Run config inspection.
3 DebugReport 
def run(self, compare_to: str | None = None, explain_key: str | None = None, list_sources: bool = False, **kwargs: Any) -> DebugReport

Run config inspection.

Parameters 3
compare_to str | None

Source to compare against (environment or profile)
explain_key str | None

Specific key to explain
list_sources bool

List available config sources **kwargs: Additional arguments
Returns

DebugReport —

DebugReport with findings

analyze
Perform analysis and return report. This is the abstract method required by De…
0 DebugReport 
def analyze(self) -> DebugReport

Perform analysis and return report.

This is the abstract method required by DebugTool. For parameterized analysis, use run() instead.

Returns

DebugReport

compare
Compare two configuration sources.
3 ConfigComparisonResult 
def compare(self, source1: str, source2: str, track_origins: bool = True) -> ConfigComparisonResult

Compare two configuration sources.

Parameters 3
source1 str

First source (environment name, "profile:name", or file path)
source2 str

Second source
track_origins bool

Track origin of each value
Returns

ConfigComparisonResult —

ConfigComparisonResult with all differences

explain_key
Explain how a config key got its effective value. Shows the resolution chain t…
1 KeyExplanation | None 
def explain_key(self, key_path: str) -> KeyExplanation | None

Explain how a config key got its effective value.

Shows the resolution chain through defaults → environment → profile.

Parameters 1
key_path str

Dot-separated key path (e.g., "site.title")
Returns

KeyExplanation | None —

KeyExplanation or None if key not found

find_issues
Find potential configuration issues. Checks for: - Deprecated keys - Missing r…
0 list[DebugFinding] 
def find_issues(self) -> list[DebugFinding]

Find potential configuration issues.

Checks for:

  • Deprecated keys
  • Missing required keys
  • Type mismatches
  • Suspicious values
Returns

list[DebugFinding] —

List of findings

Internal Methods 7
__init__
Initialize inspector.
1 None 
def __init__(self, site: Any) -> None

Initialize inspector.

Parameters 1
site Any

Site instance
_list_available_sources
List available configuration sources.
0 list[str] 
def _list_available_sources(self) -> list[str]

List available configuration sources.

Returns

list[str]

_load_config_source
Load configuration from a source.
2 tuple[dict[str, Any… 
def _load_config_source(self, source: str, track_origins: bool = True) -> tuple[dict[str, Any], dict[str, str]]

Load configuration from a source.

Parameters 2
source str

Source identifier
track_origins bool

Whether to track origins
Returns

tuple[dict[str, Any], dict[str, str]] —

Tuple of (config_dict, origins_dict)

_compute_diffs
Recursively compute diffs between configs.
6 None 
def _compute_diffs(self, config1: dict[str, Any], config2: dict[str, Any], origins1: dict[str, str], origins2: dict[str, str], path: list[str], diffs: list[ConfigDiff]) -> None

Recursively compute diffs between configs.

Parameters 6
config1 dict[str, Any]
config2 dict[str, Any]
origins1 dict[str, str]
origins2 dict[str, str]
path list[str]
diffs list[ConfigDiff]
_get_impact
Get potential impact description for a config key.
1 str | None 
def _get_impact(self, key: str) -> str | None

Get potential impact description for a config key.

Parameters 1
key str
Returns

str | None

_load_defaults_only
Load only the _default config files.
1 dict[str, Any] 
def _load_defaults_only(self, defaults_dir: Path) -> dict[str, Any]

Load only the _default config files.

Parameters 1
defaults_dir Path
Returns

dict[str, Any]

_get_nested_value
Get a value from nested dict using dot-separated path.
2 Any 
def _get_nested_value(self, config: dict[str, Any], key_path: str) -> Any

Get a value from nested dict using dot-separated path.

Parameters 2
config dict[str, Any]
key_path str
Returns

Any