Key value store

Key Value (KV) interface for versioned secret storage.

This module defines the abstract interface and data structures for implementing versioned key-value stores that manage secrets with full lifecycle support.

Use this interface when: - Building new secret storage backend integrations - Implementing custom secret management solutions - Requiring versioned storage with atomic operations

Key features: - Versioned secrets with full history tracking - Soft-delete and restore capabilities for safety - Check-and-set (CAS) for optimistic locking - Patch operations for partial updates with retry logic

BaseKeyValueStore

Bases: ABC

Abstract base class for Key Value (KV) implementations.

This interface defines the contract for KV implementations that handle key-value storage operations.

delete(path, *, versions) abstractmethod

Soft-delete secret versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to soft-delete.	required

Returns:

Type	Description
None	None

destroy(path, *, versions) abstractmethod

Permanently destroy secret versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to permanently destroy.	required

Returns:

Type	Description
None	None

list(path) abstractmethod

List child keys at a path.

Parameters:

Name	Type	Description	Default
path	str	The path to list keys from.	required

Returns:

Type	Description
list[str]	list[str]: List of key names at the given path.

patch(path, data, *, cas=None)

Merge keys into an existing secret and write a new version.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The data to merge into the existing secret.	required
cas	int | None	The version to write. Check the version available before writing.	None

Raises:

Type	Description
RequestException	If the secret cannot be patched.

read(path, *, options=None) abstractmethod

Read a secret.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
options	ReadOption | None	Read options including version. Defaults to None.	None

Returns:

Name	Type	Description
Secret	Secret	The secret data and metadata.

Raises:

Type	Description
RequestException	If the secret cannot be read.

undelete(path, *, versions) abstractmethod

Restore soft-deleted versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to restore.	required

Returns:

Type	Description
None	None

write(path, data, *, options=None) abstractmethod

Write a full secret snapshot.

This ALWAYS creates a new version. Partial updates must use patch().

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The secret data to write.	required
options	WriteOption | None	Write options including CAS. Defaults to None.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the secret cannot be written.

Metadata(version, created_time=None, deletion_time=None, destroyed=False, custom_metadata=None) dataclass

Metadata for a secret.

Attributes:

Name	Type	Description
version	int	The version of the secret.
created_time	str | None	The time the secret was created.
deletion_time	str | None	The time the secret was deleted.
destroyed	bool	Whether the secret has been destroyed.
custom_metadata	dict[str, str] | None	Custom metadata for the secret.

ReadOption(version=None) dataclass

Read options.

Attributes:

Name	Type	Description
version	int | None	The version to read.

Secret(data, metadata) dataclass

Secret data.

Attributes:

Name	Type	Description
data	dict[str, str]	The secret data.
metadata	Metadata	The metadata for the secret.

WriteOption(cas=None) dataclass

Write options.

Attributes:

Name	Type	Description
cas	int | None	The version to write. Check the version available before writing.