{"id":31078110,"url":"https://github.com/rnag/py-secrets-cache","last_synced_at":"2026-01-20T17:35:43.492Z","repository":{"id":314546594,"uuid":"1055915211","full_name":"rnag/py-secrets-cache","owner":"rnag","description":"In-memory caching for AWS Secrets Manager / SSM in Lambda, with optional file-based cache for local use.","archived":false,"fork":false,"pushed_at":"2025-09-15T04:18:45.000Z","size":82,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T07:22:09.138Z","etag":null,"topics":["aws","aws-lambda","aws-secrets-manager","aws-secretsmanager","aws-ssm","aws-ssm-parameter-store","aws-ssm-parameters","cache","lambda","secrets","ssm","ssm-parameter-store"],"latest_commit_sha":null,"homepage":"https://secrets-cache.ritviknag.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnag.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-13T03:17:46.000Z","updated_at":"2025-09-15T12:57:45.000Z","dependencies_parsed_at":"2025-09-13T06:31:01.097Z","dependency_job_id":"79907960-14e7-418b-82f3-ac0503c70b83","html_url":"https://github.com/rnag/py-secrets-cache","commit_stats":null,"previous_names":["rnag/py-secrets-cache"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rnag/py-secrets-cache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Fpy-secrets-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Fpy-secrets-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Fpy-secrets-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Fpy-secrets-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnag","download_url":"https://codeload.github.com/rnag/py-secrets-cache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnag%2Fpy-secrets-cache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278671795,"owners_count":26025757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","aws-secrets-manager","aws-secretsmanager","aws-ssm","aws-ssm-parameter-store","aws-ssm-parameters","cache","lambda","secrets","ssm","ssm-parameter-store"],"created_at":"2025-09-16T08:03:36.317Z","updated_at":"2025-10-06T20:13:38.832Z","avatar_url":"https://github.com/rnag.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--intro-start--\u003e\n\n# Secrets Cache\n\n[![PyPI version](https://img.shields.io/pypi/v/secrets-cache.svg)](https://pypi.org/project/secrets-cache/)\n[![PyPI license](https://img.shields.io/pypi/l/secrets-cache.svg)](https://pypi.org/project/secrets-cache/)\n[![PyPI Python versions](https://img.shields.io/pypi/pyversions/secrets-cache.svg)](https://pypi.org/project/secrets-cache/)\n[![GitHub Actions](https://github.com/rnag/py-secrets-cache/actions/workflows/release.yml/badge.svg)](https://github.com/rnag/py-secrets-cache/actions/workflows/release.yml)\n[![Documentation Status](https://github.com/rnag/py-secrets-cache/actions/workflows/gh-pages.yml/badge.svg)](https://secrets-cache.ritviknag.com)\n\nCache secrets from **AWS Secrets Manager** and other stores **in-memory** — ideal for AWS Lambda and ephemeral environments.\nWith the `[local]` extra, you also get optional **file-based caching** (TOML) for local development.\n\n\u003e [!TIP]\n\u003e 💡 See [secrets-cache-cdk-example](https://github.com/rnag/secrets-cache-cdk-example)\n\u003e for a ready-to-deploy AWS Lambda + CDK project showcasing `secrets-cache` with\n\u003e Secrets Manager and SSM Parameters, including caching timings.\n\n📖 [Docs / README website](https://secrets-cache.ritviknag.com) – mirrors this README exactly, with navigation and search\n\n⭐ Star the project on [GitHub](https://github.com/rnag/py-secrets-cache) if you find it useful!\n\n## Installation\n\nInstall the minimal, Lambda-friendly package [on PyPI](https://pypi.org/project/secrets-cache):\n\n```bash\npip install secrets-cache[lambda]\n```\n\nFor local development or testing (file-based cache + AWS SDK):\n\n```bash\npip install secrets-cache[local]\n```\n\nOptional CLI tools:\n\n```bash\npip install secrets-cache[cli]\n```\n\n## Usage\n\n### Fetch a secret from AWS Secrets Manager\n\n```python\nfrom secrets_cache import get_secret\n\n# Returns JSON-decoded dict if possible\ndb_creds = get_secret(\"prod/AppBeta/MySQL\")\n\n# Returns raw string\nraw_value = get_secret(\"prod/AppBeta/MySQL\", raw=True)\n\n# Force refresh from AWS, ignoring cache\nfresh_value = get_secret(\"prod/AppBeta/MySQL\", force_refresh=True)\n```\n\n### Fetch a parameter from AWS SSM Parameter Store\n\n```python\nfrom secrets_cache import get_param\n\napi_url = get_param(\"prod/AppBeta/API_URL\")\n```\n\n**Notes:**\n\n* Secrets and parameters are **cached in-memory** and optionally in a **local TOML file** (`~/.secrets_cache.toml`) for repeated calls.\n* Default cache TTL is **1 week** (configurable via `SECRETS_CACHE_TTL` environment variable).\n* AWS region defaults to `AWS_REGION` environment variable or `us-east-1`.\n* Module-level caches persist across **warm AWS Lambda invocations**, so repeated calls in the same container are very fast.\n\n## Features\n\n* Fetch secrets and parameters from AWS Secrets Manager / SSM.\n* Module-level caching for in-process efficiency.\n* Optional TOML caching for development.\n* Lambda-friendly usage without extra dependencies.\n* Easy to extend to other secret stores in the future.\n\n## Getting Started: AWS Lambda\n\nWhen running in AWS Lambda, you usually don’t want file-based caching. Use the `lambda` extra:\n\n```bash\npip install secrets-cache[lambda]\n```\n\n### Example Lambda handler\n\n```python\nimport json\nfrom secrets_cache import get_secret, get_param\n\ndef lambda_handler(event, context):\n    # Get a secret from AWS Secrets Manager\n    db_password = get_secret(\"my-db-password\", region=\"us-east-1\")\n\n    # Get a parameter from AWS SSM Parameter Store\n    api_key = get_param(\"/my/api/key\", region=\"us-east-1\")\n\n    # Do something with your secrets\n    return {\n        \"statusCode\": 200,\n        \"body\": json.dumps({\n            \"db_password_length\": len(db_password),\n            \"api_key_length\": len(api_key)\n        })\n    }\n```\n\n### Notes for Lambda\n\n* **Module-level caching** ensures repeated calls in the same container are very fast.\n* No TOML or local file access is required — perfect for ephemeral Lambda environments.\n* Secrets are cached **in memory only**, and each new container start fetches them from AWS.\n* If you want local development caching, install the `local` extra:\n\n```bash\npip install secrets-cache[local]\n```\n\nThis enables optional `~/.secrets_cache.toml` caching for local testing.\n\n## AWS CDK Example\n\nI've created a small **AWS CDK Python project** that demonstrates how to use `secrets-cache` in an AWS Lambda function.\n\n**Repository:** [secrets-cache-cdk-example](https://github.com/rnag/secrets-cache-cdk-example)\n\nThis example shows:\n\n* How to deploy a Lambda function using CDK that automatically installs `secrets-cache`.\n* How to fetch **Secrets Manager secrets** and **SSM parameters** from Lambda.\n* How module-level caching in `secrets-cache` speeds up repeated fetches in warm Lambda containers.\n* How to log fetch times in milliseconds to observe caching in action.\n\n### Quickstart\n\n1. Sign up for an [AWS account](https://aws.amazon.com/free/) (free tier is sufficient).\n2. Install the [AWS CLI](https://aws.amazon.com/cli/) and run:\n\n```bash\naws configure\n```\n\n3. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) (needed for CDK bundling).\n4. Clone the example repo:\n\n```bash\ngit clone https://github.com/rnag/secrets-cache-cdk-example\ncd secrets-cache-cdk-example\n```\n\n5. Install dependencies and activate the virtual environment:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n6. If this is your first CDK deployment in the account, bootstrap it:\n\n```bash\ncdk bootstrap\n```\n\n7. Deploy the stack:\n\n```bash\ncdk deploy\n```\n\n8. Invoke the Lambda and see **timings for secret/parameter fetches** in real time:\n\n```bash\naws lambda invoke \\\n  --function-name CdkExampleStack-TestLambda \\\n  --log-type Tail \\\n  --query 'LogResult' \\\n  --output text |  base64 --decode\n```\n\nLogs will show how fast the secret and parameter are fetched, demonstrating caching between warm starts.\n\n## Credits\n\nCreated with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [rnag/cookiecutter-pypackage](https://github.com/rnag/cookiecutter-pypackage) template.\n\n\u003c!--intro-end--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnag%2Fpy-secrets-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnag%2Fpy-secrets-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnag%2Fpy-secrets-cache/lists"}