API reference¶
Generated reference documentation for each package. The pages are rebuilt and published with this
site from main.
| Language | Reference | Generated by |
|---|---|---|
| TypeScript | TypeScript API | TypeDoc |
| Rust | Rust API · docs.rs | rustdoc |
| Go | pkg.go.dev | Go doc comments |
| Python | below | mkdocstrings |
| Java | Java API | Javadoc |
Build them locally with make docs (per language: make -C <lang> docs).
Python¶
Grow Codes SDK for OpenBao.
from grow_openbao import OpenBaoClient, OpenBaoConfig client = OpenBaoClient.from_env() # doctest: +SKIP
Modules hang off the client: client.auth, client.sys, client.wrapping,
client.leases, client.kv(), client.transit(), client.database(),
client.pki() and client.secrets() (the SecretsProvider). Server lifecycle helpers
(init/unseal) live in :mod:grow_openbao.testing.lifecycle.
DEFAULT_KV_MOUNT
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
DEFAULT_URL
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
DEFAULT_VALUE_FIELD
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
ENV_PREFIX
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
LOGGER_NAME
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
REDACTED
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
REQUEST_ID_HEADERS
module-attribute
¶
REQUEST_ID_HEADERS = ('x-request-id', 'x-amzn-requestid', 'x-amz-request-id', 'x-datadog-request-id', 'request-id', 'x-correlation-id')
Built-in immutable sequence.
If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.
If the argument is a tuple, the return value is the same object.
RETRY_AFTER_HEADERS
module-attribute
¶
Built-in immutable sequence.
If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.
If the argument is a tuple, the return value is the same object.
SDK_NAME
module-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
VENDOR_ENV
module-attribute
¶
VENDOR_ENV = {'URL': ('BAO_ADDR', 'VAULT_ADDR'), 'TOKEN': ('BAO_TOKEN', 'VAULT_TOKEN'), 'NAMESPACE': ('BAO_NAMESPACE', 'VAULT_NAMESPACE'), 'CA_CERT': ('BAO_CACERT', 'VAULT_CACERT'), 'CLIENT_CERT': ('BAO_CLIENT_CERT', 'VAULT_CLIENT_CERT'), 'CLIENT_KEY': ('BAO_CLIENT_KEY', 'VAULT_CLIENT_KEY'), 'INSECURE_SKIP_VERIFY': ('BAO_SKIP_VERIFY', 'VAULT_SKIP_VERIFY')}
dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)
AppRoleAuth ¶
Bases: grow_openbao.auth.AuthMethod
AppRole login: POST auth/<mount>/login {role_id, secret_id}.
secret_id may be omitted for roles with bind_secret_id=false.
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
AsyncAuth ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Auth: async_client.auth.
create_token ¶
create_token(*, policies: Sequence[str] | None = None, ttl_s: Duration | None = None, explicit_max_ttl_s: Duration | None = None, renewable: bool | None = None, display_name: str | None = None, meta: Mapping[str, str] | None = None, num_uses: int | None = None, no_parent: bool | None = None, no_default_policy: bool | None = None, period_s: Duration | None = None, role: str | None = None) -> AuthInfo
See :meth:Auth.create_token.
login ¶
login(method: AuthMethod, *, set_token: bool = True, auto_renew: bool | Mapping[str, Any] = False) -> AuthInfo
See :meth:Auth.login.
start_renewer ¶
See :meth:Auth.start_renewer (call from a running event loop).
AsyncBaseSecretsProvider ¶
Bases: abc.ABC
Async counterpart of :class:BaseSecretsProvider (async primitives).
After :meth:aclose every call raises :class:CancelledError ("client is closed").
aclose ¶
Stop every watcher started by this provider; later calls raise CANCELLED (idempotent).
ensure_open ¶
Raise :class:CancelledError ("aclose.
Service methods that do not go through the base operations can call it first.
load_env ¶
load_env(source: str | Mapping[str, str], *, override: bool = False, prefix: str = '', environ: MutableMapping[str, str] | None = None) -> dict[str, str]
See :meth:BaseSecretsProvider.load_env.
watch ¶
watch(name: str, interval_s: float | timedelta, on_change: Callable, *, on_error: Callable | None = None, version: str | None = None, path: str | None = None) -> AsyncWatchHandle
Start an asyncio task polling name (call from a running event loop).
AsyncDatabase ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Database.
configure_connection ¶
configure_connection(name: str, *, plugin_name: str, connection_url: str, username: str | None = None, password: str | Secret | None = None, allowed_roles: Sequence[str] | None = None, verify_connection: bool | None = None, extra: Mapping[str, Any] | None = None) -> None
Create or replace a connection (POST <mount>/config/<name>, verified by default).
connection_url uses {{username}}/{{password}} templates; extra holds
plugin-specific fields sent as is (snake_case).
create_role ¶
create_role(name: str, *, db_name: str, creation_statements: Sequence[str], revocation_statements: Sequence[str] | None = None, renew_statements: Sequence[str] | None = None, rollback_statements: Sequence[str] | None = None, default_ttl_s: Duration | None = None, max_ttl_s: Duration | None = None) -> None
Create or replace a dynamic role (POST <mount>/roles/<name>).
Statements use {{name}}, {{password}} and {{expiration}}.
get_credentials ¶
Generate credentials for a role (GET <mount>/creds/<role>).
Keep them alive with client.leases.manage(lease, on_expire=...). Unknown roles raise
:class:ValidationError. Never retried (every call creates new credentials).
read_connection ¶
Read a connection (without its password); :class:NotFoundError when missing.
AsyncHttpTransport ¶
Asynchronous transport (one per async client); options as for :class:HttpTransport.
Cancelling the calling task raises :class:CancelledError (an asyncio.CancelledError
subclass) so asyncio's cancellation machinery keeps working. Every call after
:meth:aclose raises :class:CancelledError ("client is closed").
AsyncKvMount ¶
Bases: grow_openbao._api.AsyncModule, grow_openbao.kv._KvBase
Async :class:KvMount.
delete_versions ¶
Soft-delete versions (KV v2 only).
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
after/limit paginate.
patch ¶
Merge keys into the latest version (RFC 7386: a None value removes the key).
read ¶
Read the latest (or a given) version; :class:NotFoundError when missing, deleted or
destroyed.
write ¶
Write a new version (cas: the current version must equal it, 0 = create only).
A CAS mismatch raises :class:ConflictError.
write_metadata ¶
write_metadata(path: str, *, max_versions: int | None = None, cas_required: bool | None = None, delete_version_after_s: Duration | None = None, custom_metadata: Mapping[str, str] | None = None) -> None
Update metadata settings (KV v2 only).
AsyncKvV1 ¶
Bases: grow_openbao._api.AsyncModule, grow_openbao.kv._KvBase
Async :class:KvV1.
version
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
delete_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): deleteMetadata.
delete_versions ¶
Not supported by KV version 1 (:class:UnsupportedError): deleteVersions.
destroy ¶
Not supported by KV version 1 (:class:UnsupportedError): destroy.
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
patch ¶
Not supported by KV version 1 (:class:UnsupportedError): patch.
read ¶
Read a secret; :class:NotFoundError when missing (version is v2 only).
read_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): readMetadata.
undelete ¶
Not supported by KV version 1 (:class:UnsupportedError): undelete.
write ¶
Write (replace) a secret; returns None on KV v1 (cas is v2 only).
write_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): writeMetadata.
AsyncKvV2 ¶
Bases: grow_openbao._api.AsyncModule, grow_openbao.kv._KvBase
Async :class:KvV2.
version
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
delete_metadata ¶
Delete the secret with all versions and metadata.
delete_versions ¶
Soft-delete the given versions.
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
after/limit paginate.
patch ¶
Merge keys into the latest version (RFC 7386: a None value removes the key).
read ¶
Read the latest (or a given) version; :class:NotFoundError when missing, deleted or
destroyed.
read_metadata ¶
Metadata of all versions; :class:NotFoundError when missing.
write ¶
Write a new version (cas: the current version must equal it, 0 = create only).
A CAS mismatch raises :class:ConflictError.
write_metadata ¶
write_metadata(path: str, *, max_versions: int | None = None, cas_required: bool | None = None, delete_version_after_s: Duration | None = None, custom_metadata: Mapping[str, str] | None = None) -> None
Update the metadata settings of a secret.
AsyncLeaseManager ¶
Bases: grow_openbao._api.AsyncModule
Async :class:LeaseManager: async_client.leases.
lookup ¶
Lease details (PUT sys/leases/lookup); unknown leases raise :class:ValidationError.
manage ¶
manage(lease: Lease[Any], *, increment_s: Duration | None = None, renew_fraction: float = 0.6666666666666666, min_delay_s: float = 0.5, on_renew: Callable[[LeaseRenewal], None] | None = None, on_error: Callable[[BaseException], None] | None = None, on_expire: Callable[[], None] | None = None, revoke_on_stop: bool = False, clock: Callable[[], float] | None = None, sleep: Callable[[float], Any] | None = None) -> AsyncManagedLease
See :meth:LeaseManager.manage (an asyncio task; call from a running loop).
renew ¶
Renew a lease (PUT sys/leases/renew).
A TTL beyond the maximum is capped (see warnings); unknown or revoked leases raise
:class:ValidationError.
revoke_prefix ¶
Revoke every lease under a prefix (PUT sys/leases/revoke-prefix/<prefix>).
stop_all ¶
Stop every managed lease (revoking those with revoke_on_stop). Idempotent.
AsyncManagedLease ¶
Handle of a lease kept alive by :meth:AsyncLeaseManager.manage.
AsyncOpenBaoClient ¶
Bases: grow_openbao.client._ClientBase
Asynchronous OpenBao client (same modules and methods, awaitable); use async with
or call :meth:aclose.
Cancel a call by cancelling its task: the SDK raises :class:CancelledError, which is also
an :class:asyncio.CancelledError.
aclose ¶
Stop renewers, managed leases and watchers, then close connections (idempotent).
close ¶
Stop renewers, managed leases and watchers, then close connections (idempotent).
database ¶
Database engine (default mount database).
from_env
classmethod
¶
Build a client from GROW_OPENBAO_* and BAO_*/VAULT_* variables.
request ¶
request(method: Literal, path: str, *, params: Mapping[str, Any] | None = None, json: Any = None, headers: Mapping[str, str] | None = None, list: bool = False, wrap_ttl_s: float | timedelta | None = None, idempotent: bool | None = None) -> RawResponse
See :meth:OpenBaoClient.request.
secrets ¶
secrets(mount: str | None = None, *, path: str | None = None, value_field: str | None = None) -> AsyncOpenBaoSecretsProvider
See :meth:OpenBaoClient.secrets.
AsyncOpenBaoSecretsProvider ¶
Bases: grow_openbao._secrets.base.AsyncBaseSecretsProvider
Async :class:OpenBaoSecretsProvider: async_client.secrets().
capabilities
class-attribute
¶
Build an immutable unordered collection of unique elements.
full_path ¶
The KV path of a secret: <path or provider path>/<name>.
get_all ¶
Every secret directly under path (non-recursive), keyed by name.
set ¶
set(name: str, value: Any, *, path: str | None = None, cas: int | None = None, tags: Mapping[str, str] | None = None, description: str | None = None) -> str
See :meth:OpenBaoSecretsProvider.set.
AsyncPki ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Pki.
issue_certificate ¶
issue_certificate(role: str, common_name: str, *, alt_names: Sequence[str] | None = None, ip_sans: Sequence[str] | None = None, uri_sans: Sequence[str] | None = None, ttl_s: Duration | None = None, format: Literal[pem, der, pem_bundle] | None = None, private_key_format: Literal[der, pkcs8] | None = None, exclude_cn_from_sans: bool | None = None) -> IssuedCertificate
Issue a certificate and private key for a role (POST <mount>/issue/<role>).
A common name the role does not allow raises :class:ValidationError.
list_certificates ¶
Serials of all stored certificates; [] when there is none.
read_certificate ¶
A certificate by serial; :class:NotFoundError when unknown.
revoke_certificate ¶
Revoke a certificate by serial (aa:bb:...); unknown serials raise
:class:ValidationError.
sign_csr ¶
sign_csr(role: str, csr: str, *, common_name: str | None = None, alt_names: Sequence[str] | None = None, ip_sans: Sequence[str] | None = None, uri_sans: Sequence[str] | None = None, ttl_s: Duration | None = None, format: Literal[pem, der, pem_bundle] | None = None, exclude_cn_from_sans: bool | None = None) -> SignedCertificate
Sign a PEM CSR for a role (POST <mount>/sign/<role>).
tidy ¶
tidy(*, tidy_cert_store: bool = True, tidy_revoked_certs: bool = True, safety_buffer_s: Duration | None = None, wait: bool = True, timeout_s: Duration = 60.0, interval_s: Duration = 0.5) -> TidyStatus
Start a tidy run (POST <mount>/tidy, 202).
Unless wait=False, poll tidy-status until it is Finished, Error or
Cancelled (:class:TimeoutError after timeout_s). Returns the last status.
AsyncSecretCache ¶
Bases: grow_openbao._secrets.base.AsyncBaseSecretsProvider
Async :class:SecretCache; background refreshes run as asyncio tasks.
wait_refreshes ¶
Wait for background refreshes currently running (useful in tests).
watch ¶
watch(name: str, interval_s: float | timedelta, on_change: Callable, *, on_error: Callable | None = None, version: str | None = None, path: str | None = None) -> AsyncWatchHandle
Watches the underlying provider directly (bypasses the cache).
AsyncSecretsProvider ¶
Bases: typing.Protocol
Asynchronous secrets interface (same methods, awaitable).
AsyncSys ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Sys: async_client.sys.
create_app_role ¶
create_app_role(name: str, *, mount: str = 'approle', token_policies: Sequence[str] | None = None, token_ttl_s: Duration | None = None, token_max_ttl_s: Duration | None = None, secret_id_ttl_s: Duration | None = None, secret_id_num_uses: int | None = None, bind_secret_id: bool | None = None, token_type: str | None = None) -> None
Create or update an AppRole role (POST auth/<mount>/role/<name>).
delete_app_role ¶
Delete an AppRole role.
disable_auth_method ¶
Disable an auth method; its tokens are revoked.
disable_secrets_engine ¶
Disable (unmount) a secrets engine; its data is deleted.
enable_auth_method ¶
enable_auth_method(path: str, type: str, *, description: str | None = None, default_lease_ttl_s: Duration | None = None, max_lease_ttl_s: Duration | None = None, local: bool | None = None) -> None
Enable an auth method at path.
enable_secrets_engine ¶
enable_secrets_engine(path: str, type: str, *, description: str | None = None, options: Mapping[str, str] | None = None, default_lease_ttl_s: Duration | None = None, max_lease_ttl_s: Duration | None = None, local: bool | None = None, seal_wrap: bool | None = None) -> None
Enable a secrets engine at path (e.g. type="kv", options={"version": "2"}).
A used path raises :class:ValidationError.
generate_secret_id ¶
generate_secret_id(name: str, *, mount: str = 'approle', metadata: Mapping[str, str] | None = None, cidr_list: Sequence[str] | None = None, ttl_s: Duration | None = None, num_uses: int | None = None) -> SecretIdInfo
Generate a new secret id for an AppRole role.
health ¶
GET sys/health (unauthenticated); sealed, standby and uninitialised nodes are no
error.
list_app_roles ¶
AppRole role names; [] when there is none.
list_auth_methods ¶
Auth methods by path ("approle/" → info).
read_policy ¶
Read an ACL policy; :class:NotFoundError when missing.
read_role_id ¶
The role id of an AppRole role; :class:NotFoundError for unknown roles.
write_policy ¶
Create or replace an ACL policy (PUT sys/policies/acl/<name>); invalid HCL raises
:class:ValidationError.
AsyncTokenRenewer ¶
AsyncTransit ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Transit: async_client.transit().
create_key ¶
create_key(name: str, type: str = 'aes256-gcm96', *, exportable: bool | None = None, derived: bool | None = None, auto_rotate_period_s: Duration | None = None, allow_plaintext_backup: bool | None = None, key_size: int | None = None) -> TransitKey
Create a key (idempotent: an existing key is returned unchanged).
Types: aes128-gcm96, aes256-gcm96 (default), chacha20-poly1305, ed25519,
ecdsa-p256/-p384/-p521, rsa-2048/-3072/-4096, hmac …
decrypt ¶
decrypt(name: str, ciphertext: str, *, context: TransitInput | None = None, associated_data: TransitInput | None = None) -> bytes
Decrypt a vault:v<n>: ciphertext; returns the plaintext bytes.
decrypt_batch ¶
Decrypt many items in one request; see :meth:Transit.encrypt_batch for errors.
delete_key ¶
Delete a key (needs deletion_allowed=True, else :class:ValidationError).
encrypt ¶
encrypt(name: str, plaintext: TransitInput, *, context: TransitInput | None = None, key_version: int | None = None, associated_data: TransitInput | None = None) -> Ciphertext
Encrypt plaintext (text is UTF-8 encoded).
encrypt_batch ¶
Encrypt many items in one request.
Results are in input order; a failed item has error set (the call itself fails only
when the whole request fails).
generate_data_key ¶
generate_data_key(name: str, *, plaintext: bool = True, bits: Literal[128, 256, 512] = 256, context: TransitInput | None = None) -> DataKey
Generate a data key encrypted with the transit key (plus its plaintext by default).
hash ¶
hash(input: TransitInput, *, algorithm: str | None = None, format: Literal[hex, base64] | None = None) -> str
Hash of input (default sha2-256, hex).
hmac ¶
hmac(name: str, input: TransitInput, *, algorithm: str | None = None, key_version: int | None = None) -> str
HMAC of input (vault:v<n>:<base64>).
list_keys ¶
Key names (sorted); [] when there is none.
random_bytes ¶
bytes random bytes from the server, encoded as base64 (default) or hex.
rewrap ¶
rewrap(name: str, ciphertext: str, *, context: TransitInput | None = None, key_version: int | None = None) -> Ciphertext
Re-encrypt a ciphertext with the latest (or given) key version without revealing it.
sign ¶
sign(name: str, input: TransitInput, *, hash_algorithm: str | None = None, signature_algorithm: Literal[pss, pkcs1v15] | None = None, prehashed: bool | None = None, key_version: int | None = None, context: TransitInput | None = None) -> Signature
Sign input with an asymmetric key (symmetric keys raise :class:ValidationError).
update_key_config ¶
update_key_config(name: str, *, deletion_allowed: bool | None = None, min_decryption_version: int | None = None, min_encryption_version: int | None = None, exportable: bool | None = None, allow_plaintext_backup: bool | None = None, auto_rotate_period_s: Duration | None = None) -> TransitKey
Update key settings; returns the updated key.
verify ¶
verify(name: str, input: TransitInput, *, signature: str | None = None, hmac: str | None = None, hash_algorithm: str | None = None, signature_algorithm: Literal[pss, pkcs1v15] | None = None, prehashed: bool | None = None, context: TransitInput | None = None) -> bool
Verify a signature or an hmac (exactly one); False when invalid.
AsyncWatchHandle ¶
AsyncWrapping ¶
Bases: grow_openbao._api.AsyncModule
Async :class:Wrapping.
lookup_wrapping ¶
Properties of a wrapping token without using it (POST sys/wrapping/lookup).
unwrap ¶
Unwrap a token (POST sys/wrapping/unwrap authenticated with the token itself).
A used or invalid token raises :class:ValidationError; never retried.
wrap ¶
Wrap data in a single-use token valid for ttl_s (POST sys/wrapping/wrap).
Auth ¶
Bases: grow_openbao._api.SyncModule
Logins, token self-service and token renewal: client.auth.
create_token ¶
create_token(*, policies: Sequence[str] | None = None, ttl_s: Duration | None = None, explicit_max_ttl_s: Duration | None = None, renewable: bool | None = None, display_name: str | None = None, meta: Mapping[str, str] | None = None, num_uses: int | None = None, no_parent: bool | None = None, no_default_policy: bool | None = None, period_s: Duration | None = None, role: str | None = None) -> AuthInfo
Create a child (or orphan, no_parent=True) token: POST auth/token/create.
login ¶
login(method: AuthMethod, *, set_token: bool = True, auto_renew: bool | Mapping[str, Any] = False) -> AuthInfo
Log in with an auth method and (by default) use the new token for this client.
Failed logins raise :class:AuthenticationError. auto_renew=True (or a mapping of
:meth:start_renewer keyword arguments) starts a :class:TokenRenewer that logs in
again with the same method when the token can no longer be renewed.
lookup_self ¶
Properties of the client token: GET auth/token/lookup-self.
renew_self ¶
Renew the client token (POST auth/token/renew-self).
increment_s requests a TTL; the granted TTL is lease_duration_s (capped by the
maximum TTL). Non-renewable tokens raise :class:ValidationError.
revoke_self ¶
Revoke the client token (POST auth/token/revoke-self) and forget it.
start_renewer ¶
Start a :class:TokenRenewer for the current token (TTL from lookup_self()).
Keyword arguments: reauth, increment_s, renew_fraction, min_delay_s,
on_renew, on_error, on_expire. Stopped by client.close().
AuthInfo ¶
Result of a login or token creation. The token and accessor are :class:Secret.
AuthMethod ¶
Bases: abc.ABC
An auth method usable with client.auth.login(method).
Implement :meth:login_operation to add a method (use :func:login_post).
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
login_operation ¶
The login as an SDK operation (a generator of requests).
AuthenticationError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Credentials missing or rejected (HTTP 401).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
BaseConfig ¶
Common, immutable client settings. Durations are float seconds (timedelta accepted).
Service configs subclass this (@dataclass(frozen=True, repr=False)), override url
with the service default, add their own fields (Secret for credentials), extend
:meth:_env_values and :meth:validate, and list vendor variables in ENV_VENDOR.
ENV_VENDOR
class-attribute
¶
dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)
connect_timeout
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
request_timeout
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
total_timeout
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
url
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
from_env
classmethod
¶
Build from the environment, then validate.
Precedence: explicit keyword > GROW_OPENBAO_<NAME> > vendor variables >
default. env defaults to os.environ; pass a dict in tests.
known_secrets ¶
Revealed values of every :class:Secret field (used to redact error text).
BaseSecretsProvider ¶
Bases: abc.ABC
Implements :class:SecretsProvider on top of five primitives a service provides.
Primitives (opts are the option dataclasses):
_fetch_secret(name, GetOptions) -> SecretValue | None(None when missing)_list_secrets(path) -> list[SecretMetadata](secrets directly underpath)_put_secret(name, data: bytes, SetOptions) -> str(new version or"")_remove_secret(name, DeleteOptions) -> None(raise :class:NotFoundErrorif missing)_fetch_metadata(name, GetOptions) -> SecretMetadata | None
Watchers started with :meth:watch are stopped by :meth:close and, when owner is
given (the client's registry), by client.close(). After :meth:close every call
raises :class:CancelledError ("
close ¶
Stop every watcher started by this provider; later calls raise CANCELLED (idempotent).
delete ¶
delete(name: str, *, path: str | None = None, versions: Sequence[str] | None = None, permanent: bool = False) -> None
Delete a secret; :class:NotFoundError when it does not exist.
ensure_open ¶
Raise :class:CancelledError ("close.
Service methods that do not go through the base operations can call it first.
get ¶
The secret, or None when it does not exist.
get_all ¶
Every secret directly under path (non-recursive), keyed by name.
get_bool ¶
true/false/1/0/yes/no/on/off, None when missing; else ValidationError.
get_json ¶
Decoded JSON, None when missing; :class:ValidationError when not JSON.
get_many ¶
get_many(names: Sequence[str], *, version: str | None = None, path: str | None = None) -> dict[str, SecretValue]
Values in request order; missing names are omitted.
get_number ¶
int or float, None when missing; :class:ValidationError otherwise.
list ¶
Metadata of the secrets under prefix, sorted by name.
load_env ¶
load_env(source: str | Mapping[str, str], *, override: bool = False, prefix: str = '', environ: MutableMapping[str, str] | None = None) -> dict[str, str]
Export secrets to environment variables; returns {env_name: secret_name}.
source is a path (one variable per secret directly under it, named from the secret
name relative to the path, upper-cased, non [A-Z0-9_] → _, plus prefix) or a
mapping {env_name: secret_name} (a missing secret raises :class:NotFoundError
before anything is set). Existing variables are kept unless override. environ
defaults to :data:os.environ.
require ¶
The secret; :class:NotFoundError when missing.
set ¶
set(name: str, value: Any, *, path: str | None = None, cas: int | None = None, tags: Mapping[str, str] | None = None, description: str | None = None) -> str
Store value (str, bytes, or JSON-encoded object); returns the new version.
watch ¶
watch(name: str, interval_s: float | timedelta, on_change: Callable, *, on_error: Callable | None = None, version: str | None = None, path: str | None = None) -> WatchHandle
Poll name every interval_s and call on_change(new, old) on change.
CacheStats ¶
CacheStats(hits: 'int', misses: 'int', evictions: 'int', refreshes: 'int', size: 'int')
CancelToken ¶
Thread-safe cancellation flag passed to sync calls as cancel=.
Cancelling interrupts an in-flight request (the call returns immediately with
:class:CancelledError; the abandoned HTTP exchange finishes in the background) and any
retry backoff sleep.
CancelledError ¶
Bases: grow_openbao._core.errors.OpenBaoError, asyncio.exceptions.CancelledError
The caller cancelled the operation (task cancel, :class:CancelToken, client close).
Also an :class:asyncio.CancelledError so asyncio keeps treating the task as cancelled.
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
CertificateInfo ¶
Result of :meth:Pki.read_certificate.
Ciphertext ¶
Ciphertext vault:v<n>:<base64> and the key version that produced it.
ConfigError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Invalid or missing configuration.
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
ConflictError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Conflict or failed precondition (HTTP 409, 412, CAS mismatch).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
ConnectionInfo ¶
A connection as returned by :meth:Database.read_connection (never the password).
DataKey ¶
A data key: ciphertext decrypts (with the transit key) to plaintext.
Database ¶
Bases: grow_openbao._api.SyncModule
Database engine on one mount: client.database(mount="database").
configure_connection ¶
configure_connection(name: str, *, plugin_name: str, connection_url: str, username: str | None = None, password: str | Secret | None = None, allowed_roles: Sequence[str] | None = None, verify_connection: bool | None = None, extra: Mapping[str, Any] | None = None) -> None
Create or replace a connection (POST <mount>/config/<name>, verified by default).
connection_url uses {{username}}/{{password}} templates; extra holds
plugin-specific fields sent as is (snake_case).
create_role ¶
create_role(name: str, *, db_name: str, creation_statements: Sequence[str], revocation_statements: Sequence[str] | None = None, renew_statements: Sequence[str] | None = None, rollback_statements: Sequence[str] | None = None, default_ttl_s: Duration | None = None, max_ttl_s: Duration | None = None) -> None
Create or replace a dynamic role (POST <mount>/roles/<name>).
Statements use {{name}}, {{password}} and {{expiration}}.
get_credentials ¶
Generate credentials for a role (GET <mount>/creds/<role>).
Keep them alive with client.leases.manage(lease, on_expire=...). Unknown roles raise
:class:ValidationError. Never retried (every call creates new credentials).
read_connection ¶
Read a connection (without its password); :class:NotFoundError when missing.
DatabaseCredentials ¶
Dynamic database credentials (the password is a :class:Secret).
DecryptBatchItem ¶
One item of :meth:Transit.decrypt_batch.
DecryptBatchResult ¶
Result of one batch item; error is set when this item failed.
DeleteOptions ¶
DeleteOptions(path: 'str | None' = None, versions: 'Sequence[str] | None' = None, permanent: 'bool' = False)
permanent
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
EncryptBatchItem ¶
One item of :meth:Transit.encrypt_batch.
EncryptBatchResult ¶
Result of one batch item; error is set when this item failed.
EnvReader ¶
Reads GROW_<KEY_UPPER>_<NAME> and vendor variables from an injectable mapping.
Every getter returns None when no variable is set (empty strings count as unset). A
present but invalid value raises :class:ConfigError that names the variable, never its
value.
ErrorCode ¶
Bases: builtins.str, enum.Enum
Canonical error codes; the value is the wire form used by the conformance suite.
AUTHENTICATION
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
CANCELLED
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
CONFIG
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
CONFLICT
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
NOT_FOUND
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
PERMISSION_DENIED
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
RATE_LIMITED
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
TIMEOUT
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
UNAVAILABLE
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
UNSUPPORTED
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
VALIDATION
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
ErrorInfo ¶
Passed to Hooks.on_error; error is the (redacted) SDK error.
GetOptions ¶
GetOptions(version: 'str | None' = None, path: 'str | None' = None)
HealthResponse ¶
Raw sys/health answer (sealed/standby/uninitialised nodes are no error).
HealthStatus ¶
Result of health(); status is ok/degraded/unhealthy/unreachable or a vendor word.
Hooks ¶
Optional callbacks invoked on every attempt. Exceptions raised by hooks are ignored.
HttpTransport ¶
Synchronous transport (one per client).
Service options (all optional):
request_id_headers: vendor request id headers, checked before :data:REQUEST_ID_HEADERS.retry_after_headers: headers read (in order) for the delay a 429/503 response asks for; default("retry-after",), e.g.("retry-after", "x-ratelimit-reset"). See :func:retry_after_from_headers.error_mapper:mapper(error, response)returns a service-specific error for an HTTP error response (orNoneto keep the default). The mapped error is whatHooks.on_error, the retry planner (retry_after) and the caller see; whether a status is retried stays the SPEC rule. Exceptions raised by the mapper are logged and ignored.
Every call after :meth:close raises :class:CancelledError ("client is closed").
IssuedCertificate ¶
Bases: grow_openbao.pki.SignedCertificate
An issued certificate with its private key (a :class:Secret).
private_key_type
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
JwtAuth ¶
Bases: grow_openbao.auth.AuthMethod
JWT/OIDC login with a JWT: POST auth/<mount>/login {role, jwt}.
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
KubernetesAuth ¶
Bases: grow_openbao.auth.AuthMethod
Kubernetes login: POST auth/<mount>/login {role, jwt} with the service account token.
The token is read from jwt_path at login time unless jwt is given.
DEFAULT_JWT_PATH
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
KvMetadata ¶
Metadata of a KV v2 secret (all versions).
KvMount ¶
Bases: grow_openbao._api.SyncModule, grow_openbao.kv._KvBase
A KV mount whose version is detected on first use (or taken from
config.kv_version); then delegates to the v1 or v2 behaviour. Version-only operations
raise :class:UnsupportedError on v1 mounts.
delete_versions ¶
Soft-delete versions (KV v2 only).
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
after/limit paginate.
patch ¶
Merge keys into the latest version (RFC 7386: a None value removes the key).
read ¶
Read the latest (or a given) version; :class:NotFoundError when missing, deleted or
destroyed.
write ¶
Write a new version (cas: the current version must equal it, 0 = create only).
A CAS mismatch raises :class:ConflictError.
write_metadata ¶
write_metadata(path: str, *, max_versions: int | None = None, cas_required: bool | None = None, delete_version_after_s: Duration | None = None, custom_metadata: Mapping[str, str] | None = None) -> None
Update metadata settings (KV v2 only).
KvSecret ¶
A KV secret: the key/value data and, on KV v2, the version metadata.
repr() hides the values.
KvV1 ¶
Bases: grow_openbao._api.SyncModule, grow_openbao.kv._KvBase
KV version 1 (unversioned) mount; version-only operations raise
:class:UnsupportedError.
version
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
delete_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): deleteMetadata.
delete_versions ¶
Not supported by KV version 1 (:class:UnsupportedError): deleteVersions.
destroy ¶
Not supported by KV version 1 (:class:UnsupportedError): destroy.
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
patch ¶
Not supported by KV version 1 (:class:UnsupportedError): patch.
read ¶
Read a secret; :class:NotFoundError when missing (version is v2 only).
read_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): readMetadata.
undelete ¶
Not supported by KV version 1 (:class:UnsupportedError): undelete.
write ¶
Write (replace) a secret; returns None on KV v1 (cas is v2 only).
write_metadata ¶
Not supported by KV version 1 (:class:UnsupportedError): writeMetadata.
KvV2 ¶
Bases: grow_openbao._api.SyncModule, grow_openbao.kv._KvBase
KV version 2 (versioned) mount.
version
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
delete_metadata ¶
Delete the secret with all versions and metadata.
delete_versions ¶
Soft-delete the given versions.
list ¶
Keys directly under a folder (sub-folders end in /); [] when there is none.
after/limit paginate.
patch ¶
Merge keys into the latest version (RFC 7386: a None value removes the key).
read ¶
Read the latest (or a given) version; :class:NotFoundError when missing, deleted or
destroyed.
read_metadata ¶
Metadata of all versions; :class:NotFoundError when missing.
write ¶
Write a new version (cas: the current version must equal it, 0 = create only).
A CAS mismatch raises :class:ConflictError.
write_metadata ¶
write_metadata(path: str, *, max_versions: int | None = None, cas_required: bool | None = None, delete_version_after_s: Duration | None = None, custom_metadata: Mapping[str, str] | None = None) -> None
Update the metadata settings of a secret.
KvVersionMetadata ¶
Metadata of one KV v2 version.
LeaderStatus ¶
sys/leader.
Lease ¶
Bases: typing.Generic
A lease on a dynamic secret (e.g. database credentials).
LeaseInfo ¶
Result of :meth:LeaseManager.lookup.
LeaseManager ¶
Bases: grow_openbao._api.SyncModule
Lease operations and automatic renewal: client.leases.
lookup ¶
Lease details (PUT sys/leases/lookup); unknown leases raise :class:ValidationError.
manage ¶
manage(lease: Lease[Any], *, increment_s: Duration | None = None, renew_fraction: float = 0.6666666666666666, min_delay_s: float = 0.5, on_renew: Callable[[LeaseRenewal], None] | None = None, on_error: Callable[[BaseException], None] | None = None, on_expire: Callable[[], None] | None = None, revoke_on_stop: bool = False, clock: Callable[[], float] | None = None, wait: Callable[[float], bool] | None = None, background: bool = True) -> ManagedLease
Keep a lease alive in a background thread.
Renews at 2/3 of its TTL until the maximum TTL is reached, then calls on_expire once
when it expires. Stopped by the handle, :meth:stop_all or client.close().
renew ¶
Renew a lease (PUT sys/leases/renew).
A TTL beyond the maximum is capped (see warnings); unknown or revoked leases raise
:class:ValidationError.
revoke_prefix ¶
Revoke every lease under a prefix (PUT sys/leases/revoke-prefix/<prefix>).
stop_all ¶
Stop every managed lease (revoking those with revoke_on_stop). Idempotent.
LeaseRenewal ¶
Result of :meth:LeaseManager.renew.
LeaseState ¶
Remaining lifetime of a token or lease.
LoggerLike ¶
Bases: typing.Protocol
Structured logger interface accepted in configuration (SPEC Logger).
ManagedLease ¶
Handle of a lease kept alive by :meth:LeaseManager.manage.
MountInfo ¶
A secrets engine or auth method mount.
NotFoundError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Missing record (HTTP 404).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
OpenBaoClient ¶
Bases: grow_openbao.client._ClientBase
Synchronous OpenBao client. Thread-safe; use as a context manager or call
:meth:close.
Service modules: :attr:auth, :attr:sys, :attr:wrapping, :attr:leases,
:meth:kv, :meth:kv_v1, :meth:kv_v2, :meth:transit, :meth:database, :meth:pki
and :meth:secrets (the SecretsProvider). Cancel calls from another thread with
with client.cancellable(token): ... or the cancel= argument of the core methods.
cancellable ¶
Apply token to every call made by this thread inside the with block.
close ¶
Stop token renewers, managed leases and secret watchers, then release connections (idempotent).
from_env
classmethod
¶
Build a client from GROW_OPENBAO_* and BAO_*/VAULT_* variables.
health ¶
Unauthenticated health (GET /v1/sys/health); never raises for an unhealthy or
unreachable server.
healthy is true only for an active, unsealed node; status is active,
standby, perfstandby, sealed or uninitialized (unreachable on any
error). details holds version, initialized, sealed, standby and
clusterName (when set); on errors error (and httpStatus). Raises only
:class:CancelledError and :class:ConfigError.
kv ¶
KV mount with auto-detected version (default config.kv_mount); cached per mount.
ping ¶
Authenticated round trip (GET auth/token/lookup-self); latency in ms.
A missing, invalid or revoked token raises :class:AuthenticationError.
request ¶
request(method: Literal, path: str, *, params: Mapping[str, Any] | None = None, json: Any = None, headers: Mapping[str, str] | None = None, list: bool = False, wrap_ttl_s: float | timedelta | None = None, idempotent: bool | None = None) -> RawResponse
Call any OpenBao API path (/v1/<path>) with the client token, namespace,
retries and error mapping (for endpoints this SDK has no method for).
secrets ¶
secrets(mount: str | None = None, *, path: str | None = None, value_field: str | None = None) -> OpenBaoSecretsProvider
:class:SecretsProvider over a KV mount (default config.kv_mount) and base path
(default config.secrets_path); close() stops its watchers.
server_version ¶
Server version from sys/health (e.g. 2.7.2).
OpenBaoConfig ¶
Bases: grow_openbao._core.config.BaseConfig
Immutable settings for :class:~grow_openbao.OpenBaoClient.
Common fields (url, timeouts, retry, tls, proxy, headers,
user_agent_suffix, hooks, logger) come from :class:BaseConfig. Durations are
float seconds; datetime.timedelta is accepted. token accepts a str and is stored
as a :class:Secret; repr() never shows it.
Service fields:
token— client token sent asX-Vault-Token. Leave it unset when the client logs in with an auth method (client.auth.login(...)).namespace— sent asX-Vault-Namespace.kv_mount— default KV mount ofclient.kv()/client.secrets()("secret").kv_version—1or2to skip KV version auto-detection (sys/internal/ui/mounts) for tokens that cannot read it;None= auto-detect.secrets_path— base path inside the KV mount ofclient.secrets()(""= root).value_field— KV data field that holds aclient.secrets()value ("value").
Environment (from_env): GROW_OPENBAO_<NAME> first, then the vendor variables of
:data:VENDOR_ENV (BAO_* then VAULT_*). Names: URL, TOKEN, NAMESPACE,
CONNECT_TIMEOUT, REQUEST_TIMEOUT, TOTAL_TIMEOUT, MAX_RETRIES, CA_CERT,
CLIENT_CERT, CLIENT_KEY, INSECURE_SKIP_VERIFY, PROXY, KV_MOUNT,
KV_VERSION (1, 2; 0 = auto-detect) and SECRETS_PATH.
ENV_VENDOR
class-attribute
¶
ENV_VENDOR = {'URL': ('BAO_ADDR', 'VAULT_ADDR'), 'TOKEN': ('BAO_TOKEN', 'VAULT_TOKEN'), 'NAMESPACE': ('BAO_NAMESPACE', 'VAULT_NAMESPACE'), 'CA_CERT': ('BAO_CACERT', 'VAULT_CACERT'), 'CLIENT_CERT': ('BAO_CLIENT_CERT', 'VAULT_CLIENT_CERT'), 'CLIENT_KEY': ('BAO_CLIENT_KEY', 'VAULT_CLIENT_KEY'), 'INSECURE_SKIP_VERIFY': ('BAO_SKIP_VERIFY', 'VAULT_SKIP_VERIFY')}
dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)
kv_mount
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
secrets_path
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
url
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
value_field
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
OpenBaoError ¶
Bases: builtins.Exception
Base class of every error raised by this SDK.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
canonical :class: |
|
message |
human readable text; never contains credentials or raw response bodies. |
|
http_status |
HTTP status when the error came from a response. |
|
request_id |
vendor request id header when present. |
|
retryable |
whether retrying the same call may succeed. |
|
retry_after |
server requested delay in seconds (rate limiting / unavailable). |
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
default_retryable
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
OpenBaoSecretsProvider ¶
Bases: grow_openbao._secrets.base.BaseSecretsProvider
:class:SecretsProvider over an OpenBao KV mount (v1 or v2, auto-detected).
Create it with client.secrets(mount=None, path="", value_field="value").
get(name)reads<path>/<name>; KV v2 versions are theSecretValue.version.setreturns the new KV v2 version (""on KV v1);casandtags(custom metadata) need KV v2.stris stored as is,bytesas base64 (withencoding: base64), other values JSON-encoded.deletesoft-deletes the latest version (KV v2);versionsdeletes those versions,permanent=Trueremoves all versions and metadata. Missing → :class:NotFoundError.list(prefix)lists one folder level (sub-folders skipped); on KV v2 each entry carries its metadata and secrets whose current version is deleted are skipped.
capabilities
class-attribute
¶
Build an immutable unordered collection of unique elements.
full_path ¶
The KV path of a secret: <path or provider path>/<name>.
get_all ¶
Every secret directly under path (non-recursive), keyed by name.
set ¶
set(name: str, value: Any, *, path: str | None = None, cas: int | None = None, tags: Mapping[str, str] | None = None, description: str | None = None) -> str
Store value (str, bytes → base64, other → JSON); returns the version.
PermissionDeniedError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Authenticated but not allowed (HTTP 403).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
Pki ¶
Bases: grow_openbao._api.SyncModule
PKI engine on one mount: client.pki(mount="pki").
issue_certificate ¶
issue_certificate(role: str, common_name: str, *, alt_names: Sequence[str] | None = None, ip_sans: Sequence[str] | None = None, uri_sans: Sequence[str] | None = None, ttl_s: Duration | None = None, format: Literal['pem', 'der', 'pem_bundle'] | None = None, private_key_format: Literal['der', 'pkcs8'] | None = None, exclude_cn_from_sans: bool | None = None) -> IssuedCertificate
Issue a certificate and private key for a role (POST <mount>/issue/<role>).
A common name the role does not allow raises :class:ValidationError.
list_certificates ¶
Serials of all stored certificates; [] when there is none.
read_certificate ¶
A certificate by serial; :class:NotFoundError when unknown.
revoke_certificate ¶
Revoke a certificate by serial (aa:bb:...); unknown serials raise
:class:ValidationError.
sign_csr ¶
sign_csr(role: str, csr: str, *, common_name: str | None = None, alt_names: Sequence[str] | None = None, ip_sans: Sequence[str] | None = None, uri_sans: Sequence[str] | None = None, ttl_s: Duration | None = None, format: Literal['pem', 'der', 'pem_bundle'] | None = None, exclude_cn_from_sans: bool | None = None) -> SignedCertificate
Sign a PEM CSR for a role (POST <mount>/sign/<role>).
tidy ¶
tidy(*, tidy_cert_store: bool = True, tidy_revoked_certs: bool = True, safety_buffer_s: Duration | None = None, wait: bool = True, timeout_s: Duration = 60.0, interval_s: Duration = 0.5) -> TidyStatus
Start a tidy run (POST <mount>/tidy, 202).
Unless wait=False, poll tidy-status until it is Finished, Error or
Cancelled (:class:TimeoutError after timeout_s). Returns the last status.
Policy ¶
An ACL policy.
RateLimitError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Too many requests (HTTP 429); retry_after holds the requested delay when known.
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
default_retryable
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
RawResponse ¶
Result of :meth:OpenBaoClient.request: the decoded OpenBao envelope.
Request ¶
One logical API call (possibly several attempts).
path is joined to the base URL ({name} style values must already be encoded; use
:func:urllib.parse.quote); an absolute http:///https:// URL is used as is (for
pagination links the service returns; the default headers, config.headers included,
are sent there too, so only pass URLs of the same service). json is encoded when not
None; content sends raw bytes. idempotent overrides the method rule; an
idempotency_key sends the Idempotency-Key header and marks the request idempotent.
raise_for_status=False returns error responses instead of raising (retries still
apply). Statuses in allow_status are expected answers (a 404 that carries data, a
health endpoint's 503): the response is returned at once, like a success, without retries
or on_error.
allow_status
class-attribute
¶
Built-in immutable sequence.
If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.
If the argument is a tuple, the return value is the same object.
operation
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
raise_for_status
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
RequestInfo ¶
Passed to Hooks.on_request; url and headers are redacted.
ResourceRegistry ¶
Holds :class:Stoppable objects; :meth:stop_all stops each once, ignoring errors.
register ¶
Track item; when the registry is already closed the item is stopped now.
Response ¶
A completed HTTP response (body fully read).
attempts
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
operation
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
ResponseInfo ¶
Passed to Hooks.on_response; headers are the redacted response headers (rate
limit headers and the like stay readable).
RetryPolicy ¶
Retry settings. Durations are seconds (datetime.timedelta is accepted).
Backoff for retry n (0-based) is full jitter:
random(0, min(max_backoff, initial_backoff * multiplier ** n)).
random returns a float in [0, 1); inject it in tests for deterministic sleeps.
initial_backoff
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
max_backoff
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
max_retries
class-attribute
¶
int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.
int('0b100', base=0) 4
max_retry_after
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
multiplier
class-attribute
¶
Convert a string or number to a floating-point number, if possible.
backoff_cap ¶
Upper bound of the jittered sleep before retry retry (0-based).
RevocationInfo ¶
Result of :meth:Pki.revoke_certificate.
RoleInfo ¶
A role as returned by :meth:Database.read_role.
SealStatus ¶
sys/seal-status.
Secret ¶
Wraps a credential so it never shows up in str/repr/logs.
s = Secret("hunter2") str(s), s.reveal() ('[REDACTED]', 'hunter2')
SecretCache ¶
Bases: grow_openbao._secrets.base.BaseSecretsProvider
Caches reads of a :class:SecretsProvider; writes pass through and invalidate.
- Entries live
ttl_s; negative results (missing secrets) are cached too. - Refresh-ahead: a hit after
ttl_s * refresh_ahead_factorstarts one background refresh. - Stale-while-revalidate: up to
ttl_s + stale_while_revalidate_sthe stale value is returned while one refresh runs. - LRU eviction beyond
max_entries.clock(monotonic seconds) is injectable;spawnruns background refreshes (default: a daemon thread). - :meth:
closemakes later calls raise :class:CancelledError("client is closed"); it does not close the wrapped provider.
watch ¶
watch(name: str, interval_s: float | timedelta, on_change: Callable, *, on_error: Callable | None = None, version: str | None = None, path: str | None = None) -> WatchHandle
Watches the underlying provider directly (bypasses the cache).
SecretIdInfo ¶
A generated AppRole secret id (:class:Secret values).
SecretMetadata ¶
Names and metadata of a secret (never its value).
get(meta.name, path=meta.path) fetches the secret the metadata describes.
SecretValue ¶
Redacting wrapper around a secret's bytes.
str()/repr() print SecretValue([REDACTED]); use :meth:reveal,
:meth:reveal_bytes or :meth:json to read the value.
fingerprint ¶
SHA-256 hex digest of the value (used by watch when there is no version).
SecretsProvider ¶
Bases: typing.Protocol
Synchronous secrets interface implemented by every secrets service package.
ServiceError ¶
Bases: builtins.Exception
Base class of every error raised by this SDK.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
canonical :class: |
|
message |
human readable text; never contains credentials or raw response bodies. |
|
http_status |
HTTP status when the error came from a response. |
|
request_id |
vendor request id header when present. |
|
retryable |
whether retrying the same call may succeed. |
|
retry_after |
server requested delay in seconds (rate limiting / unavailable). |
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
default_retryable
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
SetOptions ¶
SetOptions(path: 'str | None' = None, cas: 'int | None' = None, tags: 'Mapping[str, str] | None' = None, description: 'str | None' = None)
Signature ¶
A signature vault:v<n>:<base64>.
SignedCertificate ¶
A certificate issued or signed by the PKI engine.
Stoppable ¶
Bases: typing.Protocol
Sys ¶
Bases: grow_openbao._api.SyncModule
System backend: client.sys. Most write calls need a privileged (root/sudo) token.
create_app_role ¶
create_app_role(name: str, *, mount: str = 'approle', token_policies: Sequence[str] | None = None, token_ttl_s: Duration | None = None, token_max_ttl_s: Duration | None = None, secret_id_ttl_s: Duration | None = None, secret_id_num_uses: int | None = None, bind_secret_id: bool | None = None, token_type: str | None = None) -> None
Create or update an AppRole role (POST auth/<mount>/role/<name>).
delete_app_role ¶
Delete an AppRole role.
disable_auth_method ¶
Disable an auth method; its tokens are revoked.
disable_secrets_engine ¶
Disable (unmount) a secrets engine; its data is deleted.
enable_auth_method ¶
enable_auth_method(path: str, type: str, *, description: str | None = None, default_lease_ttl_s: Duration | None = None, max_lease_ttl_s: Duration | None = None, local: bool | None = None) -> None
Enable an auth method at path.
enable_secrets_engine ¶
enable_secrets_engine(path: str, type: str, *, description: str | None = None, options: Mapping[str, str] | None = None, default_lease_ttl_s: Duration | None = None, max_lease_ttl_s: Duration | None = None, local: bool | None = None, seal_wrap: bool | None = None) -> None
Enable a secrets engine at path (e.g. type="kv", options={"version": "2"}).
A used path raises :class:ValidationError.
generate_secret_id ¶
generate_secret_id(name: str, *, mount: str = 'approle', metadata: Mapping[str, str] | None = None, cidr_list: Sequence[str] | None = None, ttl_s: Duration | None = None, num_uses: int | None = None) -> SecretIdInfo
Generate a new secret id for an AppRole role.
health ¶
GET sys/health (unauthenticated); sealed, standby and uninitialised nodes are no
error.
list_app_roles ¶
AppRole role names; [] when there is none.
list_auth_methods ¶
Auth methods by path ("approle/" → info).
read_policy ¶
Read an ACL policy; :class:NotFoundError when missing.
read_role_id ¶
The role id of an AppRole role; :class:NotFoundError for unknown roles.
write_policy ¶
Create or replace an ACL policy (PUT sys/policies/acl/<name>); invalid HCL raises
:class:ValidationError.
TidyStatus ¶
Tidy progress from <mount>/tidy-status.
TimeoutError ¶
Bases: grow_openbao._core.errors.OpenBaoError
A connect, request or total deadline was exceeded (also HTTP 408, 504).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
default_retryable
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
TlsConfig ¶
TLS settings. insecure_skip_verify is for tests only and logs a warning once.
insecure_skip_verify
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
TokenAuth ¶
Bases: grow_openbao.auth.AuthMethod
Uses an existing token; login checks it with lookup-self.
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
TokenInfo ¶
Token properties from :meth:Auth.lookup_self.
TokenRenewal ¶
One renewal or re-login seen by a :class:TokenRenewer on_renew callback.
TokenRenewer ¶
Renews the client token at 2/3 of its TTL (renew-self).
When the token cannot be renewed any more it logs in again with reauth or calls
on_expire once at expiry. Stopped by :meth:stop or client.close().
Create it with :meth:Auth.start_renewer (or login(..., auto_renew=True)).
Transit ¶
Bases: grow_openbao._api.SyncModule
Transit engine on one mount: client.transit(mount="transit").
create_key ¶
create_key(name: str, type: str = 'aes256-gcm96', *, exportable: bool | None = None, derived: bool | None = None, auto_rotate_period_s: Duration | None = None, allow_plaintext_backup: bool | None = None, key_size: int | None = None) -> TransitKey
Create a key (idempotent: an existing key is returned unchanged).
Types: aes128-gcm96, aes256-gcm96 (default), chacha20-poly1305, ed25519,
ecdsa-p256/-p384/-p521, rsa-2048/-3072/-4096, hmac …
decrypt ¶
decrypt(name: str, ciphertext: str, *, context: TransitInput | None = None, associated_data: TransitInput | None = None) -> bytes
Decrypt a vault:v<n>: ciphertext; returns the plaintext bytes.
decrypt_batch ¶
Decrypt many items in one request; see :meth:Transit.encrypt_batch for errors.
delete_key ¶
Delete a key (needs deletion_allowed=True, else :class:ValidationError).
encrypt ¶
encrypt(name: str, plaintext: TransitInput, *, context: TransitInput | None = None, key_version: int | None = None, associated_data: TransitInput | None = None) -> Ciphertext
Encrypt plaintext (text is UTF-8 encoded).
encrypt_batch ¶
Encrypt many items in one request.
Results are in input order; a failed item has error set (the call itself fails only
when the whole request fails).
generate_data_key ¶
generate_data_key(name: str, *, plaintext: bool = True, bits: Literal[128, 256, 512] = 256, context: TransitInput | None = None) -> DataKey
Generate a data key encrypted with the transit key (plus its plaintext by default).
hash ¶
hash(input: TransitInput, *, algorithm: str | None = None, format: Literal['hex', 'base64'] | None = None) -> str
Hash of input (default sha2-256, hex).
hmac ¶
hmac(name: str, input: TransitInput, *, algorithm: str | None = None, key_version: int | None = None) -> str
HMAC of input (vault:v<n>:<base64>).
list_keys ¶
Key names (sorted); [] when there is none.
random_bytes ¶
bytes random bytes from the server, encoded as base64 (default) or hex.
rewrap ¶
rewrap(name: str, ciphertext: str, *, context: TransitInput | None = None, key_version: int | None = None) -> Ciphertext
Re-encrypt a ciphertext with the latest (or given) key version without revealing it.
sign ¶
sign(name: str, input: TransitInput, *, hash_algorithm: str | None = None, signature_algorithm: Literal['pss', 'pkcs1v15'] | None = None, prehashed: bool | None = None, key_version: int | None = None, context: TransitInput | None = None) -> Signature
Sign input with an asymmetric key (symmetric keys raise :class:ValidationError).
update_key_config ¶
update_key_config(name: str, *, deletion_allowed: bool | None = None, min_decryption_version: int | None = None, min_encryption_version: int | None = None, exportable: bool | None = None, allow_plaintext_backup: bool | None = None, auto_rotate_period_s: Duration | None = None) -> TransitKey
Update key settings; returns the updated key.
verify ¶
verify(name: str, input: TransitInput, *, signature: str | None = None, hmac: str | None = None, hash_algorithm: str | None = None, signature_algorithm: Literal['pss', 'pkcs1v15'] | None = None, prehashed: bool | None = None, context: TransitInput | None = None) -> bool
Verify a signature or an hmac (exactly one); False when invalid.
TransitKey ¶
A transit key.
UnavailableError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Network error or server unavailable (HTTP 500, 502, 503).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
default_retryable
class-attribute
¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
UnsupportedError ¶
Bases: grow_openbao._core.errors.OpenBaoError
The service or deployment does not offer this capability (HTTP 501, missing API).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
UnwrapResult ¶
Result of :meth:Wrapping.unwrap: the original response (repr hides data).
UserpassAuth ¶
Bases: grow_openbao.auth.AuthMethod
Username/password login: POST auth/<mount>/login/<username> {password}.
method
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.
ValidationError ¶
Bases: grow_openbao._core.errors.OpenBaoError
Bad input (HTTP 400, 413, 422, other 4xx, client-side validation).
code
class-attribute
¶
Canonical error codes; the value is the wire form used by the conformance suite.
WatchHandle ¶
Polls fetch every interval_s in a daemon thread and reports changes.
The first successful fetch is the baseline; later fetches whose version (or SHA-256 when
unversioned) differ call on_change(new, old), including deletion (new is None).
Errors (from fetching or from on_change) go to on_error and polling continues.
A :class:CancelledError from fetching (the provider or client was closed) ends the
watcher quietly (:attr:stopped becomes true), like the async watcher.
WrapInfo ¶
A wrapping token (a :class:Secret) and its properties.
Wrapping ¶
Bases: grow_openbao._api.SyncModule
Response wrapping: client.wrapping.
lookup_wrapping ¶
Properties of a wrapping token without using it (POST sys/wrapping/lookup).
unwrap ¶
Unwrap a token (POST sys/wrapping/unwrap authenticated with the token itself).
A used or invalid token raises :class:ValidationError; never retried.
wrap ¶
Wrap data in a single-use token valid for ttl_s (POST sys/wrapping/wrap).
WrappingLookup ¶
Result of :meth:Wrapping.lookup_wrapping.
apoll_until
async
¶
apoll_until(fn: Callable[[], Awaitable[T | None]], *, timeout_s: float = 30.0, interval_s: float = 1.0, predicate: Callable[[T], bool] | None = None, operation: str = 'poll', clock: Callable[[], float] = monotonic) -> T
Async :func:poll_until; fn is an async callable.
env_var_name ¶
Variable name for secret name listed under path.
The name relative to path is upper-cased and every character outside [A-Z0-9_]
becomes _; prefix is prepended.
error_for_code ¶
Return the error class for a code (ErrorCode member or wire value).
error_from_status ¶
error_from_status(status: int, operation: str, *, content: bytes = b'', headers: Headers | None = None, known_secrets: list[str] | None = None, retry_after: float | None = None, request_id_headers: Sequence[str] = ()) -> ServiceError
Map an HTTP error status to the SPEC 2.1 error with a redacted, truncated message.
request_id_headers are checked before the default :data:REQUEST_ID_HEADERS.
get_logger ¶
The package logger (LOGGER_NAME), silent by default (NullHandler).
parse_bool ¶
Parse true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.
parse_duration ¶
Parse a duration into seconds.
Accepts integer milliseconds ("1500" → 1.5) or Go-style units ("500ms", "10s",
"2m", "1h", "1m30s"). Raises :class:ValueError for anything else.
parse_retry_after ¶
Parse Retry-After as delta seconds or an HTTP-date; return seconds (>= 0) or None.
poll_until ¶
poll_until(fn: Callable[[], T | None], *, timeout_s: float = 30.0, interval_s: float = 1.0, predicate: Callable[[T], bool] | None = None, operation: str = 'poll', sleep: Callable[[float], None] = sleep, clock: Callable[[], float] = monotonic) -> T
Call fn every interval_s until it returns a ready value; return that value.
A value is ready when it is not None and predicate(value) is true (without a
predicate: not an empty container). Retryable SDK errors raised by fn are remembered
and polling continues; other errors propagate. Raises :class:TimeoutError after timeout_s.
redact_fields ¶
Recursively redact values whose key looks sensitive in nested mappings and lists.
redact_headers ¶
Copy of headers with sensitive values replaced by [REDACTED].
redact_text ¶
Replace every known secret value (length >= 4) in text with [REDACTED].
redact_url ¶
Redact user info and every query value (all values, not only sensitive ones).
Query names are kept so the URL stays useful in logs.
retry_after_from_headers ¶
retry_after_from_headers(headers: Headers | Mapping[str, str], names: Sequence[str] = ('retry-after',), *, now: Callable[[], float] = time) -> float | None
Server requested delay in seconds from the first of names that parses.
Retry-After is delta seconds or an HTTP-date. Other headers (X-RateLimit-Reset,
RateLimit-Reset …) may be delta seconds or a Unix timestamp in seconds or milliseconds;
timestamps are turned into the remaining delay.
to_seconds ¶
Normalise a duration given as float seconds or :class:datetime.timedelta.
truncate ¶
Truncate text to limit characters (adds an ellipsis when cut).
user_agent ¶
grow-codes-<key>/<version> (python) plus <suffix> when given.