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.
Project setup options
Section titled “Project setup options”- 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.
- 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.
Install
Section titled “Install”From PyPI
Section titled “From PyPI”pip install sourceorrery==0.3.1sourceorrery 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.
From the GitHub release
Section titled “From the GitHub release”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:
# x64pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-win_amd64.whl# Arm64pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-win_arm64.whl# Apple siliconpip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-macosx_11_0_arm64.whl# Intelpip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl# x64pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-manylinux_2_28_x86_64.whl# arm64pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-manylinux_2_28_aarch64.whlTo 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>.
From source
Section titled “From source”See Building from source below.
Get a secret
Section titled “Get a secret”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 endsSecretReader(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.valuevalue.expose() # bytes (a copy)value.expose_text() # strlen(value)value.close() # zeroise; expose() raises ValueError afterwardsrepr(value) # 'SecretValue([REDACTED])'pickle.dumps(value), copy.copy(value) and json.dumps(value) raise
TypeError.
Errors
Section titled “Errors”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 triedexcept 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.
Load a project
Section titled “Load a project”import osfrom 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.
Threads
Section titled “Threads”A SecretReader may be shared between threads; the native call releases
the GIL, so reads run in parallel.
Building from source
Section titled “Building from source”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:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changesBuild the package and install it into a virtual environment. pip fetches maturin, which compiles the Rust extension; the first build takes a few minutes.
python -m venv .venvsource .venv/bin/activate # Windows: .venv\Scripts\activate (PowerShell), source .venv/Scripts/activate (Git Bash)pip install ./bindings/pythonpython -c "import sourceorrery; print(sourceorrery.__version__)"To install the build somewhere else, make a wheel and copy it there:
pip wheel ./bindings/python --no-deps -w dist # dist/sourceorrery-<version>-cp311-abi3-<platform>.whlThe 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:
cargo build --release -p sourceorrery-clieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault and the variables the tests readpip install pytestpython -m pytest bindings/python/testspython bindings/python/examples/get_secret.py "$SOURCEORRERY_TEST_VAULT" database-passwordpython tests/conformance/sdk/harness.py --runner pythonWhat the fixture script creates: The SDK test vault.
Source: bindings/python (opens in a new tab).