fnox-py 1.25.1

Python wrapper for fnox

fnox-py

fnox-py is a thin Python wrapper around the fnox secrets management tool.

It does not reimplement fnox behavior in Python. Instead, it:

• locates a real fnox binary
• builds argv for common commands
• runs the binary
• returns parsed results or typed errors

Python requirement: >=3.12

[!NOTE] Official fnox project links:

• GitHub repo: jdx/fnox
• Fnox docs: https://fnox.jdx.dev

Installation

uv

uv tool install fnox-py

pip

pip install fnox-py

Bundled binary vs source install

Platform wheels are intended to bundle the fnox binary.

If you install from source instead of a platform wheel, fnox-py requires a real fnox executable to be available via:

• PATH, or
• FNOX_PY_BINARY=/absolute/path/to/fnox

Examples:

pip install --no-binary fnox-py fnox-py

FNOX_PY_BINARY=/usr/local/bin/fnox python -c "import fnox_py; print(fnox_py.version())"

Binary Resolution

At runtime, fnox-py resolves the fnox binary in this order:

1. FNOX_PY_BINARY
2. bundled/installed locations in the current environment
3. bundled/installed fallback locations associated with the base or target install
4. user scheme script location
5. PATH

If FNOX_PY_BINARY is set but points to a missing file, fnox-py raises FnoxNotFoundError.

Python API

from fnox_py import (
    config_files,
    export_json,
    get,
    lease_create,
    profiles,
    providers,
    schema,
    version,
)

value = get("MY_SECRET")
all_values = export_json()
schema_doc = schema()
profile_names = profiles()
provider_names = providers()
config_paths = config_files()
lease = lease_create("vault", duration="1h", label="local-dev")
fnox_version = version()

Common examples

Get a single value:

from fnox_py import get

token = get("API_TOKEN")

Get a value from a specific profile:

from fnox_py import get

token = get("API_TOKEN", profile="prod")

Decode base64 output:

from fnox_py import get

decoded = get("TLS_CERT", base64_decode=True)

Export all secrets as JSON:

from fnox_py import export_json

data = export_json(profile="dev")

Inspect schema, profiles, providers, and config files:

from fnox_py import config_files, profiles, providers, schema

print(schema())
print(profiles())
print(providers())
print(config_files())

Create a lease:

from fnox_py import lease_create

lease = lease_create("vault", duration="30m", label="ci-job")

Get the underlying fnox version:

from fnox_py import version

print(version())

CLI

The package installs the fnox-py console script.

Built-in subcommands

Locate the resolved binary:

fnox-py which

Show the wrapper version and attempt to print the underlying fnox version:

fnox-py version

Print basic environment diagnostics:

fnox-py doctor

Passthrough behavior

Any arguments other than which, version, and doctor are passed directly through to fnox.

For example:

fnox-py get MY_SECRET
fnox-py profiles
fnox-py export --format json

With no arguments, fnox-py runs fnox with no extra argv.

Public API

fnox-py currently exports:

• config_files
• export_json
• get
• lease_create
• profiles
• providers
• schema
• version
• find_fnox_bin
• run
• FnoxResult
• FnoxCommandError
• FnoxError
• FnoxNotFoundError
• FnoxTimeoutError

Errors

Library calls raise typed exceptions:

• FnoxNotFoundError when the binary cannot be found
• FnoxCommandError when fnox exits non-zero
• FnoxTimeoutError on subprocess timeout
• FnoxError as the base exception type

Development

This project uses uv, pytest, ruff, and mypy.

Install dependencies:

uv sync

Run tests:

uv run pytest -v

Run a single test:

uv run pytest tests/test_api.py::test_get -q

Lint:

uv run ruff check src tests scripts

Type-check:

uv run mypy src

Build distributions:

uv build

Release / Platform Wheel Build

scripts/build_platform_wheel.py builds platform-specific wheels by:

1. building a pure Python wheel
2. downloading upstream fnox release binaries
3. injecting the binary into the wheel
4. rewriting wheel metadata
5. building an sdist

The upstream fnox version to bundle is read from FNOX_VERSION.txt at the repo root by default. To override it, pass --fnox-version:

uv run python scripts/build_platform_wheel.py --fnox-version 1.0.0 --output dist/

Expected upstream archive and extracted binary SHA256 values are pinned in FNOX_HASHES.json and verified during release builds.

To bump the bundled version, update FNOX_VERSION.txt, refresh FNOX_HASHES.json, and commit both changes.

Notes

• fnox-py is intentionally small and wrapper-focused.
• For behavior, flags, and command semantics, prefer the upstream fnox documentation.
• If you need lower-level control, use run() directly and inspect FnoxResult.