API Reference

This section provides detailed API documentation for ConfigBuddy.

Core Classes

Config

class configbuddy.core.config.Config(data, source=None)

Bases: object

Base class for representing configuration file contents.

This class provides functionality to load, save, and visualize configuration data from various file formats including YAML, JSON, and INI.

__str__()

Convert configuration to a string representation.

Return type:

str

Returns:

String representation of the configuration in a tree structure.

diff_with(config)

Compare this configuration with another using ConfigDiffer.

A convenience method that uses ConfigDiffer to analyze differences between this configuration and another one.

Parameters:

config (Config) – Another Config object to compare with

Return type:

ConfigDiff

Returns:

ConfigDiff object containing the differences between configurations

classmethod from_file(path)

Create a Config object from a file.

Parameters:

path (str | Path) – Path to the configuration file. Can be a string or Path object.

Return type:

Config

Returns:

A new Config instance containing the loaded configuration data.

Raises:

ValueError – If the file format is not supported.

merge_with(config, strategy='deep')

Merge this configuration with another using ConfigMerger.

A convenience method that uses ConfigMerger to merge this configuration with another one. Similar to diff_with, but for merging.

Parameters:

• config (Config) – Another Config object to merge with

• strategy (str) – Merge strategy to use (‘deep’ or ‘shallow’) ‘deep’ recursively merges nested dictionaries ‘shallow’ only merges top-level keys

Returns:

• Config: The merged configuration object

• list[MergeConflict]: List of merge conflicts detected during merging

Return type:

A tuple containing

Example

>>> config1 = Config.from_file('base.yaml')
>>> config2 = Config.from_file('override.yaml')
>>> merged, conflicts = config1.merge_with(config2)
>>> if conflicts:
...     print("Merge conflicts detected:", conflicts)
>>> merged.save('merged.yaml')

save(path=None)

Save configuration to a file.

Parameters:

path (Union[str, Path, None]) – Path where to save the configuration. If None, uses the source path.

Raises:

ValueError – If no path is specified and source is None.

Return type:

None

to_dict()

Convert configuration to a dictionary.

Return type:

dict[str, Any]

Returns:

Dictionary representation of the configuration data.

validate(schema_path)

Validate configuration against a JSON schema.

Parameters:

schema_path (str | Path) – Path to the JSON schema file.

Return type:

list[str] | None

Returns:

List of validation errors or None if no errors are found.

visualize()

Visualize configuration in a tree structure.

Displays the configuration data as a hierarchical tree in the console.

Return type:

None

ConfigDiff

class configbuddy.core.config.ConfigDiff(added, removed, modified, unchanged)

Bases: object

Class representing differences between configuration files.

added

Dictionary of keys and values that were added in the new config

removed

Dictionary of keys and values that were removed from the base config

modified

Dictionary of keys mapping to tuples of (old_value, new_value)

unchanged

Dictionary of keys and values that remained the same

__str__()

Return a string representation of the configuration differences.

Return type:

str

added: dict[str, Any]

modified: dict[str, tuple[Any, Any]]

removed: dict[str, Any]

unchanged: dict[str, Any]

visualize()

Visualize the configuration differences in a tree structure.

Return type:

None

ConfigMerger

class configbuddy.core.merger.ConfigMerger

Bases: object

Class for merging multiple configuration files.

This class provides functionality to merge multiple Config objects, with support for different merge strategies and conflict detection.

The merger supports two strategies: - deep: Recursively merges nested dictionaries - shallow: Only merges top-level keys

When conflicts are detected during merging, they are tracked and returned along with the merged result. A conflict occurs when multiple configs have different values for the same key.

static merge(configs, strategy='deep')

Merge multiple configuration files.

Parameters:

• configs (list[Config]) – List of Config objects to merge. Must contain at least one config.

• strategy (str) – Merge strategy to use. Can be either ‘deep’ or ‘shallow’. ‘deep’ recursively merges nested dictionaries. ‘shallow’ only merges top-level keys.

Returns:

• Config: The merged configuration object

• list[MergeConflict]: List of merge conflicts detected during merging

Return type:

A tuple containing

Raises:

ValueError – If no configs provided or if strategy is not ‘deep’ or ‘shallow’

ConfigValidator

class configbuddy.core.validator.ConfigValidator(schema)

Bases: object

Class for validating configuration files.

