Python API

Root exports below are the package's public import surface. The narrative architecture documents behavior and limitations; some source docstrings still use broader “never-leak” wording. API tables here show contracts without repeating those descriptions.

axm_vault

MASK = '********' module-attribute

SERVICE = 'axm-vault' module-attribute

__all__ = ['MASK', 'SERVICE', 'AuthDependencySpec', 'AuthSource', 'AuthStatus', 'Catalog', 'CatalogRejection', 'CredentialGroup', 'CredentialSpec', 'InstanceSource', 'KeyringStore', 'Layer', 'MissingCredentialError', 'Provenance', 'Resolved', 'Resolver', 'Sensitivity', 'UnsupportedAuthDeclarationError', 'UnsupportedInstanceDeclarationError', 'VaultDoctorTool', 'VaultSetTool', 'as_secret', 'atomic_write', 'bind', 'declare_instance', 'doctor_data', 'get', 'groups_from_provider', 'list_instances', 'load_catalog', 'redact', 'resolver', 'rotate_secret', 'run_setup'] module-attribute

Layer = Literal['env', 'file', 'keyring', 'default', 'prompt']

Provenance = dict[str, dict[str, str | bool]]

AuthDependencySpec

Bases: BaseModel

login_command instance-attribute

status()

AuthSource

Bases: Protocol

status()

AuthStatus

Bases: StrEnum

Catalog

Bases: BaseModel

all_specs()

auth_dependencies()

for_package(package)

group(gid)

Raises:

Type	Description
KeyError	if no group with that id is registered.

groups()

rejections()

CatalogRejection

Bases: BaseModel

CredentialGroup

Bases: BaseModel

spec(name)

Raises:

Type	Description
KeyError	if no spec with that name exists in the group.

CredentialSpec

Bases: BaseModel

InstanceSource

Bases: Protocol

declare(instance)

list_instances()

KeyringStore

delete(group, name, instance=None)

get(group, name, instance=None)

set(group, name, value, instance=None)

username(group, name, instance=None) staticmethod

MissingCredentialError

Bases: Exception

Resolved

Bases: BaseModel

Resolver

keyring_available()

probe(layer, spec, group, instance=None)

resolve(group, name, instance=None)

Sensitivity

Bases: StrEnum

UnsupportedAuthDeclarationError

Bases: RuntimeError

UnsupportedInstanceDeclarationError

Bases: RuntimeError

VaultDoctorTool

name property

execute(*, package=None, instance=None)

VaultSetTool

name property

execute(*, group, name, value, instance=None)

as_secret(value)

atomic_write(path, data, *, encoding='utf-8')

bind(model, group, instance=None)

declare_instance(group, instance)

doctor_data(package=None, *, catalog=None, instance=None)

Parameters:

Name	Type	Description	Default
package	str | None	When given, restrict the report to credential groups contributed by that package; otherwise cover the whole catalog.	None
catalog	Catalog | None	Catalog to inspect; defaults to the discovered :func:~axm_vault.catalog.load_catalog result.	None
instance	str | None	Optional multi-instance identity. When given, it takes precedence over instance discovery.	None

Returns:

Name	Type	Description
A	Provenance	data:Provenance mapping canonical keyring usernames to
	Provenance	{layer, present}, with an instance segment for multi-instance groups.
	Provenance	layer is the first probed layer to supply the credential, or
	Provenance	"missing" when none does; present mirrors that. The value
	Provenance	itself is NEVER included (security invariant).

get(group, name, instance=None)

groups_from_provider(entry_point, provider)

list_instances(group)

load_catalog() cached

redact(text, *secrets)

rotate_secret(group, name, value, instance=None)

Raises:

Type	Description
ValueError	if name already ends with the reserved .prev suffix — that namespace is owned by the rotation backup slot and must not collide with a real spec name or instance.
KeyringUnavailableError	when the OS keyring backend is unavailable.

run_setup(only=None)

Parameters:

Name	Type	Description	Default
only	str | None	When given, restrict setup to the single group.name (or a bare name) matching this string; otherwise cover every spec.	None

Resolver singleton

The root export resolver is a preconstructed, non-interactive Resolver(). Use its resolve and probe methods as described in Resolver. It is a runtime instance, rather than another class or factory.

Module-level surfaces

The installed tools include VaultDeleteTool, although it is not a root export. KeyringUnavailableError likewise requires its module path. They are listed separately rather than implied root imports. groups_from_provider is a root export, documented above.

VaultDeleteTool

name property

execute(*, group='', name='', instance=None)

KeyringUnavailableError

Bases: RuntimeError