Metadata-Version: 2.4
Name: secrets-cache
Version: 0.2.0
Summary: Cache secrets locally from AWS Secrets Manager and other secret stores.
Author-email: Ritvik Nag <me@ritviknag.com>
Maintainer-email: Ritvik Nag <me@ritviknag.com>
License: MIT
Project-URL: bugs, https://github.com/rnag/py-secrets-cache/issues
Project-URL: changelog, https://github.com/rnag/py-secrets-cache/blob/master/changelog.md
Project-URL: homepage, https://github.com/rnag/py-secrets-cache
Keywords: aws,secrets,ssm,cache,lambda
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
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 :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: cli
Requires-Dist: typer; extra == "cli"
Provides-Extra: local
Requires-Dist: boto3>=1.26; extra == "local"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "local"
Requires-Dist: tomli-w>=1.0; python_version < "3.11" and extra == "local"
Provides-Extra: lambda
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: ruff; extra == "test"
Requires-Dist: ty; extra == "test"
Requires-Dist: ipdb; extra == "test"
Dynamic: license-file

# Secrets Cache

![PyPI version](https://img.shields.io/pypi/v/secrets-cache.svg)
[![Documentation Status](https://readthedocs.org/projects/secrets-cache/badge/?version=latest)](https://secrets-cache.readthedocs.io/en/latest/?version=latest)

Cache secrets locally from AWS Secrets Manager and other secret stores, with optional local caching for development or Lambda-friendly usage.

* PyPI package: https://pypi.org/project/secrets-cache/
* Free software: MIT License
* Documentation: https://secrets-cache.readthedocs.io.

## Installation

Install the base package (minimal, Lambda-friendly):

```bash
pip install secrets-cache[lambda]
````

Install with **local cache support** (TOML) for testing / development:

```bash
pip install secrets-cache[local]
```

Install with CLI support:

```bash
pip install secrets-cache[cli]
```

You can also combine extras:

```bash
pip install "secrets-cache[local,cli]"
```

## Usage

```python
from secrets_cache import get_secret, get_param

# Get a secret from AWS Secrets Manager
my_secret = get_secret("my-secret-name", region="us-east-1")

# Get a parameter from AWS SSM Parameter Store
my_param = get_param("/my/parameter/name", region="us-east-1")
```

**Notes:**

* By default, secrets are cached **in memory** to reduce repeated AWS calls.
* If `local` extra is installed, secrets are also stored in `~/.secrets_cache.toml` for local caching.
* Module-level caches persist across **warm AWS Lambda invocations**, so repeated calls in the same container are very fast.

## Features

* Fetch secrets and parameters from AWS Secrets Manager / SSM.
* Module-level caching for in-process efficiency.
* Optional TOML caching for development.
* Lambda-friendly usage without extra dependencies.
* Easy to extend to other secret stores in the future.

## Getting Started: AWS Lambda

When running in AWS Lambda, you usually don’t want file-based caching. Use the `lambda` extra:

```bash
pip install secrets-cache[lambda]
````

### Example Lambda handler

```python
import json
from secrets_cache import get_secret, get_param

def lambda_handler(event, context):
    # Get a secret from AWS Secrets Manager
    db_password = get_secret("my-db-password", region="us-east-1")

    # Get a parameter from AWS SSM Parameter Store
    api_key = get_param("/my/api/key", region="us-east-1")

    # Do something with your secrets
    return {
        "statusCode": 200,
        "body": json.dumps({
            "db_password_length": len(db_password),
            "api_key_length": len(api_key)
        })
    }
```

### Notes for Lambda

* **Module-level caching** ensures repeated calls in the same container are very fast.
* No TOML or local file access is required — perfect for ephemeral Lambda environments.
* Secrets are cached **in memory only**, and each new container start fetches them from AWS.
* If you want local development caching, install the `local` extra:

```bash
pip install secrets-cache[local]
```

This enables optional `~/.secrets_cache.toml` caching for local testing.

## Credits

Created with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [rnag/cookiecutter-pypackage](https://github.com/rnag/cookiecutter-pypackage) template.
