Skip to main content

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

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.

Metadata

Release files for fnox-py 1.31.0

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

Source distribution (sdist)

Source distribution for fnox-py 1.31.0
File Size Uploaded Provenance Actions
fnox_py-1.31.0.tar.gz 6.6 kB With provenance Details for fnox_py-1.31.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fnox-py 1.31.0
File Actions
fnox_py-1.31.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for fnox_py-1.31.0-py3-none-win_arm64.whl
fnox_py-1.31.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for fnox_py-1.31.0-py3-none-win_amd64.whl
fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl
fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl
fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl
fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 118.7 MB

Release files / fnox_py-1.31.0.tar.gz

Download URL fnox_py-1.31.0.tar.gz
Size 6.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ef26fc01240a3d48a42bd7ff2ca8983383a54b78963e01e1cd2a8496546b7560
BLAKE2b-256 checksum
How to use checksums
c66ade5b9ba7bef3bb3b0c94100c4d177668acfed988aba8425b3affe5f95271
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-win_arm64.whl

Download URL fnox_py-1.31.0-py3-none-win_arm64.whl
Size 15.6 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
74d5deb7d48cbfb6e5c553116aba0eaceafffc92490dd07e78059effa21fd76a
BLAKE2b-256 checksum
How to use checksums
860f9e6f2049b3fb3913ef8d2afc8246b6b0c5428f2a87fc9b6acc93ff7baba5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-win_amd64.whl

Download URL fnox_py-1.31.0-py3-none-win_amd64.whl
Size 16.7 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
f48b7166ddaacf3f5639931d0cd1c7b830d54daa84f544784a7230091ee829a1
BLAKE2b-256 checksum
How to use checksums
2fee821978442e207240f51781b52bc1c079d4274609451bec08742e749eecdd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl

Download URL fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl
Size 24.6 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
8e8239a8a357fb55010902bb81d066de3b4a9c954eaa65d502df15d189f1eba3
BLAKE2b-256 checksum
How to use checksums
68d768d0e5d5473deca17df3b032805aa37c433d2683fcaef25ce0d1548927cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl

Download URL fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl
Size 23.8 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
4081aa8766b02939b1312820519b969e6634ee38799c2f38229e9ee764deaf54
BLAKE2b-256 checksum
How to use checksums
0bd71051b08f575c7d28e3eb70122054d576d8f52a5aff3771478e6e2fe41972
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl

Download URL fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl
Size 18.1 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
a5fb358c576d32e3bfbc919bc7392bb2c5fdf568dea6237ae45872c6675aad5f
BLAKE2b-256 checksum
How to use checksums
2613471196840eec8db7220b5fa96e61d3e446b98dfe09a102287d975876d97b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl

Download URL fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl
Size 19.7 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
e9627d63fdfcc7e66a8425f130b37b9afed07b89a14476f0f60eb188b3b3965a
BLAKE2b-256 checksum
How to use checksums
2debd19b931569757d9c6791a87ce4d9882521e1e2de637162e53df381def9ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Security for fnox-py 1.31.0

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.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for fnox_py-1.31.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

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.

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