This class provides functionality to validate configuration data against a JSON schema.

__init__(schema)

Initialize validator with a schema.

Parameters:

schema (dict[str, Any]) – JSON schema dictionary to validate against

Raises:

jsonschema.exceptions.SchemaError – If the schema itself is invalid

classmethod from_config(config)

Create a validator from an existing configuration.

Parameters:

config (Config) – Configuration object to generate schema from

Return type:

ConfigValidator

Returns:

ConfigValidator instance with schema generated from config

classmethod from_file(schema_path)

Create a validator from a schema file.

Parameters:

schema_path (str | Path) – Path to the JSON schema file

Return type:

ConfigValidator

Returns:

ConfigValidator instance initialized with the schema from file

classmethod generate_schema(config)

Generate a JSON schema from a configuration file.

Return type:

dict[str, Any]

save_schema(path)

Save the current schema to a file.

Parameters:

path (str | Path) – Path where to save the schema

Return type:

None

validate(config)

Validate a configuration against the schema.

Return type:

list[str] | None

Visualizer

class configbuddy.core.visualizer.BaseVisualizer

Bases: ABC

Base class for configuration visualizers.

This abstract class defines the interface that all visualizer implementations must follow. It provides common functionality for displaying configuration data in different formats.

abstract to_string(data)

Convert visualization to string.

Parameters:

data (Any) – The data to convert to string representation

Return type:

str

Returns:

String representation of the visualized data

abstract visualize(data)

Display data in the console.

Parameters:

data (Any) – The data to visualize. The specific type depends on the visualizer implementation.

Return type:

None

class configbuddy.core.visualizer.ConfigData(*args, **kwargs)

Bases: Protocol

Protocol for configuration data.

This protocol defines the required interface for configuration data objects that can be visualized by the TreeVisualizer.

data

Dictionary containing the configuration data

source

Optional path to the source configuration file

property data: dict[str, Any]

property source: Path | None

class configbuddy.core.visualizer.DiffVisualizer

Bases: BaseVisualizer

Visualizer for configuration differences.

This visualizer displays the differences between two configurations, highlighting added, removed, and modified values in different colors.

to_string(diff)

Convert the configuration differences visualization to a string.

Parameters:

diff (ConfigDiff) – ConfigDiff object containing added, removed, modified, and unchanged items

Return type:

str

Returns:

String representation of the configuration differences visualization

visualize(diff)

Display the configuration differences in the console.

Parameters:

diff (ConfigDiff) – ConfigDiff object containing added, removed, modified, and unchanged items

Return type:

None

class configbuddy.core.visualizer.TreeVisualizer

Bases: BaseVisualizer

Visualizer for configuration data in tree structure.

This visualizer displays configuration data as a colored tree structure, with different colors for each level of nesting and different data types.

__init__()

Initialize the TreeVisualizer with a predefined set of colors for different tree levels.

to_string(config)

Convert the configuration tree visualization to a string.

Parameters:

config (ConfigData) – Configuration data object implementing the ConfigData protocol

Return type:

str

Returns:

String representation of the configuration tree visualization

visualize(config)

Display the configuration data as a tree in the console.

Parameters:

config (ConfigData) – Configuration data object implementing the ConfigData protocol

Return type:

None

Types

class configbuddy.core.types.ConfigDiff(added, removed, modified, unchanged)

Bases: object

Class representing differences between configuration files.

added

Dictionary of keys and values that were added in the new config

removed

Dictionary of keys and values that were removed from the base config

modified

Dictionary of keys mapping to tuples of (old_value, new_value)

unchanged

Dictionary of keys and values that remained the same

__str__()

Return a string representation of the configuration differences.

Return type:

str

added: dict[str, Any]

modified: dict[str, tuple[Any, Any]]

removed: dict[str, Any]

unchanged: dict[str, Any]

visualize()

Visualize the configuration differences in a tree structure.

Return type:

None

class configbuddy.core.types.MergeConflict(key, values, sources)

Bases: object

Class representing a merge conflict between configurations.

key

The configuration key where the conflict occurred

values

List of conflicting values from different sources

sources

List of source identifiers where the conflicting values came from

key: str

sources: list[str]

values: list[Any]

CLI

class configbuddy.cli.cli.CLI(args=None)

Bases: object

add_subcommands()

Return type:

None

execute()

Return type:

None

init_parser()

Return type:

ArgumentParser