# Get a Secrets Manager secret value using Python with client-side caching
<a name="retrieving-secrets_cache-python"></a>

When you retrieve a secret, you can use the Secrets Manager Python-based caching component to cache it for future use. Retrieving a cached secret is faster than retrieving it from Secrets Manager. Because there is a cost for calling Secrets Manager APIs, using a cache can reduce your costs. For all of the ways you can retrieve secrets, see [Get secrets](retrieving-secrets.md).

The cache policy is Least Recently Used (LRU), so when the cache must discard a secret, it discards the least recently used secret. By default, the cache refreshes secrets every hour. You can configure [how often the secret is refreshed](retrieving-secrets_cache-ref-secretcacheconfig.md) in the cache, and you can [hook into the secret retrieval](retrieving-secrets_cache-ref-secretcachehook.md) to add more functionality.

The cache does not force garbage collection once cache references are freed. The cache implementation does not include cache invalidation. The cache implementation is focused around the cache itself, and is not security hardened or focused. If you require additional security such as encrypting items in the cache, use the interfaces and abstract methods provided.

To use the component, you must have the following: 
+ Python 3.6 or later.
+ botocore 1.12 or higher. See [AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) and [Botocore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html). 
+ setuptools\$1scm 3.2 or higher. See [https://pypi.org/project/setuptools-scm/](https://pypi.org/project/setuptools-scm/).

To download the source code, see [Secrets Manager Python-based caching client component](https://github.com/aws/aws-secretsmanager-caching-python ) on GitHub.

To install the component, use the following command.

```
$ pip install aws-secretsmanager-caching
```

**Required permissions: **
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

For more information, see [Permissions reference](auth-and-access.md#reference_iam-permissions).

**Topics**
+ [

# SecretCache
](retrieving-secrets_cache-ref-secretcache.md)
+ [

# SecretCacheConfig
](retrieving-secrets_cache-ref-secretcacheconfig.md)
+ [

# SecretCacheHook
](retrieving-secrets_cache-ref-secretcachehook.md)
+ [

# @InjectSecretString
](retrieving-secrets_cache-decor-string.md)
+ [

# @InjectKeywordedSecretString
](retrieving-secrets_cache-decor-keyword.md)

**Example Retrieve a secret**  
The following example shows how to get the secret value for a secret named *mysecret*.  

```
import botocore 
import botocore.session 
from aws_secretsmanager_caching import SecretCache, SecretCacheConfig 

client = botocore.session.get_session().create_client('secretsmanager')
cache_config = SecretCacheConfig()
cache = SecretCache( config = cache_config, client = client)

secret = cache.get_secret_string('mysecret')
```

# SecretCache
<a name="retrieving-secrets_cache-ref-secretcache"></a>

An in-memory cache for secrets retrieved from Secrets Manager. You use [get\$1secret\$1string](#retrieving-secrets_cache-ref-secretcache_get_secret_string) or [get\$1secret\$1binary](#retrieving-secrets_cache-ref-secretcache_get_secret_binary) to retrieve a secret from the cache. You can configure the cache settings by passing in a [SecretCacheConfig](retrieving-secrets_cache-ref-secretcacheconfig.md) object in the constructor. 

For more information, including examples, see [Get a Secrets Manager secret value using Python with client-side caching](retrieving-secrets_cache-python.md).

```
cache = SecretCache(
    config = SecretCacheConfig,
    client = [client](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html)
)
```

**Topics**
+ [

## get\$1secret\$1string
](#retrieving-secrets_cache-ref-secretcache_get_secret_string)
+ [

## get\$1secret\$1binary
](#retrieving-secrets_cache-ref-secretcache_get_secret_binary)

## get\$1secret\$1string
<a name="retrieving-secrets_cache-ref-secretcache_get_secret_string"></a>

Retrieves the secret string value.

Request syntax  

```
response = cache.get_secret_string(
    secret_id='string',
    version_stage='string' )
```

Parameters  
+ `secret_id` (*string*): [Required] The name or ARN of the secret.
+ `version_stage` (*string*): The version of secrets that you want to retrieve. For more information, see [secret versions](whats-in-a-secret.md). The default is 'AWSCURRENT'. 

Return type  
string

## get\$1secret\$1binary
<a name="retrieving-secrets_cache-ref-secretcache_get_secret_binary"></a>

Retrieves the secret binary value.

Request syntax  

```
response = cache.get_secret_binary(
    secret_id='string',
    version_stage='string'
)
```

Parameters  
+ `secret_id` (*string*): [Required] The name or ARN of the secret.
+ `version_stage` (*string*): The version of secrets that you want to retrieve. For more information, see [secret versions](whats-in-a-secret.md). The default is 'AWSCURRENT'. 

Return type  
[base64-encoded](https://tools.ietf.org/html/rfc4648#section-4) string

# SecretCacheConfig
<a name="retrieving-secrets_cache-ref-secretcacheconfig"></a>

Cache configuration options for a [SecretCache](retrieving-secrets_cache-ref-secretcache.md) such as max cache size and Time to Live (TTL) for cached secrets.Parameters

`max_cache_size` (*int*)  
The maximum cache size. The default is `1024` secrets. 

`exception_retry_delay_base` (*int*)  
The number of seconds to wait after an exception is encountered before retrying the request. The default is `1`.

`exception_retry_growth_factor` (*int*)pur  
The growth factor to use for calculating the wait time between retries of failed requests. The default is `2`. 

`exception_retry_delay_max` (*int*)  
The maximum amount of time in seconds to wait between failed requests. The default is `3600`.

`default_version_stage` (*str*)  
The version of secrets that you want to cache. For more information, see [Secret versions](whats-in-a-secret.md#term_version). The default is `'AWSCURRENT'`.

`secret_refresh_interval` (*int*)  
The number of seconds to wait between refreshing cached secret information. The default is `3600`.

`secret_cache_hook` (*SecretCacheHook*)  
An implementation of the `SecretCacheHook` abstract class. The default value is `None`.

# SecretCacheHook
<a name="retrieving-secrets_cache-ref-secretcachehook"></a>

An interface to hook into a [SecretCache](retrieving-secrets_cache-ref-secretcache.md) to perform actions on the secrets being stored in the cache. 

**Topics**
+ [

## put
](#retrieving-secrets_cache-ref-secretcachehook_put)
+ [

## get
](#retrieving-secrets_cache-ref-secretcachehook_get)

## put
<a name="retrieving-secrets_cache-ref-secretcachehook_put"></a>

Prepares the object for storing in the cache.

Request syntax  

```
response = hook.put(
    obj='secret_object'
)
```

Parameters  
+ `obj` (*object*) -- [Required] The secret or object that contains the secret.

Return type  
object

## get
<a name="retrieving-secrets_cache-ref-secretcachehook_get"></a>

Derives the object from the cached object.

Request syntax  

```
response = hook.get(
    obj='secret_object'
)
```

Parameters  
+ `obj` (*object*): [Required] The secret or object that contains the secret.

Return type  
object

# @InjectSecretString
<a name="retrieving-secrets_cache-decor-string"></a>

This decorator expects a secret ID string and [SecretCache](retrieving-secrets_cache-ref-secretcache.md) as the first and second arguments. The decorator returns the secret string value. The secret must contain a string. 

```
from aws_secretsmanager_caching import SecretCache 
from aws_secretsmanager_caching import InjectKeywordedSecretString,  InjectSecretString 

cache = SecretCache()

@InjectSecretString ( 'mysecret' ,  cache ) 
def function_to_be_decorated( arg1,  arg2,  arg3):
```

# @InjectKeywordedSecretString
<a name="retrieving-secrets_cache-decor-keyword"></a>

This decorator expects a secret ID string and [SecretCache](retrieving-secrets_cache-ref-secretcache.md) as the first and second arguments. The remaining arguments map parameters from the wrapped function to JSON keys in the secret. The secret must contain a string in JSON structure. 

For a secret that contains this JSON:

```
{
  "username": "saanvi",
  "password": "EXAMPLE-PASSWORD"
}
```

The following example shows how to extract the JSON values for `username` and `password` from the secret.

```
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( 'Do something with the func_username and func_password parameters')
```