{"id":5087,"library":"types-hvac","title":"Typing Stubs for hvac","description":"types-hvac provides static type annotations for the `hvac` library, the official Python client for HashiCorp Vault. It enables type checkers like MyPy and Pyright to analyze code using `hvac` for type correctness. The package version 2.4.0.20260408 offers accurate annotations for `hvac==2.4.*` and is part of the actively maintained typeshed project.","status":"active","version":"2.4.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","hvac","typeshed","vault","type-checking"],"install":[{"cmd":"pip install hvac types-hvac","lang":"bash","label":"Install hvac and its typing stubs"}],"dependencies":[{"reason":"types-hvac provides type hints for this package; it is required at runtime to use the functionality described.","package":"hvac","optional":false}],"imports":[{"note":"Type stubs are not imported directly; they provide type information for symbols imported from the runtime library (hvac).","symbol":"Client","correct":"from hvac import Client"},{"note":"Type stubs for exceptions and other modules within hvac are provided via types-hvac but imported from the hvac package itself.","symbol":"VaultError","correct":"from hvac.exceptions import VaultError"}],"quickstart":{"code":"import os\nfrom hvac import Client\nfrom hvac.exceptions import VaultError\n\n# Ensure VAULT_ADDR and VAULT_TOKEN environment variables are set\n# For example: export VAULT_ADDR='http://127.0.0.1:8200' VAULT_TOKEN='your_root_token'\n\nclient: Client | None = None\ntry:\n    vault_addr = os.environ.get('VAULT_ADDR', 'http://127.0.0.1:8200')\n    vault_token = os.environ.get('VAULT_TOKEN', 'your_vault_token')\n\n    client = Client(url=vault_addr, token=vault_token)\n\n    if client.is_authenticated():\n        print('Successfully authenticated to Vault.')\n        # Example: Write a secret\n        path = 'secret/data/my-application/config'\n        secret_data = {'username': 'testuser', 'password': 'testpassword'}\n        client.secrets.kv.v2.create_or_update_secret(path=path, secret=secret_data)\n        print(f'Secret written to {path}')\n\n        # Example: Read a secret\n        read_response = client.secrets.kv.v2.read_secret_version(path=path)\n        if read_response and 'data' in read_response and 'data' in read_response['data']:\n            print(f\"Retrieved username: {read_response['data']['data']['username']}\")\n        else:\n            print('Secret not found or invalid format.')\n    else:\n        print('Failed to authenticate to Vault.')\n\nexcept VaultError as e:\n    print(f'Vault operation failed: {e}')\nexcept Exception as e:\n    print(f'An unexpected error occurred: {e}')\nfinally:\n    if client:\n        # Ensure to close the client session if it manages connections\n        # In hvac, the underlying requests session is usually managed implicitly or can be closed if explicitly created\n        # For persistent clients, manual session closing might not be strictly necessary, but good practice for short-lived scripts.\n        pass\n\n# To verify type checking, run a type checker (e.g., mypy, pyright) on this file.","lang":"python","description":"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."},"warnings":[{"fix":"Always install the runtime library `hvac` alongside `types-hvac` (e.g., `pip install hvac types-hvac`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"hvac>=3.0.0 (and corresponding types-hvac versions)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}