Configuration Versioning

Configuration versioning and history management for Confii.

This module provides versioning capabilities for configurations, allowing tracking of changes over time and rollback functionality.

class confii.config_versioning.ConfigVersion(version_id: str, config_dict: Dict[str, Any], timestamp: float | None = None, metadata: Dict[str, Any] | None = None)

Bases: object

Represents a single immutable snapshot of a configuration.

Each version captures the full configuration dictionary, a timestamp, and optional metadata (author, commit message, etc.). Instances are created by ConfigVersionManager.save_version() and can be serialised to / deserialised from JSON with to_dict() and from_dict().

version_id

Unique identifier (SHA-256 prefix) for this version.

config_dict

The configuration dictionary captured in this snapshot.

timestamp

Unix timestamp when the version was created.

metadata

Arbitrary metadata dict (e.g., author, change description).

Example

>>> version = ConfigVersion(
...     version_id="abc123",
...     config_dict={"database": {"host": "localhost"}},
...     metadata={"author": "deploy-bot"},
... )
>>> version.to_dict()["version_id"]
'abc123'

__init__(version_id: str, config_dict: Dict[str, Any], timestamp: float | None = None, metadata: Dict[str, Any] | None = None) → None

Initialize a configuration version.

Parameters:

• version_id – Unique version identifier

• config_dict – Configuration dictionary for this version

• timestamp – Version timestamp (default: current time)

• metadata – Optional metadata dictionary

classmethod from_dict(data: Dict[str, Any]) → ConfigVersion

Create ConfigVersion from dictionary.

Parameters:

data – Dictionary containing version data

Returns:

ConfigVersion instance

to_dict() → Dict[str, Any]

Convert version to dictionary.

Returns:

Dictionary representation of the version

class confii.config_versioning.ConfigVersionManager(storage_path: str | None = None, max_versions: int | None = None)

Bases: object

Manages configuration versions and history.

Provides save, retrieve, list, rollback, and diff operations over a series of ConfigVersion snapshots. Versions are persisted as individual JSON files under storage_path and are also held in an in-memory cache for fast access. Oldest versions are automatically evicted when max_versions is exceeded.

Use this class when you need an audit trail of configuration changes or the ability to roll back to a known-good configuration.

storage_path

pathlib.Path directory where version JSON files are stored.

max_versions

Maximum number of versions retained before eviction.

Example

>>> manager = ConfigVersionManager(storage_path="/tmp/cfg_versions")
>>> v1 = manager.save_version({"debug": False}, metadata={"author": "ci"})
>>> v2 = manager.save_version({"debug": True})
>>> manager.rollback(v1.version_id)
{'debug': False}

DEFAULT_MAX_VERSIONS = 100

__init__(storage_path: str | None = None, max_versions: int | None = None) → None

Initialize version manager.

Parameters:

• storage_path – Path to store version history (default: .confii/versions)

• max_versions – Maximum number of versions to keep. Oldest versions are evicted when the limit is reached. None means use default (100).

diff_versions(version_id1: str, version_id2: str) → List[Any]

Compare two configuration versions.

Parameters:

• version_id1 – First version ID

• version_id2 – Second version ID

Returns:

List of differences between versions

Example

>>> diffs = manager.diff_versions("abc123", "def456")
>>> for diff in diffs:
...     print(f"{diff.key}: {diff.diff_type.value}")

get_latest_version() → ConfigVersion | None

Get the latest configuration version.

Returns:

Latest ConfigVersion instance, or None if no versions exist

get_version(version_id: str) → ConfigVersion | None

Get a configuration version by ID.

Parameters:

version_id – Version ID to retrieve

Returns:

ConfigVersion instance, or None if not found

Example

>>> version = manager.get_version("abc123")
>>> if version:
...     config = version.config_dict

list_versions(limit: int | None = None) → List[ConfigVersion]

List all configuration versions.

Parameters:

limit – Optional limit on number of versions to return

Returns:

List of ConfigVersion instances, sorted by timestamp (newest first)

Example

>>> versions = manager.list_versions(limit=10)
>>> for version in versions:
...     print(f"{version.version_id}: {version.timestamp}")

rollback(version_id: str) → Dict[str, Any]

Rollback to a specific configuration version.

Parameters:

version_id – Version ID to rollback to

Returns:

Configuration dictionary from the specified version

Raises:

ValueError – If version not found

Example

>>> config_dict = manager.rollback("abc123")
>>> # Use config_dict to restore configuration

save_version(config_dict: Dict[str, Any], metadata: Dict[str, Any] | None = None) → ConfigVersion

Save a new configuration version.

Parameters:

• config_dict – Configuration dictionary to version

• metadata – Optional metadata (e.g., author, message)

Returns:

ConfigVersion instance

Example

>>> manager = ConfigVersionManager()
>>> version = manager.save_version(
...     config_dict,
...     metadata={
...         "author": "user@example.com",
...         "message": "Updated database config",
...     },
... )