Skip to main content

valt0

Python client for Valt0. It fetches secrets from a local Valt0 vault at runtime, so you don't have to keep them in .env files, config files, or CI variables.

  • License: Apache-2.0
  • Requires: Python >= 3.9, and the valt0 service/CLI installed and running locally

Installation

pip install valt0-client

The package is installed as valt0-client and imported as valt0.


Usage

import valt0

vault = valt0.open_vault(id="your-vault-id", name="your-vault-name")

# The with block zeroes the underlying buffer as soon as you are finished
with vault.secret("DATABASE_PASSWORD") as secret:
    # Preferred: the raw bytes, wiped on exit
    pw = secret.bytes()

    # Or, when a string is unavoidable
    db.connect(password=secret.reveal())

Without a with block, call secret.destroy() yourself, ideally in a finally.

Secrets are redacted by default

A Secret won't leak its value into a log line, a traceback, an f-string, or a pickle. You only get the plaintext when you ask for it explicitly:

print(secret)                            # [REDACTED]
print(repr(secret))                      # Secret([REDACTED])
f"{secret}"                              # [REDACTED]
logging.info("connecting %s", secret)    # connecting [REDACTED]
json.dumps({"pw": secret}, default=str)  # {"pw": "[REDACTED]"}
pickle.dumps(secret)                     # TypeError: valt0: Secret objects cannot be pickled or copied

secret.reveal()  # the actual value

Redaction covers str(), repr() and format(). Pickling and copying raise TypeError, so a secret can't slip out through multiprocessing or a cache.

Errors

open_vault and Vault.secret raise two specific errors for the most common connection failures:

try:
    vault = valt0.open_vault(id="your-vault-id", name="your-vault-name")
except valt0.CantConnectToServiceError:
    ...  # socket or session file not found: is the valt0 service running?
except valt0.NoServiceResponseError:
    ...  # the service did not answer in time
except valt0.Valt0Error:
    ...  # any other error, e.g. the vault could not be loaded

The service has 1 second to answer each request. Outside deploy mode, opening a vault waits up to 60 seconds instead, so you have time to unlock the vault when the service asks.

Threads and asyncio

The client is synchronous and thread-safe; every call uses its own connection. From async code, run it in a worker thread:

secret = await asyncio.to_thread(vault.secret, "DATABASE_PASSWORD")

API

open_vault(*, id: str, name: str) -> Vault

Opens the vault identified by id. Raises an error if the service is unreachable or the vault cannot be loaded.

Argument Type Description
id str Vault identifier — the only value used to locate the vault
name str Display label for messages; .valt0 is appended if missing

Note: name can be anything. Valt0 does not check that it matches the vault id — it is only used for messaging purposes, so pick whatever makes the vault easy to recognise.

Vault

Member Description
id The vault's id
name The vault's name
secret(name) Secret: fetches one secret by name

Secret

Member Description
bytes() The raw bytes as a bytearray (the underlying buffer, not a copy). This is the preferred accessor.
reveal() The value as a str. Strings are immutable and can't be wiped, so use sparingly. ValueError if not UTF-8 text.
destroy() Zeroes the buffer. Buffers returned by bytes() are zeroed too, and later calls return empty values.
with secret Calls destroy() when the block exits.

Errors

Error Raised when
Valt0Error Base class of every error the client raises
CantConnectToServiceError The service socket or session file does not exist
NoServiceResponseError The service did not respond before the deadline

Maintained by BYTE 1620. Licensed under Apache-2.0.

Metadata

Release files for valt0-client 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valt0-client 1.0.1
File Size Uploaded Provenance Actions
valt0_client-1.0.1.tar.gz 54.2 kB Without provenance Details for valt0_client-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valt0-client 1.0.1
File Interpreter ABI Platform Actions
valt0_client-1.0.1-py3-none-any.whl Python 3 none any Details for valt0_client-1.0.1-py3-none-any.whl

Total release size: 77.8 kB

Release files / valt0_client-1.0.1.tar.gz

Download URL valt0_client-1.0.1.tar.gz
Size 54.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1418e38e5637761c7ea7c4ce50a10bbfd1fa1c99e07766caf105c3e57e3e73fa
BLAKE2b-256 checksum
How to use checksums
423dee92b74d712ccf7820e139349c1de75f42ae719289c2145acaf8fd1177b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / valt0_client-1.0.1-py3-none-any.whl

Download URL valt0_client-1.0.1-py3-none-any.whl
Size 23.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
46a7e198e01371b109da084f68b01872443cb6ec8ed22d184318b8f8bc215d03
BLAKE2b-256 checksum
How to use checksums
1656d3733857207770387c14ba84d4ae8052fc0f56ab7cb63fa3cf2bead8e4e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for valt0-client 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page