Typing Stubs for hvac

Warnings

• gotcha types-hvac is purely for static type checking. Installing it does not provide any runtime functionality; it only supplies type definitions for the `hvac` library. You must install `hvac` separately to use the client.
  Fix: Always install the runtime library `hvac` alongside `types-hvac` (e.g., `pip install hvac types-hvac`).
• gotcha The version of `types-hvac` aims to be compatible with specific major/minor versions of the `hvac` library (e.g., `types-hvac==2.4.0.*` for `hvac==2.4.*`). Using mismatched versions can lead to inaccurate or failing type checks, especially if the `hvac` API changes.
  Fix: Ensure that the installed `types-hvac` version closely matches the `hvac` version you are using. Refer to the `types-hvac` PyPI page or typeshed project for compatibility statements. Consider pinning stub versions (e.g., `types-hvac==2.4.0.20260408`) to avoid unexpected type-checking issues on updates.
• breaking While `types-hvac` itself doesn't introduce runtime breaking changes, future major versions of `hvac` (e.g., `hvac==3.0.0`) are slated to include breaking changes, such as modifying the `certificate` parameter for `create_ca_certificate_role` and changing the default for `raise_on_deleted_version`.
  Fix: Before upgrading `hvac` to a new major version, consult the `hvac` changelog and `types-hvac` release notes. Adjust your code to accommodate API changes, such as how `create_ca_certificate_role` handles certificates or how deleted secrets are retrieved from KV v2.

Install

• pip install hvac types-hvac Install hvac and its typing stubs

Imports

• Client

  from hvac import Client

  Type stubs are not imported directly; they provide type information for symbols imported from the runtime library (hvac).
• VaultError

  from hvac.exceptions import VaultError

  Type stubs for exceptions and other modules within hvac are provided via types-hvac but imported from the hvac package itself.

Quickstart

This quickstart demonstrates basic `hvac` client initialization and secret interaction with type hints. It requires the `VAULT_ADDR` and `VAULT_TOKEN` environment variables to be set for successful authentication. The `types-hvac` package provides the type information for `Client` and other `hvac` objects, allowing static analysis tools to verify the code's type safety.

import os
from hvac import Client
from hvac.exceptions import VaultError

# Ensure VAULT_ADDR and VAULT_TOKEN environment variables are set
# For example: export VAULT_ADDR='http://127.0.0.1:8200' VAULT_TOKEN='your_root_token'

client: Client | None = None
try:
    vault_addr = os.environ.get('VAULT_ADDR', 'http://127.0.0.1:8200')
    vault_token = os.environ.get('VAULT_TOKEN', 'your_vault_token')

    client = Client(url=vault_addr, token=vault_token)

    if client.is_authenticated():
        print('Successfully authenticated to Vault.')
        # Example: Write a secret
        path = 'secret/data/my-application/config'
        secret_data = {'username': 'testuser', 'password': 'testpassword'}
        client.secrets.kv.v2.create_or_update_secret(path=path, secret=secret_data)
        print(f'Secret written to {path}')

        # Example: Read a secret
        read_response = client.secrets.kv.v2.read_secret_version(path=path)
        if read_response and 'data' in read_response and 'data' in read_response['data']:
            print(f"Retrieved username: {read_response['data']['data']['username']}")
        else:
            print('Secret not found or invalid format.')
    else:
        print('Failed to authenticate to Vault.')

except VaultError as e:
    print(f'Vault operation failed: {e}')
except Exception as e:
    print(f'An unexpected error occurred: {e}')
finally:
    if client:
        # Ensure to close the client session if it manages connections
        # In hvac, the underlying requests session is usually managed implicitly or can be closed if explicitly created
        # For persistent clients, manual session closing might not be strictly necessary, but good practice for short-lived scripts.
        pass

# To verify type checking, run a type checker (e.g., mypy, pyright) on this file.