Metadata-Version: 2.3
Name: vault-kv-client
Version: 0.1.0
Summary: Typed HashiCorp Vault KV helper library with pragmatic auth and env helpers.
Keywords: vault,hashicorp,hvac,secrets,kubernetes,jwt,approle
Author: PaulKov
License: Apache License
         Version 2.0, January 2004
         http://www.apache.org/licenses/
         
         TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
         
         1. Definitions.
         
         "License" shall mean the terms and conditions for use, reproduction, and
         distribution as defined by Sections 1 through 9 of this document.
         
         "Licensor" shall mean the copyright owner or entity authorized by the copyright
         owner that is granting the License.
         
         "Legal Entity" shall mean the union of the acting entity and all other entities
         that control, are controlled by, or are under common control with that entity.
         For the purposes of this definition, "control" means (i) the power, direct or
         indirect, to cause the direction or management of such entity, whether by
         contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
         outstanding shares, or (iii) beneficial ownership of such entity.
         
         "You" (or "Your") shall mean an individual or Legal Entity exercising
         permissions granted by this License.
         
         "Source" form shall mean the preferred form for making modifications, including
         but not limited to software source code, documentation source, and configuration
         files.
         
         "Object" form shall mean any form resulting from mechanical transformation or
         translation of a Source form, including but not limited to compiled object code,
         generated documentation, and conversions to other media types.
         
         "Work" shall mean the work of authorship, whether in Source or Object form, made
         available under the License, as indicated by a copyright notice that is included
         in or attached to the work.
         
         "Derivative Works" shall mean any work, whether in Source or Object form, that is
         based on (or derived from) the Work and for which the editorial revisions,
         annotations, elaborations, or other modifications represent, as a whole, an
         original work of authorship. Derivative Works shall not include works that remain
         separable from, or merely link (or bind by name) to the interfaces of, the Work
         and Derivative Works thereof.
         
         "Contribution" shall mean any work of authorship, including the original version
         of the Work and any modifications or additions to that Work or Derivative Works
         thereof, that is intentionally submitted to Licensor for inclusion in the Work by
         the copyright owner or by an individual or Legal Entity authorized to submit on
         behalf of the copyright owner.
         
         "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of
         whom a Contribution has been received by Licensor and subsequently incorporated
         within the Work.
         
         2. Grant of Copyright License.
         
         Subject to the terms and conditions of this License, each Contributor hereby
         grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
         irrevocable copyright license to reproduce, prepare Derivative Works of,
         publicly display, publicly perform, sublicense, and distribute the Work and such
         Derivative Works in Source or Object form.
         
         3. Grant of Patent License.
         
         Subject to the terms and conditions of this License, each Contributor hereby
         grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
         irrevocable (except as stated in this section) patent license to make, have
         made, use, offer to sell, sell, import, and otherwise transfer the Work.
         
         If You institute patent litigation against any entity alleging that the Work or a
         Contribution incorporated within the Work constitutes direct or contributory
         patent infringement, then any patent licenses granted to You under this License
         for that Work shall terminate as of the date such litigation is filed.
         
         4. Redistribution.
         
         You may reproduce and distribute copies of the Work or Derivative Works thereof
         in any medium, with or without modifications, and in Source or Object form,
         provided that You meet the following conditions:
         
         (a) You must give any other recipients of the Work or Derivative Works a copy of
         this License; and
         
         (b) You must cause any modified files to carry prominent notices stating that You
         changed the files; and
         
         (c) You must retain, in the Source form of any Derivative Works that You
         distribute, all copyright, patent, trademark, and attribution notices from the
         Source form of the Work, excluding those notices that do not pertain to any part
         of the Derivative Works; and
         
         (d) If the Work includes a "NOTICE" text file as part of its distribution, then
         any Derivative Works that You distribute must include a readable copy of the
         attribution notices contained within such NOTICE file, excluding those notices
         that do not pertain to any part of the Derivative Works, in at least one of the
         following places: within a NOTICE text file distributed as part of the Derivative
         Works; within the Source form or documentation, if provided along with the
         Derivative Works; or, within a display generated by the Derivative Works, if and
         wherever such third-party notices normally appear.
         
         The contents of the NOTICE file are for informational purposes only and do not
         modify the License. You may add Your own attribution notices within Derivative
         Works that You distribute, alongside or as an addendum to the NOTICE text from
         the Work, provided that such additional attribution notices cannot be construed
         as modifying the License.
         
         You may add Your own copyright statement to Your modifications and may provide
         additional or different license terms and conditions for use, reproduction, or
         distribution of Your modifications, or for any such Derivative Works as a whole,
         provided Your use, reproduction, and distribution of the Work otherwise complies
         with the conditions stated in this License.
         
         5. Submission of Contributions.
         
         Unless You explicitly state otherwise, any Contribution intentionally submitted
         for inclusion in the Work by You to the Licensor shall be under the terms and
         conditions of this License, without any additional terms or conditions.
         
         6. Trademarks.
         
         This License does not grant permission to use the trade names, trademarks,
         service marks, or product names of the Licensor, except as required for
         reasonable and customary use in describing the origin of the Work and reproducing
         the content of the NOTICE file.
         
         7. Disclaimer of Warranty.
         
         Unless required by applicable law or agreed to in writing, Licensor provides the
         Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
         express or implied, including, without limitation, any warranties or conditions
         of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
         You are solely responsible for determining the appropriateness of using or
         redistributing the Work and assume any risks associated with Your exercise of
         permissions under this License.
         
         8. Limitation of Liability.
         
         In no event and under no legal theory, whether in tort (including negligence),
         contract, or otherwise, unless required by applicable law (such as deliberate and
         grossly negligent acts) or agreed to in writing, shall any Contributor be liable
         to You for damages, including any direct, indirect, special, incidental, or
         consequential damages of any character arising as a result of this License or out
         of the use or inability to use the Work.
         
         9. Accepting Warranty or Additional Liability.
         
         While redistributing the Work or Derivative Works thereof, You may choose to
         offer, and charge a fee for, acceptance of support, warranty, indemnity, or other
         liability obligations and/or rights consistent with this License. However, in
         accepting such obligations, You may act only on Your own behalf and on Your sole
         responsibility, not on behalf of any other Contributor.
         
         END OF TERMS AND CONDITIONS
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
Requires-Dist: hvac>=2.0,<3.0
Requires-Dist: apache-airflow>=2.7 ; extra == 'airflow'
Requires-Dist: build>=1.2 ; extra == 'dev'
Requires-Dist: mkdocs>=1.6 ; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: ruff>=0.6 ; extra == 'dev'
Requires-Dist: mypy>=1.10 ; extra == 'dev'
Requires-Dist: twine>=5.1 ; extra == 'dev'
Requires-Dist: types-requests ; extra == 'dev'
Maintainer: PaulKov
Requires-Python: >=3.10
Project-URL: Changelog, https://github.com/PaulKov/vault-kv-client/blob/main/CHANGELOG.md
Project-URL: Documentation, https://paulkov.github.io/vault-kv-client/
Project-URL: Homepage, https://github.com/PaulKov/vault-kv-client
Project-URL: Issues, https://github.com/PaulKov/vault-kv-client/issues
Project-URL: Source, https://github.com/PaulKov/vault-kv-client
Provides-Extra: airflow
Provides-Extra: dev
Description-Content-Type: text/markdown

