## AWS Secrets Manager Python caching client
[](https://github.com/aws/aws-secretsmanager-caching-python/actions/workflows/python-package.yml)
[](https://codecov.io/github/aws/aws-secretsmanager-caching-python)
The AWS Secrets Manager Python caching client enables in-process caching of secrets for Python applications.
## Getting Started
### Required Prerequisites
To use this client you must have:
* Python 3.7 or newer. Use of Python versions 3.6 or older are not supported.
* An Amazon Web Services (AWS) account to access secrets stored in AWS Secrets Manager.
* **To create an AWS account**, go to [Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) and then choose **I am a new user.** Follow the instructions to create an AWS account.
* **To create a secret in AWS Secrets Manager**, go to [Creating Secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) and follow the instructions on that page.
* This library makes use of botocore, the low-level core functionality of the boto3 SDK. For more information on boto3 and botocore, please review the [AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) and [Botocore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) documentation.
### Dependencies
This library requires the following standard dependencies:
* botocore
* setuptools_scm
For development and testing purposes, this library requires the following additional dependencies:
* pytest
* pytest-cov
* pytest-sugar
* codecov
* pylint
* sphinx
Please review the `requirements.txt` and `dev-requirements.txt` file for specific version requirements.
### Installation
Installing the latest release via **pip**:
```bash
$ pip install aws-secretsmanager-caching
```
Installing the latest development release:
```bash
$ git clone https://github.com/aws/aws-secretsmanager-caching-python.git
$ cd aws-secretsmanager-caching-python
$ python setup.py install
```
### Development
#### Getting Started
Assuming that you have Python and virtualenv installed, set up your environment and install the required dependencies like this instead of the `pip install aws_secretsmanager_caching` defined above:
```bash
$ git clone https://github.com/aws/aws-secretsmanager-caching-python.git
$ cd aws-secretsmanager-caching-python
$ virtualenv venv
...
$ . venv/bin/activate
$ pip install -r requirements.txt -r dev-requirements.txt
$ pip install -e .
```
#### Running Tests
You can run tests in all supported Python versions using tox. By default, it will run all of the unit and integration tests, but you can also specify your own arguments to past to `pytest`.
```bash
$ tox # runs integ/unit tests, flake8 tests and pylint tests
$ tox -- test/unit/test_decorators.py # runs specific test file
$ tox -e py37 -- test/integ/ # runs specific test directory
```
#### Documentation
You can locally-generate the Sphinx-based documentation via:
```bash
$ tox -e docs
```
Which will subsequently be viewable at `file://${CLONE_DIR}/.tox/docs_out/index.html`
### Usage
Using the client consists of the following steps:
1. Instantiate the client while optionally passing in a `SecretCacheConfig()` object to the `config` parameter. You can also pass in an existing `botocore.client.BaseClient` client to the client parameter.
2. Request the secret from the client instance.
```python
import botocore
import botocore.session
from aws_secretsmanager_caching import SecretCache, SecretCacheConfig
client = botocore.session.get_session().create_client('secretsmanager')
cache_config = SecretCacheConfig() # See below for defaults
cache = SecretCache(config=cache_config, client=client)
secret = cache.get_secret_string('mysecret')
```
#### Cache Configuration
You can configure the cache config object with the following parameters:
* `max_cache_size` - The maximum number of secrets to cache. The default value is `1024`.
* `exception_retry_delay_base` - The number of seconds to wait after an exception is encountered and before retrying the request. The default value is `1`.
* `exception_retry_growth_factor` - The growth factor to use for calculating the wait time between retries of failed requests. The default value is `2`.
* `exception_retry_delay_max` - The maximum amount of time in seconds to wait between failed requests. The default value is `3600`.
* `default_version_stage` - The default version stage to request. The default value is `'AWSCURRENT'`
* `secret_refresh_interval` - The number of seconds to wait between refreshing cached secret information. The default value is `3600.0`.
* `secret_cache_hook` - An implementation of the SecretCacheHook abstract class. The default value is `None`.
#### Decorators
The library also includes several decorator functions to wrap existing function calls with SecretString-based secrets:
* `@InjectedKeywordedSecretString` - This decorator expects the secret id and cache as the first and second arguments, with subsequent arguments mapping a parameter key from the function that is being wrapped to a key in the secret. The secret being retrieved from the cache must contain a SecretString and that string must be JSON-based.
* `@InjectSecretString` - This decorator also expects the secret id and cache as the first and second arguments. However, this decorator simply returns the result of the cache lookup directly to the first argument of the wrapped function. The secret does not need to be JSON-based but it must contain a SecretString.
```python
from aws_secretsmanager_caching import SecretCache
from aws_secretsmanager_caching import InjectKeywordedSecretString, InjectSecretString
cache = SecretCache()
@InjectKeywordedSecretString(secret_id='mysecret', cache=cache, func_username='username', func_password='password')
def function_to_be_decorated(func_username, func_password):
print('Something cool is being done with the func_username and func_password arguments here')
...
@InjectSecretString('mysimplesecret', cache)
def function_to_be_decorated(arg1, arg2, arg3):
# arg1 contains the cache lookup result of the 'mysimplesecret' secret.
# arg2 and arg3, in this example, must still be passed when calling function_to_be_decorated().
```
## Getting Help
We use GitHub issues for tracking bugs and caching library feature requests and have limited bandwidth to address them. Please use these community resources for getting help:
* Ask a question on [Stack Overflow](https://stackoverflow.com/) and tag it with [aws-secrets-manager](https://stackoverflow.com/questions/tagged/aws-secrets-manager).
* Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/)
* if it turns out that you may have found a bug, please [open an issue](https://github.com/aws/aws-secretsmanager-caching-python/issues/new).
## License
This library is licensed under the Apache 2.0 License.
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-secretsmanager-caching-python",
"name": "aws-secretsmanager-caching",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.5",
"maintainer_email": null,
"keywords": "secretsmanager secrets manager development cache caching client",
"author": "Amazon Web Services",
"author_email": "aws-secretsmanager-dev@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/8e/e1/d05d08f450035cc83e6822e5cf311b44ac91d271dc3533492996c0ca860a/aws_secretsmanager_caching-1.1.2.tar.gz",
"platform": null,
"description": "## AWS Secrets Manager Python caching client\n\n[](https://github.com/aws/aws-secretsmanager-caching-python/actions/workflows/python-package.yml)\n[](https://codecov.io/github/aws/aws-secretsmanager-caching-python)\n\nThe AWS Secrets Manager Python caching client enables in-process caching of secrets for Python applications.\n\n## Getting Started\n\n### Required Prerequisites\n\nTo use this client you must have:\n\n* Python 3.7 or newer. Use of Python versions 3.6 or older are not supported.\n* An Amazon Web Services (AWS) account to access secrets stored in AWS Secrets Manager.\n * **To create an AWS account**, go to [Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) and then choose **I am a new user.** Follow the instructions to create an AWS account.\n\n * **To create a secret in AWS Secrets Manager**, go to [Creating Secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) and follow the instructions on that page.\n\n * This library makes use of botocore, the low-level core functionality of the boto3 SDK. For more information on boto3 and botocore, please review the [AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) and [Botocore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) documentation. \n\n### Dependencies\nThis library requires the following standard dependencies:\n* botocore\n* setuptools_scm\n\nFor development and testing purposes, this library requires the following additional dependencies:\n* pytest\n* pytest-cov\n* pytest-sugar\n* codecov\n* pylint\n* sphinx\n\nPlease review the `requirements.txt` and `dev-requirements.txt` file for specific version requirements.\n\n### Installation\nInstalling the latest release via **pip**:\n```bash\n$ pip install aws-secretsmanager-caching\n```\n\nInstalling the latest development release:\n```bash\n$ git clone https://github.com/aws/aws-secretsmanager-caching-python.git\n$ cd aws-secretsmanager-caching-python\n$ python setup.py install\n```\n\n### Development\n#### Getting Started\nAssuming that you have Python and virtualenv installed, set up your environment and install the required dependencies like this instead of the `pip install aws_secretsmanager_caching` defined above:\n\n```bash\n$ git clone https://github.com/aws/aws-secretsmanager-caching-python.git\n$ cd aws-secretsmanager-caching-python\n$ virtualenv venv\n...\n$ . venv/bin/activate\n$ pip install -r requirements.txt -r dev-requirements.txt\n$ pip install -e .\n```\n\n#### Running Tests\nYou can run tests in all supported Python versions using tox. By default, it will run all of the unit and integration tests, but you can also specify your own arguments to past to `pytest`.\n```bash\n$ tox # runs integ/unit tests, flake8 tests and pylint tests\n$ tox -- test/unit/test_decorators.py # runs specific test file\n$ tox -e py37 -- test/integ/ # runs specific test directory\n```\n\n#### Documentation\nYou can locally-generate the Sphinx-based documentation via:\n```bash\n$ tox -e docs\n```\nWhich will subsequently be viewable at `file://${CLONE_DIR}/.tox/docs_out/index.html`\n\n### Usage\nUsing the client consists of the following steps:\n1. Instantiate the client while optionally passing in a `SecretCacheConfig()` object to the `config` parameter. You can also pass in an existing `botocore.client.BaseClient` client to the client parameter.\n2. Request the secret from the client instance.\n```python\nimport botocore\nimport botocore.session\nfrom aws_secretsmanager_caching import SecretCache, SecretCacheConfig\n\nclient = botocore.session.get_session().create_client('secretsmanager')\ncache_config = SecretCacheConfig() # See below for defaults\ncache = SecretCache(config=cache_config, client=client)\n\nsecret = cache.get_secret_string('mysecret')\n```\n\n#### Cache Configuration\nYou can configure the cache config object with the following parameters:\n* `max_cache_size` - The maximum number of secrets to cache. The default value is `1024`.\n* `exception_retry_delay_base` - The number of seconds to wait after an exception is encountered and before retrying the request. The default value is `1`.\n* `exception_retry_growth_factor` - The growth factor to use for calculating the wait time between retries of failed requests. The default value is `2`.\n* `exception_retry_delay_max` - The maximum amount of time in seconds to wait between failed requests. The default value is `3600`.\n* `default_version_stage` - The default version stage to request. The default value is `'AWSCURRENT'`\n* `secret_refresh_interval` - The number of seconds to wait between refreshing cached secret information. The default value is `3600.0`.\n* `secret_cache_hook` - An implementation of the SecretCacheHook abstract class. The default value is `None`.\n\n#### Decorators\nThe library also includes several decorator functions to wrap existing function calls with SecretString-based secrets:\n* `@InjectedKeywordedSecretString` - This decorator expects the secret id and cache as the first and second arguments, with subsequent arguments mapping a parameter key from the function that is being wrapped to a key in the secret. The secret being retrieved from the cache must contain a SecretString and that string must be JSON-based.\n* `@InjectSecretString` - This decorator also expects the secret id and cache as the first and second arguments. However, this decorator simply returns the result of the cache lookup directly to the first argument of the wrapped function. The secret does not need to be JSON-based but it must contain a SecretString.\n```python\nfrom aws_secretsmanager_caching import SecretCache\nfrom aws_secretsmanager_caching import InjectKeywordedSecretString, InjectSecretString\n\ncache = SecretCache()\n\n@InjectKeywordedSecretString(secret_id='mysecret', cache=cache, func_username='username', func_password='password')\ndef function_to_be_decorated(func_username, func_password):\n print('Something cool is being done with the func_username and func_password arguments here')\n ...\n\n@InjectSecretString('mysimplesecret', cache)\ndef function_to_be_decorated(arg1, arg2, arg3):\n # arg1 contains the cache lookup result of the 'mysimplesecret' secret.\n # arg2 and arg3, in this example, must still be passed when calling function_to_be_decorated().\n```\n\n## Getting Help\nWe use GitHub issues for tracking bugs and caching library feature requests and have limited bandwidth to address them. Please use these community resources for getting help:\n* Ask a question on [Stack Overflow](https://stackoverflow.com/) and tag it with [aws-secrets-manager](https://stackoverflow.com/questions/tagged/aws-secrets-manager).\n* Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/)\n* if it turns out that you may have found a bug, please [open an issue](https://github.com/aws/aws-secretsmanager-caching-python/issues/new). \n## License\n\nThis library is licensed under the Apache 2.0 License. \n",
"bugtrack_url": null,
"license": null,
"summary": "Client-side AWS Secrets Manager caching library",
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/aws/aws-secretsmanager-caching-python"
},
"split_keywords": [
"secretsmanager",
"secrets",
"manager",
"development",
"cache",
"caching",
"client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5baee0ca1b36056b6aaffc4e70c26a4c4fabdf4fca3e00a0098ea6ec100225f1",
"md5": "f6e3aac4af39a935f160b1997b6c88ab",
"sha256": "3fb66b2728cb9f2f015bfd56c5f41e4878e838659a1b0ade1439d971d5ce169e"
},
"downloads": -1,
"filename": "aws_secretsmanager_caching-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6e3aac4af39a935f160b1997b6c88ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.5",
"size": 18134,
"upload_time": "2024-03-29T21:49:09",
"upload_time_iso_8601": "2024-03-29T21:49:09.737759Z",
"url": "https://files.pythonhosted.org/packages/5b/ae/e0ca1b36056b6aaffc4e70c26a4c4fabdf4fca3e00a0098ea6ec100225f1/aws_secretsmanager_caching-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ee1d05d08f450035cc83e6822e5cf311b44ac91d271dc3533492996c0ca860a",
"md5": "96cc4fd0cb1f004d59c51ba27780b882",
"sha256": "861768f88d7203fa4b03e6050c58bc124aefdbbc502e9c62a97875fb85eab5e0"
},
"downloads": -1,
"filename": "aws_secretsmanager_caching-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "96cc4fd0cb1f004d59c51ba27780b882",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.5",
"size": 26705,
"upload_time": "2024-03-29T21:50:29",
"upload_time_iso_8601": "2024-03-29T21:50:29.761618Z",
"url": "https://files.pythonhosted.org/packages/8e/e1/d05d08f450035cc83e6822e5cf311b44ac91d271dc3533492996c0ca860a/aws_secretsmanager_caching-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 21:50:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-secretsmanager-caching-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "botocore",
"specs": [
[
">=",
"1.12"
]
]
},
{
"name": "setuptools_scm",
"specs": [
[
">=",
"3.2"
]
]
}
],
"tox": true,
"lcname": "aws-secretsmanager-caching"
}
JSON
