hvac

hvac is the community-maintained Python client for HashiCorp Vault, wrapping Vault’s REST API surface in a single Client object that exposes every major secrets engine and authentication method as a discrete, typed Python module. Rather than hand-rolling HTTP calls against Vault’s endpoints, callers instantiate hvac.Client and dispatch to submodules under hvac.api.secrets_engines (KV v1/v2, PKI, Transit, Database, AWS, GCP, Azure, LDAP, RabbitMQ, SSH, Consul, Identity) and hvac.api.auth_methods (AppRole, Kubernetes, AWS, LDAP, OIDC, GitHub, Okta, RADIUS, userpass, and more).

Underneath, a pluggable Adapter abstraction (JSONAdapter by default, with a RawAdapter alternative) isolates the actual requests-based HTTP transport from the API-shaped wrapper classes, so retry behavior, TLS verification, and proxy configuration can be swapped without touching call sites. The library also carries a deliberate deprecation path for its legacy write() method, nudging callers toward write_data() while preserving backward compatibility for existing integrations.

What You Get

• A single hvac.Client entry point that authenticates to Vault and dispatches to every mounted secrets engine and auth method
• Typed wrapper modules for KV v1/v2, PKI, Transit, Database, AWS/GCP/Azure, LDAP, RabbitMQ, SSH, Consul, and Identity secrets engines
• Auth method modules covering AppRole, AWS IAM, Kubernetes, LDAP, OIDC, GitHub, Okta, RADIUS, and userpass
• A pluggable Adapter abstraction (JSONAdapter/RawAdapter) so requests-level transport behavior can be customized without touching call sites
• System backend helpers for seal/unseal, policy management, audit devices, and Vault health checks

Common Use Cases

• Fetching database credentials or API keys from Vault inside a Python service at request or startup time instead of embedding secrets in config
• Reading and rotating versioned KV v2 secrets as part of a deployment or CI/CD pipeline
• Authenticating a Python workload to Vault via AppRole or Kubernetes service-account auth in a containerized environment
• Using the Transit secrets engine from Python to encrypt/decrypt application data without the app ever holding raw encryption keys

Under The Hood

Architecture hvac’s Client class (hvac/v1/init.py) is the composition root: it builds an Adapter instance and assembles every VaultApiCategory subclass — the auth_methods, secrets_engines, and system_backend packages — behind attributes on the client, with each category further decomposed into one module per Vault subsystem (e.g. api/secrets_engines/kv_v2.py, api/auth_methods sub-modules) inheriting a shared VaultApiBase. This gives a flat, mostly 1:1 mapping between Vault’s own REST namespaces and hvac’s Python namespaces, so a change to Vault’s API surface is localized to one module rather than rippling through the client. The main structural tension is legacy compatibility code living alongside the current design — the write()/_smart_pop deprecation shim in the Client constructor exists purely to keep an older calling convention working while steering callers to write_data().

Tech Stack The library targets Python 3.8+ (managed via Poetry, pyproject.toml) with requests as its only required runtime dependency and an optional pyhcl extra (installed via the [parser] extra) for parsing HCL-formatted responses into native dicts. Development tooling layers in black for formatting, flake8 for linting, and a dev dependency group that includes Flask/Werkzeug/Authlib for standing up mock OAuth/OIDC providers in tests. Docs are built with Sphinx plus a custom doctest extension (docs/ext/hvac_doctest.py) that runs documentation examples as real tests against a live Vault binary.

Code Quality The test suite is split into unit_tests (mocking the adapter/HTTP layer with requests_mock) and integration_tests (spinning up an actual Vault server, per CONTRIBUTING.md, to exercise auth methods and secrets engines end-to-end), giving both fast isolated coverage and confidence against real Vault behavior. CI (lint-and-test.yml) runs this matrix across every supported Python version plus a nightly scheduled run, alongside black and flake8 checks. Docstrings are consistently present and detailed across the API modules (parameter types, return types, and links to the corresponding Vault API docs), though the codebase relies on docstring type annotations rather than PEP 484 type hints throughout most of the client.

API Design The public surface favors explicitness over magic: every secrets-engine and auth-method call takes a mount_point keyword with a documented default, and responses are returned as raw requests.Response-like JSON rather than wrapped model objects, which keeps the library thin but pushes some interpretation work onto callers. Method names largely mirror Vault’s own path segments, which keeps the mapping between docs and code predictable once a user has read Vault’s API reference, at the cost of some verbosity for common operations like a simple KV read/write.