# vault-kv-client

`vault-kv-client` is a small, typed, and production-friendly helper library for
working with HashiCorp Vault KV engines through `hvac`.

It focuses on the common parts teams end up re-implementing around Vault:

- KV v1 and v2 support with automatic mount version detection
- Token, AppRole, Kubernetes, and Vault JWT/OIDC authentication
- Enterprise namespace support
- Recursive listing and secret copy helpers
- Optional in-memory read caching
- Environment-driven bootstrap for CI, Kubernetes, and legacy Airflow deployments

## Installation

```bash
pip install vault-kv-client
```

With `uv`:

```bash
uv add vault-kv-client
```

With Poetry:

```bash
poetry add vault-kv-client
```

## Quick Start

```python
from vault_kv_client import VaultAuth, VaultManager, VaultSettings

settings = VaultSettings(
    addr="https://vault.example.com",
    verify=True,
    namespace=None,
)

auth = VaultAuth(token="s.xxxxx")
client = VaultManager(settings=settings, auth=auth)

secret = client.get_secret("kv", "apps/my-service")
print(secret["username"])
```

Environment-driven bootstrap is also available:

```python
from vault_kv_client import get_default_manager

client = get_default_manager()
secret = client.get_secret("kv", "apps/my-service")
```

## Public API

Root package exports:

- `VaultManager`
- `VaultSettings`
- `VaultAuth`
- `VaultJWTAuth`
- `VaultKubernetesAuth`
- `VaultClientError`
- `VaultNotConfiguredError`
- `VaultDependencyError`
- `SecretNotFoundError`
- `get_default_manager()`
- `get_creds()`

Core methods:

- `get_secret(mount_point, path, kv_version=None)`
- `upsert_secret(mount_point=..., path=..., secret=..., kv_version=None)`
- `list_secrets(mount_point, path="", kv_version=None)`
- `list_all_secrets(mount_point, path="", kv_version=None)`
- `copy_secret(source_mount=..., target_mount=..., path=...)`
- `clear_cache()`

## Authentication Modes

The library supports four mutually exclusive auth modes:

- `token`
- `approle`
- `kubernetes`
- `jwt`

Full examples are documented in [docs/auth-methods.md](docs/auth-methods.md).

## Legacy Compatibility

The historical package name `vault_client` is still shipped as a temporary
compatibility layer:

```python
from vault_client import VaultManager
```

That import path now emits a `DeprecationWarning`. New projects should use
`vault_kv_client`.

## Documentation

Repository docs are designed for self-service onboarding:

- [Getting Started](docs/getting-started.md)
- [Installation](docs/installation.md)
- [Auth Methods](docs/auth-methods.md)
- [KV v1/v2 Behavior](docs/kv-behavior.md)
- [API Reference](docs/api-reference.md)
- [Migration from `vault_client`](docs/migration-from-vault-client.md)
- [Development](docs/development.md)
- [Security](docs/security.md)
- [Release Process](docs/release-process.md)

The GitHub Pages site is generated from the same sources via MkDocs Material.

## Development

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -U pip uv
uv pip install -e ".[dev]"
ruff check .
mypy src
pytest -q
mkdocs build
```

## Security

- Never log secret payloads.
- Prefer short-lived auth flows where possible.
- Use the minimum Vault policy scope required for your application.
- Report security issues through the process described in [SECURITY.md](SECURITY.md).

## License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
