v0.2.0: release

Author: rnag

.idea/secrets-cache.iml

@@ -1,5 +1,9 @@
 # History
 
+## 0.2.0 (2025-09-13)
+
+* Add core caching logic.
+
 ## 0.1.0 (2025-09-12)
 
 * First release on PyPI.

HISTORY.md

@@ -3,16 +3,108 @@
 ![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.
+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
 
-* TODO
+* 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
 
-This package was created with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [rnag/cookiecutter-pypackage](https://github.com/rnag/cookiecutter-pypackage) project template.
+Created with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [rnag/cookiecutter-pypackage](https://github.com/rnag/cookiecutter-pypackage) template.

README.md

@@ -1,6 +1,6 @@
 [project]
 name = "secrets-cache"
-version = "0.1.0"
+version = "0.2.0"
 description = "Cache secrets locally from AWS Secrets Manager and other secret stores."
 readme = "README.md"
 authors = [
@@ -9,15 +9,15 @@ authors = [
 maintainers = [
   {name = "Ritvik Nag", email = "me@ritviknag.com"}
 ]
+keywords = ["aws", "secrets", "ssm", "cache", "lambda"]
 classifiers = [
     # TODO
     # Ref: https://pypi.org/classifiers/
     # 'Development Status :: 5 - Production/Stable',
-    # 'Development Status :: 4 - Beta',
-    'Development Status :: 2 - Pre-Alpha',
+    'Development Status :: 4 - Beta',
     'Intended Audience :: Developers',
-    'License :: OSI Approved :: MIT License',
     'Natural Language :: English',
+    'License :: OSI Approved :: MIT License',
     'Programming Language :: Python',
     'Programming Language :: Python :: 3',
     'Programming Language :: Python :: 3.10',
@@ -29,12 +29,20 @@ classifiers = [
     'Topic :: Software Development',
 ]
 license = {text = "MIT"}
-dependencies = [
-  "typer"
-]
+# Base dependencies (always installed)
+dependencies = []
 requires-python = ">= 3.10"
 
 [project.optional-dependencies]
+cli = [
+    'typer',  # CLI / optional but handy
+]
+local = [
+    'boto3>=1.26',  # AWS SDK for fetching secrets
+    'tomli>=2.0; python_version<"3.11"',  # TOML reader for Python <3.11
+    'tomli-w>=1.0; python_version<"3.11"',  # TOML writer for Python <3.11
+]
+lambda = []              # Lambda-friendly, skips boto3
 test = [
     "coverage",  # testing
     "pytest",  # testing

pyproject.toml

@@ -1,4 +1,7 @@
-"""Top-level package for Secrets Cache."""
+"""Secrets Cache Library - get AWS secrets and SSM parameters with optional caching."""
+from ._aws import get_secret, get_param
+
+__all__ = ["get_secret", "get_param"]
 
 __author__ = """Ritvik Nag"""
 __email__ = 'me@ritviknag.com'

src/secrets_cache/__init__.py

@@ -0,0 +1,88 @@
+"""Main module."""
+
+from pathlib import Path
+
+import boto3
+
+from ._cache import cached_fetch
+
+
+# Optional: import TOML only if available
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    try:
+        import tomli as tomllib  # Python 3.10
+    except ImportError:
+        tomllib = None
+
+try:
+    import tomli_w
+except ImportError:
+    tomli_w = None
+
+
+# Module-level caches
+_secret_cache = {}
+_param_cache = {}
+_boto_clients = {}
+
+# TOML cache file (optional)
+_CACHE_FILE = Path.home() / '.secrets_cache.toml'
+
+
+def get_boto_client(service: str, region: str = 'us-east-1'):
+    """Cache boto3 clients per service/region."""
+    key = service, region
+    _client = _boto_clients.get(key)
+    if _client is None:
+        _boto_clients[key] = _client = boto3.client(service, region_name=region)
+    return _client
+
+
+def _read_toml_cache():
+    if not tomllib or not _CACHE_FILE.exists():
+        return {}
+    with _CACHE_FILE.open('rb') as f:
+        return tomllib.load(f)
+
+
+def _write_toml_cache(data):
+    if not tomli_w or not _CACHE_FILE.parent.exists():
+        return
+    with _CACHE_FILE.open('wb') as f:
+        tomli_w.dump(data, f)
+
+
+def get_secret(name: str, region: str = 'us-east-1', ttl: int = 7 * 24 * 3600):
+    """Get secret from AWS Secrets Manager with optional caching."""
+    return cached_fetch(_secret_cache, name, region, _fetch_secret, ttl)
+
+
+def get_param(name: str, region: str = 'us-east-1', ttl: int = 7 * 24 * 3600):
+    """Get parameter from AWS SSM Parameter Store with optional caching."""
+    return cached_fetch(_param_cache, name, region, _fetch_param, ttl)
+
+
+def _fetch_secret(name: str, region: str = 'us-east-1'):
+    client = get_boto_client('secretsmanager', region)
+    resp = client.get_secret_value(SecretId=name)
+    value = resp['SecretString']
+
+    # Update local TOML cache if available
+    data = _read_toml_cache()
+    data[name] = value
+    _write_toml_cache(data)
+    return value
+
+
+def _fetch_param(name: str, region: str = 'us-east-1'):
+    client = get_boto_client('ssm', region)
+    resp = client.get_parameter(Name=name, WithDecryption=True)
+    value = resp['Parameter']['Value']
+
+    # Update local TOML cache if available
+    data = _read_toml_cache()
+    data[name] = value
+    _write_toml_cache(data)
+    return value

src/secrets_cache/_aws.py

@@ -0,0 +1,13 @@
+from time import time
+
+
+def cached_fetch(cache: dict, key: str, region: str, fetcher, ttl: int):
+    """Fetch from cache or call fetcher."""
+    now = time()
+    entry = cache.get(key)
+    if entry and (now - entry['fetched_at'] < ttl):
+        return entry['value']
+
+    value = fetcher(key, region)
+    cache[key] = {'value': value, 'fetched_at': now}
+    return value

src/secrets_cache/_cache.py

@@ -3,7 +3,6 @@
 import typer
 from rich.console import Console
 
-from secrets_cache import utils
 
 app = typer.Typer()
 console = Console()
@@ -15,7 +14,7 @@ def main():
     console.print("Replace this message by putting your code into "
                "secrets_cache.cli.main")
     console.print("See Typer documentation at https://typer.tiangolo.com/")
-    utils.do_something_useful()
+    # utils.do_something_useful()
 
 
 if __name__ == "__main__":