# Python

Documentation version: 0.3.1.

> [!NOTE]
> SDKs are read-only. The CLI creates vaults and sets secret values;
> applications do not need a CLI process running alongside them.

## Project setup options

1. **Option 1: Set up with the CLI.** Follow the [CLI installation guide](https://sourceorrery.ai/getting-started/#install),
   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](https://sourceorrery.ai/guides/ai-agents/)
   works with an existing CLI installation.

## Install




### From PyPI

```bash
pip install sourceorrery==0.3.1
```

[`sourceorrery` on PyPI](https://pypi.org/project/sourceorrery/) 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](https://sourceorrery.ai/security/supply-chain/#pypi): 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

The same wheels and sdist are attached to the
[v0.3.1 release](https://github.com/Netizine/sourceorrery/releases/tag/v0.3.1).
Install the wheel for your platform straight from it:



#### Windows

```bash
# 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
```

#### macOS

```bash
# Apple silicon
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-macosx_11_0_arm64.whl
# Intel
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl
```

#### Linux

```bash
# x64
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-manylinux_2_28_x86_64.whl
# arm64
pip install https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1-cp311-abi3-manylinux_2_28_aarch64.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>`.

### From source

See [Building from source](https://sourceorrery.ai/sdks/python/#building-from-source) below.

## Get a secret

```python
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](https://sourceorrery.ai/providers/hashicorp-vault/),
[AWS Secrets Manager](https://sourceorrery.ai/providers/aws-secrets-manager/),
[Azure Key Vault](https://sourceorrery.ai/providers/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.

> [!IMPORTANT]
> `expose_text()` returns a Python `str` copy. Leaving the `with` block
> clears the SDK's native buffer, but cannot erase that string or copies
> retained by `connect()`. Keep exposed values short-lived and out of logs.

| 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`:

```python
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`.

## Errors

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

```python
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](https://sourceorrery.ai/sdks/#errors) for what each hint says.

## Load a project

```python
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.

> [!NOTE]
> This example deliberately copies values into this process's environment.
> Closing `Project` does not remove those variables or erase their string
> copies. Read individual values directly through the SDK when your
> application does not need environment-based configuration.

## Threads

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

## 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](https://sourceorrery.ai/guides/building-from-source/#what-you-need) has the commands for
each platform. For this SDK, also Python 3.11 or newer with `pip`.

Get the code:

```bash
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.

```bash
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:

```bash
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](https://sourceorrery.ai/guides/building-from-source/#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:

```bash
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](https://sourceorrery.ai/guides/building-from-source/#the-sdk-test-vault).
Source: [`bindings/python`](https://github.com/Netizine/sourceorrery/blob/main/bindings/python/README.md).
