Skip to content

Python

The read-only Python SDK: install it from PyPI, the release or source, open a vault, get a secret, handle typed errors with hints, load a project.

6 min read
  1. Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
  2. Option 2: Set up with an AI coding agent. Run sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
Terminal window
pip install sourceorrery==0.3.1

sourceorrery on PyPI (opens in a new tab) has abi3 wheels for Python 3.11+ on Windows, macOS and Linux (glibc), x64 and arm64, built with PyO3 and maturin, with no runtime dependencies, so nothing is compiled on install. uv add sourceorrery==0.3.1 and poetry add sourceorrery@0.3.1 install the same package. On any other platform pip builds the sdist, which needs Rust 1.91.1+ and a C compiler.

To pin the exact files you install, see Supply chain: the wheels on PyPI are byte for byte the ones on the GitHub release, so their hashes can be checked against each other.

The same wheels and sdist are attached to the v0.3.1 release (opens in a new tab). Install the wheel for your platform straight from it:

Terminal window
# x64
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-win_amd64.whl
# Arm64
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-win_arm64.whl

To pin it, put the same URL in requirements.txt as sourceorrery @ https://…/sourceorrery-0.3.1-cp311-abi3-win_amd64.whl; append #sha256=<hash> with the hash from the release’s SHA256SUMS and pip verifies the download. Any other platform builds the sdist from the same release (sourceorrery-0.3.1.tar.gz; Rust 1.91.1+ required) with pip install <its URL>.

See Building from source below.

from sourceorrery import SecretReader
with SecretReader("development") as reader, reader.get("database-password") as secret:
connect(password=secret.value.expose_text())
# the SDK's native buffer is zeroised when the `with` block ends

SecretReader(vault, *, home=None, recovery_key=None, recovery_key_file=None, environment=True) opens the vault. With the default options, SOURCEORRERY_HOME locates the vault; this machine’s key in the OS credential store opens it, else the recovery key: recovery_key, SOURCEORRERY_RECOVERY_KEY, then recovery_key_file or SOURCEORRERY_RECOVERY_KEY_FILE. Pass environment=False to ignore the two variables. The SDK never prompts and never asks the vault’s view check.

A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.

Call Returns
reader.get(name) Secret for the newest accessible version
reader.get(name, version) Secret for exactly that version
reader.properties(name, version=None) SecretProperties (policy not applied)
reader.resolve("sourceorrery://development/database-password") Secret
reader.descriptor() dict describing the vault (no values)
reader.close() releases the vault; also a context manager

Secret has .properties (a frozen dataclass: vault, name, version, enabled, content_type, tags, not_before, expires_on, created_on, updated_on, recovery_level, reference) and .value, a SecretValue:

value = secret.value
value.expose() # bytes (a copy)
value.expose_text() # str
len(value)
value.close() # zeroise; expose() raises ValueError afterwards
repr(value) # 'SecretValue([REDACTED])'

pickle.dumps(value), copy.copy(value) and json.dumps(value) raise TypeError.

All exceptions derive from sourceorrery.SourceOrreryError and carry .code, .message and .hint; str(err) is the message followed by the hint.

from sourceorrery import SecretReader, SecretNotFoundError, VaultLockedError, SourceOrreryError
try:
with SecretReader("development") as reader:
with reader.get("database-password") as secret:
connect(password=secret.value.expose_text())
except VaultLockedError as err:
print(err.hint) # which recovery-key sources were tried
except SecretNotFoundError as err:
print(err.hint) # "Store it with `sourceorrery secret set database-password --vault development` ..."
except SourceOrreryError as err:
print(err.code, err)

Classes: VaultNotFoundError, VaultLockedError, MigrationRequiredError, VaultMismatchError, SecretNotFoundError, VersionNotFoundError, SecretDeletedError, PolicyError with SecretDisabledError, SecretNotYetValidError (.transient is true), SecretExpiredError, IntegrityError, UnsupportedError, InvalidArgumentError, InvalidNameError, ManifestError, PermissionDeniedError, StorageError, and for secrets kept at a provider UnauthenticatedError (the provider has no credentials for this process) and ProviderUnavailableError (it could not be reached; .transient is true). See the SDK overview for what each hint says.

import os
from sourceorrery import Project
with Project.load("sourceorrery.toml") as project: # or Project.load() to discover it
os.environ.update({s.env: s.value.expose_text() for s in project})

Project.load resolves every [secrets.*] entry the way sourceorrery run does and raises the first required secret’s error if one cannot be read. project.env("DATABASE_PASSWORD"), project.get("database-password") and iteration give the resolved entries.

A SecretReader may be shared between threads; the native call releases the GIL, so reads run in parallel.

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler (on Linux also pkg-config and libdbus-1-dev); Building from source has the commands for each platform. For this SDK, also Python 3.11 or newer with pip.

Get the code:

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1 # or stay on main for the newest changes

Build the package and install it into a virtual environment. pip fetches maturin, which compiles the Rust extension; the first build takes a few minutes.

Terminal window
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate (PowerShell), source .venv/Scripts/activate (Git Bash)
pip install ./bindings/python
python -c "import sourceorrery; print(sourceorrery.__version__)"

To install the build somewhere else, make a wheel and copy it there:

Terminal window
pip wheel ./bindings/python --no-deps -w dist # dist/sourceorrery-<version>-cp311-abi3-<platform>.whl

The version is the one committed in the repository, not the release’s; Get the code shows how to stamp the release version first.

To run the tests, the example and the conformance harness, build the CLI, which creates the test vault, and run the rest in Bash (Git Bash on Windows) with the virtual environment active:

Terminal window
cargo build --release -p sourceorrery-cli
eval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault and the variables the tests read
pip install pytest
python -m pytest bindings/python/tests
python bindings/python/examples/get_secret.py "$SOURCEORRERY_TEST_VAULT" database-password
python tests/conformance/sdk/harness.py --runner python

What the fixture script creates: The SDK test vault. Source: bindings/python (opens in a new tab).