API Reference¶

Complete Python API documentation for lbx.

Overview¶

The lbx Python API provides programmatic access to all functionality. It's designed to be simple, secure, and intuitive for developers who want to integrate lbx into their applications.

Installation¶

pip install lbx

See Installation Guide for other installation options.

Core Module¶

The main entry point for programmatic access to lbx functionality.

lbx ¶

Public Lbx API exposure.

This module re-exports the high-level Lbx vault manager so users can import it directly from :mod:lbx rather than navigating internal packages. The internal structure remains hidden; only stable API surfaces are exposed here.

Classes¶

Lbx ¶

Lbx(
    path: Path | str | None = None,
    *,
    use_keychain: bool = True,
    binary_service: BinaryService | None = None,
    file_service: FileService | None = None,
    keyring_service: KeyringService | None = None,
    crypto_service: CryptoService | None = None,
)

High-level vault manager.

This class provides the main API for working with an Lbx vault: creating, unlocking, locking, deleting, and managing services and secrets. It composes the service layer into a single cohesive interface.

By default, the derived encryption key is stored in the OS keychain whenever a vault is created or unlocked. This can be controlled via the use_keychain flag.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str \| None`	Optional path to the vault file. If None, the default vault path (as determined by FileService) is used.	`None`
`use_keychain`	`bool`	Whether to store the derived encryption key in the OS keychain when creating or unlocking the vault.	`True`
`binary_service`	`BinaryService \| None`	Optional preconfigured BinaryService instance.	`None`
`file_service`	`FileService \| None`	Optional preconfigured FileService instance.	`None`
`keyring_service`	`KeyringService \| None`	Optional preconfigured KeyringService instance.	`None`
`crypto_service`	`CryptoService \| None`	Optional preconfigured CryptoService instance.	`None`

Attributes¶

is_unlocked property ¶

is_unlocked: bool

Whether the vault is currently unlocked.

Returns:

Name	Type	Description
`bool`	`bool`	True if an encryption key is loaded in memory, False
	`bool`	otherwise.

path property ¶

path: Path

Path to the vault file on disk.

Returns:

Name	Type	Description
`Path`	`Path`	Vault file path.

Functions¶

exists ¶

exists() -> bool

Check whether the vault file exists.

Returns:

Name	Type	Description
`bool`	`bool`	True if the vault file exists, False otherwise.

create ¶

create(password: str) -> None

Create a new vault.

This method:

Fails if a vault file already exists.
Derives a master key and encryption key from the password.
Persists the vault to disk.
Stores the encryption key in the OS keychain if use_keychain is True.

Parameters:

Name	Type	Description	Default
`password`	`str`	Password to derive the master and encryption keys.	required

Raises:

Type	Description
`VaultExistsError`	If a vault file already exists at the configured path.
`InvalidPasswordError`	If the password is empty (raised by CryptoService).
`EncryptionError`	If key derivation or encryption fails.

unlock ¶

unlock(password: str) -> None

Unlock an existing vault using a password.

This method:

Loads the vault from disk.
Verifies the password against the stored master key.
Derives and sets the encryption key.
Stores the encryption key in the OS keychain if use_keychain is True.

Parameters:

Name	Type	Description	Default
`password`	`str`	Password to verify and derive the encryption key.	required

Raises:

Type	Description
`VaultNotFoundError`	If the vault file does not exist.
`InvalidPasswordError`	If the password is empty or incorrect.
`EncryptionError`	If key derivation fails.

unlock_from_keychain ¶

unlock_from_keychain() -> bool

Unlock the vault using the OS keychain.

This method attempts to:

Load the vault from disk.
Retrieve the encryption key from the OS keychain.
Set the encryption key in memory.

Returns:

Name	Type	Description
`bool`	`bool`	True if the key was found and the vault was unlocked,
	`bool`	False if no key exists in the keychain for this service/account.

Raises:

Type	Description
`VaultNotFoundError`	If the vault file does not exist.
`KeychainNotAvailableError`	If the OS keychain is not available.
`KeychainAccessError`	If the keychain is locked or access is denied.
`KeychainDataError`	If the stored key data is invalid.

lock ¶

lock() -> None

Lock the vault and clear the encryption key from memory.

lock_and_forget ¶

lock_and_forget() -> None

Lock the vault and remove the key from the OS keychain.

This clears the in-memory key and deletes the key from the keychain.

delete_vault ¶

delete_vault() -> None

Delete the vault file and any stored keychain entry.

After this operation, the in-memory vault is also cleared.

list_services ¶

list_services() -> list[str]

List all service names in the vault.

Returns:

Type	Description
`list[str]`	list[str]: List of service names.

Raises:

Type	Description
`VaultNotFoundError`	If the vault file does not exist.

has_service ¶

has_service(service: str) -> bool

Check whether a service exists.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name to check.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the service exists, False otherwise.

Raises:

Type	Description
`VaultNotFoundError`	If the vault file does not exist.

delete_service ¶

delete_service(service: str) -> None

Delete a service and all its secrets.

Parameters:

Name	Type	Description	Default
`service`	`str`	Name of the service to delete.	required

Raises:

Type	Description
`ServiceNotFoundError`	If the service does not exist.
`VaultLockedError`	If the vault is locked.

rename_service ¶

rename_service(old_name: str, new_name: str) -> None

Rename a service.

Parameters:

Name	Type	Description	Default
`old_name`	`str`	Existing service name.	required
`new_name`	`str`	New service name.	required

Raises:

Type	Description
`ServiceNotFoundError`	If `old_name` does not exist.
`ServiceExistsError`	If `new_name` already exists.
`VaultLockedError`	If the vault is locked.

list_secrets ¶

list_secrets(
    service: str | None = None,
) -> list[tuple[str, str]]

List secrets, optionally filtered by service.

Parameters:

Name	Type	Description	Default
`service`	`str \| None`	Optional service name. If provided, only secrets for that service are listed. If None, all secrets in the vault are listed.	`None`

Returns:

Type	Description
`list[tuple[str, str]]`	list[tuple[str, str]]: List of (service_name, secret_name)
`list[tuple[str, str]]`	tuples.

Raises:

Type	Description
`ServiceNotFoundError`	If a specific service is requested but does not exist.
`VaultNotFoundError`	If the vault file does not exist.

has_secret ¶

has_secret(service: str, name: str) -> bool

Check whether a secret exists.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`name`	`str`	Secret name.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the secret exists, False otherwise.

Raises:

Type	Description
`VaultNotFoundError`	If the vault file does not exist.

get_secret ¶

get_secret(service: str, name: str) -> SecretEntry

Get a decrypted secret.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`name`	`str`	Secret name.	required

Returns:

Name	Type	Description
`SecretEntry`	`SecretEntry`	Decrypted secret entry.

Raises:

Type	Description
`ServiceNotFoundError`	If the service does not exist.
`SecretNotFoundError`	If the secret does not exist.
`VaultLockedError`	If the vault is locked.

add_secret ¶

add_secret(service: str, name: str, value: str) -> None

Add a new secret.

If the service does not exist, it is created. If the secret already exists in that service, a SecretExistsError is raised.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`name`	`str`	Secret name.	required
`value`	`str`	Secret plaintext value.	required

Raises:

Type	Description
`SecretExistsError`	If the secret already exists in the service.
`VaultLockedError`	If the vault is locked.

update_secret ¶

update_secret(service: str, name: str, value: str) -> None

Update an existing secret.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`name`	`str`	Secret name.	required
`value`	`str`	New plaintext value.	required

Raises:

Type	Description
`ServiceNotFoundError`	If the service does not exist.
`SecretNotFoundError`	If the secret does not exist.
`VaultLockedError`	If the vault is locked.

rename_secret ¶

rename_secret(
    service: str, old_name: str, new_name: str
) -> None

Rename a secret within a service.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`old_name`	`str`	Existing secret name.	required
`new_name`	`str`	New secret name.	required

Raises:

Type	Description
`ServiceNotFoundError`	If the service does not exist.
`SecretNotFoundError`	If `old_name` does not exist.
`SecretExistsError`	If `new_name` already exists in the service.
`VaultLockedError`	If the vault is locked.

move_secret ¶

move_secret(
    source_service: str, name: str, target_service: str
) -> None

Move a secret from one service to another.

The secret keeps the same name in the target service.

Parameters:

Name	Type	Description	Default
`source_service`	`str`	Name of the source service.	required
`name`	`str`	Secret name.	required
`target_service`	`str`	Name of the target service.	required

Raises:

Type	Description
`ServiceNotFoundError`	If the source service does not exist.
`SecretNotFoundError`	If the secret does not exist in the source.
`SecretExistsError`	If the target already has a secret with the same name.
`VaultLockedError`	If the vault is locked.

delete_secret ¶

delete_secret(service: str, name: str) -> None

Delete a secret.

If the service becomes empty after deletion, it is removed.

Parameters:

Name	Type	Description	Default
`service`	`str`	Service name.	required
`name`	`str`	Secret name.	required

Raises:

Type	Description
`ServiceNotFoundError`	If the service does not exist.
`SecretNotFoundError`	If the secret does not exist.
`VaultLockedError`	If the vault is locked.

Exceptions¶

Custom exceptions raised by lbx operations.

exceptions ¶

Exception hierarchy for Lbx.

All library-specific exceptions derive from LbxError. Catch this base class if you want to handle all library errors in one place.

Classes¶

LbxError ¶

Bases: Exception


              flowchart TD
              lbx.exceptions.LbxError[LbxError]

              

              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Base class for all Lbx-specific errors.

InvalidVaultFileError ¶

InvalidVaultFileError(message: str | None = None)

Bases: LbxError


              flowchart TD
              lbx.exceptions.InvalidVaultFileError[InvalidVaultFileError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.InvalidVaultFileError
                


              click lbx.exceptions.InvalidVaultFileError href "" "lbx.exceptions.InvalidVaultFileError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

File is not a valid Lbx vault.

This usually means the magic header does not match BinaryFormat.MAGIC, or the file is not an Lbx vault at all.

Parameters:

Name	Type	Description	Default
`message`	`str \| None`	Optional custom error message.	`None`

UnsupportedVersionError ¶

UnsupportedVersionError(version: int)

Bases: LbxError


              flowchart TD
              lbx.exceptions.UnsupportedVersionError[UnsupportedVersionError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.UnsupportedVersionError
                


              click lbx.exceptions.UnsupportedVersionError href "" "lbx.exceptions.UnsupportedVersionError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Vault version is not supported by this build.

Parameters:

Name	Type	Description	Default
`version`	`int`	Version number found in the vault file.	required

VaultCorruptedError ¶

VaultCorruptedError(
    message: str,
    *,
    offset: int | None = None,
    section: str | None = None,
)

Bases: LbxError


              flowchart TD
              lbx.exceptions.VaultCorruptedError[VaultCorruptedError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.VaultCorruptedError
                


              click lbx.exceptions.VaultCorruptedError href "" "lbx.exceptions.VaultCorruptedError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Vault file is truncated or structurally inconsistent.

This indicates that the file appears to be an Lbx vault (magic matches) but internal structure or lengths are invalid.

Common causes

Length-prefixed blocks exceed available bytes.
Reads attempt to go past the end of the buffer.
Sections are incomplete or malformed.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the corruption.	required
`offset`	`int \| None`	Byte offset where the error was detected.	`None`
`section`	`str \| None`	Logical section name.	`None`

EncryptionError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.EncryptionError[EncryptionError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.EncryptionError
                


              click lbx.exceptions.EncryptionError href "" "lbx.exceptions.EncryptionError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Symmetric encryption or key-derivation error.

Raised when

The encryption key is invalid or not set.
Encryption or key derivation fails.

DecryptionError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.DecryptionError[DecryptionError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.DecryptionError
                


              click lbx.exceptions.DecryptionError href "" "lbx.exceptions.DecryptionError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Symmetric decryption error.

Raised when

The decryption key is invalid or not set.
The authentication tag is invalid.
The decrypted plaintext cannot be decoded.

InvalidPasswordError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.InvalidPasswordError[InvalidPasswordError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.InvalidPasswordError
                


              click lbx.exceptions.InvalidPasswordError href "" "lbx.exceptions.InvalidPasswordError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Password-related error.

Raised when

The password is empty where required.
The password does not match the stored master key.

VaultNotFoundError ¶

VaultNotFoundError(path: str)

Bases: LbxError


              flowchart TD
              lbx.exceptions.VaultNotFoundError[VaultNotFoundError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.VaultNotFoundError
                


              click lbx.exceptions.VaultNotFoundError href "" "lbx.exceptions.VaultNotFoundError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Vault file does not exist.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the missing vault file.	required

VaultIOError ¶

VaultIOError(operation: str, path: str, reason: str)

Bases: LbxError


              flowchart TD
              lbx.exceptions.VaultIOError[VaultIOError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.VaultIOError
                


              click lbx.exceptions.VaultIOError href "" "lbx.exceptions.VaultIOError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Filesystem I/O error related to vault operations.

Wraps lower-level OS and pathlib errors for consistency.

Parameters:

Name	Type	Description	Default
`operation`	`str`	Operation being performed (e.g., "read", "write").	required
`path`	`str`	Filesystem path involved.	required
`reason`	`str`	Human-readable description of the failure.	required

KeychainNotAvailableError ¶

KeychainNotAvailableError()

Bases: LbxError


              flowchart TD
              lbx.exceptions.KeychainNotAvailableError[KeychainNotAvailableError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.KeychainNotAvailableError
                


              click lbx.exceptions.KeychainNotAvailableError href "" "lbx.exceptions.KeychainNotAvailableError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

System keychain is not available.

Raised when the keyring backend cannot be found or initialized.

KeychainAccessError ¶

KeychainAccessError(operation: str, reason: str)

Bases: LbxError


              flowchart TD
              lbx.exceptions.KeychainAccessError[KeychainAccessError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.KeychainAccessError
                


              click lbx.exceptions.KeychainAccessError href "" "lbx.exceptions.KeychainAccessError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

System keychain access error.

Parameters:

Name	Type	Description	Default
`operation`	`str`	Operation being performed (e.g., "store", "retrieve").	required
`reason`	`str`	Reason for the failure (e.g., "permission denied").	required

KeychainDataError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.KeychainDataError[KeychainDataError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.KeychainDataError
                


              click lbx.exceptions.KeychainDataError href "" "lbx.exceptions.KeychainDataError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Invalid or corrupted data in the system keychain.

Raised when stored key data cannot be parsed or has unexpected format.

KeyNotFoundError ¶

KeyNotFoundError(service: str, account: str)

Bases: LbxError


              flowchart TD
              lbx.exceptions.KeyNotFoundError[KeyNotFoundError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.KeyNotFoundError
                


              click lbx.exceptions.KeyNotFoundError href "" "lbx.exceptions.KeyNotFoundError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Key not found in the system keychain.

Parameters:

Name	Type	Description	Default
`service`	`str`	Keyring service name.	required
`account`	`str`	Keyring account name.	required

VaultExistsError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.VaultExistsError[VaultExistsError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.VaultExistsError
                


              click lbx.exceptions.VaultExistsError href "" "lbx.exceptions.VaultExistsError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Vault already exists at the target path.

VaultLockedError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.VaultLockedError[VaultLockedError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.VaultLockedError
                


              click lbx.exceptions.VaultLockedError href "" "lbx.exceptions.VaultLockedError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Operation requires an unlocked vault, but the vault is locked.

ServiceNotFoundError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.ServiceNotFoundError[ServiceNotFoundError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.ServiceNotFoundError
                


              click lbx.exceptions.ServiceNotFoundError href "" "lbx.exceptions.ServiceNotFoundError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Service does not exist in the vault.

SecretNotFoundError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.SecretNotFoundError[SecretNotFoundError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.SecretNotFoundError
                


              click lbx.exceptions.SecretNotFoundError href "" "lbx.exceptions.SecretNotFoundError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Secret does not exist within the given service.

ServiceExistsError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.ServiceExistsError[ServiceExistsError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.ServiceExistsError
                


              click lbx.exceptions.ServiceExistsError href "" "lbx.exceptions.ServiceExistsError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Service already exists in the vault.

SecretExistsError ¶

Bases: LbxError


              flowchart TD
              lbx.exceptions.SecretExistsError[SecretExistsError]
              lbx.exceptions.LbxError[LbxError]

                              lbx.exceptions.LbxError --> lbx.exceptions.SecretExistsError
                


              click lbx.exceptions.SecretExistsError href "" "lbx.exceptions.SecretExistsError"
              click lbx.exceptions.LbxError href "" "lbx.exceptions.LbxError"

Secret already exists within the given service.

API Reference¶

Overview¶

Installation¶

Core Module¶

lbx ¶

Classes¶

Lbx ¶

Attributes¶

Functions¶

Exceptions¶

exceptions ¶

Classes¶

LbxError ¶

InvalidVaultFileError ¶

UnsupportedVersionError ¶

VaultCorruptedError ¶

EncryptionError ¶

DecryptionError ¶

InvalidPasswordError ¶

VaultNotFoundError ¶

VaultIOError ¶

KeychainNotAvailableError ¶

KeychainAccessError ¶

KeychainDataError ¶

KeyNotFoundError ¶

VaultExistsError ¶

VaultLockedError ¶

ServiceNotFoundError ¶

SecretNotFoundError ¶

ServiceExistsError ¶

SecretExistsError ¶

See Also¶