Skip to content

Commit ec62084

Browse files
heitorlessaheitorlessa
authored
docs(parameters): improve readability on error handling get_parameter… (#2833)
* docs(parameters): improve readability on error handling get_parameters_by_name * docs(parameters): add details about return on get_parameters; improve code snippet * docs(ssm): correct api docstring on return value
1 parent c060a00 commit ec62084

File tree

3 files changed

+40
-27
lines changed

3 files changed

+40
-27
lines changed

‎aws_lambda_powertools/utilities/parameters/ssm.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -626,6 +626,8 @@ def get_parameters(
626626
"""
627627
Retrieve multiple parameter values from AWS Systems Manager (SSM) Parameter Store
628628
629+
For readability, we strip the path prefix name in the response.
630+
629631
Parameters
630632
----------
631633
path: str
@@ -664,9 +666,8 @@ def get_parameters(
664666
>>>
665667
>>> for key, value in values.items():
666668
... print(key, value)
667-
/my/path/prefix/a Parameter value a
668-
/my/path/prefix/b Parameter value b
669-
/my/path/prefix/c Parameter value c
669+
config Parameter value (/my/path/prefix/config)
670+
webhook/config Parameter value (/my/path/prefix/webhook/config)
670671
671672
**Retrieves parameter values and decodes them using a Base64 decoder**
672673

‎docs/utilities/parameters.md

+29-21
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ This utility requires additional permissions to work as expected.
3333
| SSM | **`get_parameters`**, **`SSMProvider.get_multiple`** | **`ssm:GetParametersByPath`** |
3434
| SSM | **`get_parameters_by_name`**, **`SSMProvider.get_parameters_by_name`** | **`ssm:GetParameter`** and **`ssm:GetParameters`** |
3535
| SSM | If using **`decrypt=True`** | You must add an additional permission **`kms:Decrypt`** |
36-
| Secrets | **`get_secret`**, **`SecretsProvider.get`** | **`secretsmanager:GetSecretValue`** |
36+
| Secrets | **`get_secret`**, **`SecretsProvider.get`** | **`secretsmanager:GetSecretValue`** |
3737
| DynamoDB | **`DynamoDBProvider.get`** | **`dynamodb:GetItem`** |
3838
| DynamoDB | **`DynamoDBProvider.get_multiple`** | **`dynamodb:Query`** |
3939
| AppConfig | **`get_app_config`**, **`AppConfigProvider.get_app_config`** | **`appconfig:GetLatestConfiguration`** and **`appconfig:StartConfigurationSession`** |
@@ -53,26 +53,34 @@ For multiple parameters, you can use either:
5353
* `get_parameters_by_name` to fetch distinct parameters by their full name. It also accepts custom caching, transform, decrypt per parameter.
5454

5555
=== "getting_started_recursive_ssm_parameter.py"
56-
```python hl_lines="3 10 13"
56+
This is useful when you want to fetch all parameters from a given path, say `/dev`, e.g., `/dev/config`, `/dev/webhook/config`
57+
58+
To ease readability in deeply nested paths, we strip the path name. For example:
59+
60+
* `/dev/config` -> `config`
61+
* `/dev/webhook/config` -> `webhook/config`
62+
63+
```python hl_lines="3 11 18"
5764
--8<-- "examples/parameters/src/getting_started_recursive_ssm_parameter.py"
5865
```
5966

6067
=== "getting_started_parameter_by_name.py"
61-
```python hl_lines="3 14"
68+
```python hl_lines="3 15"
6269
--8<-- "examples/parameters/src/getting_started_parameter_by_name.py"
6370
```
6471

65-
???+ tip "`get_parameters_by_name` supports graceful error handling"
66-
By default, we will raise `GetParameterError` when any parameter fails to be fetched. You can override it by setting `raise_on_error=False`.
72+
=== "get_parameter_by_name_error_handling.py"
73+
!!! tip "Failing gracefully if one or more parameters cannot be fetched or decrypted."
6774

68-
When disabled, we take the following actions:
75+
By default, we will raise `GetParameterError` when any parameter fails to be fetched.
6976

70-
* Add failed parameter name in the `_errors` key, _e.g._, `{_errors: ["/param1", "/param2"]}`
71-
* Keep only successful parameter names and their values in the response
72-
* Raise `GetParameterError` if any of your parameters is named `_errors`
77+
You can override it by setting `raise_on_error=False`. When disabled, we take the following actions:
7378

74-
=== "get_parameter_by_name_error_handling.py"
75-
```python hl_lines="3 5 12-13 15"
79+
* Add failed parameter name in the `_errors` key, _e.g._, `{_errors: ["/param1", "/param2"]}`
80+
* Keep only successful parameter names and their values in the response
81+
* Raise `GetParameterError` if any of your parameters is named `_errors`
82+
83+
```python hl_lines="3 5 13-17"
7684
--8<-- "examples/parameters/src/get_parameter_by_name_error_handling.py"
7785
```
7886

@@ -389,16 +397,16 @@ You can use arbitrary keyword arguments to pass it directly to the underlying SD
389397

390398
Here is the mapping between this utility's functions and methods and the underlying SDK:
391399

392-
| Provider | Function/Method | Client name | Function name |
393-
| ------------------- | ------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
394-
| SSM Parameter Store | `get_parameter` | `ssm` | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter){target="_blank"} |
395-
| SSM Parameter Store | `get_parameters` | `ssm` | [get_parameters_by_path](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameters_by_path){target="_blank"} |
396-
| SSM Parameter Store | `SSMProvider.get` | `ssm` | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter){target="_blank"} |
397-
| SSM Parameter Store | `SSMProvider.get_multiple` | `ssm` | [get_parameters_by_path](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameters_by_path){target="_blank"} |
398-
| Secrets Manager | `get_secret` | `secretsmanager` | [get_secret_value](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html#SecretsManager.Client.get_secret_value){target="_blank"} |
399-
| Secrets Manager | `SecretsProvider.get` | `secretsmanager` | [get_secret_value](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html#SecretsManager.Client.get_secret_value){target="_blank"} |
400-
| DynamoDB | `DynamoDBProvider.get` | `dynamodb` | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table){target="_blank"}) | [get_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.get_item) |
401-
| DynamoDB | `DynamoDBProvider.get_multiple` | `dynamodb` | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table){target="_blank"}) | [query](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.query) |
400+
| Provider | Function/Method | Client name | Function name |
401+
| ------------------- | ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
402+
| SSM Parameter Store | `get_parameter` | `ssm` | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter){target="_blank"} |
403+
| SSM Parameter Store | `get_parameters` | `ssm` | [get_parameters_by_path](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameters_by_path){target="_blank"} |
404+
| SSM Parameter Store | `SSMProvider.get` | `ssm` | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter){target="_blank"} |
405+
| SSM Parameter Store | `SSMProvider.get_multiple` | `ssm` | [get_parameters_by_path](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameters_by_path){target="_blank"} |
406+
| Secrets Manager | `get_secret` | `secretsmanager` | [get_secret_value](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html#SecretsManager.Client.get_secret_value){target="_blank"} |
407+
| Secrets Manager | `SecretsProvider.get` | `secretsmanager` | [get_secret_value](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html#SecretsManager.Client.get_secret_value){target="_blank"} |
408+
| DynamoDB | `DynamoDBProvider.get` | `dynamodb` | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table){target="_blank"}) | [get_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.get_item) |
409+
| DynamoDB | `DynamoDBProvider.get_multiple` | `dynamodb` | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table){target="_blank"}) | [query](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.query) |
402410
| App Config | `get_app_config` | `appconfigdata` | [start_configuration_session](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/appconfigdata.html#AppConfigData.Client.start_configuration_session){target="_blank"} and [get_latest_configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/appconfigdata.html#AppConfigData.Client.get_latest_configuration){target="_blank"} |
403411

404412
### Bring your own boto client

‎examples/parameters/src/getting_started_recursive_ssm_parameter.py

+7-3
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,16 @@
66

77
def lambda_handler(event: dict, context: LambdaContext):
88
try:
9-
# Retrieve multiple parameters from a path prefix
10-
all_parameters: dict = parameters.get_parameters("/lambda-powertools/", max_age=20)
9+
# Retrieve all parameters within a path e.g., /dev
10+
# Say, you had two parameters under `/dev`: /dev/config, /dev/webhook/config
11+
all_parameters: dict = parameters.get_parameters("/dev", max_age=20)
1112
endpoint_comments = None
1213

14+
# We strip the path prefix name for readability and memory usage in deeply nested paths
15+
# all_parameters would then look like:
16+
## all_parameters["config"] = value # noqa: ERA001
17+
## all_parameters["webhook/config"] = value # noqa: ERA001
1318
for parameter, value in all_parameters.items():
14-
1519
if parameter == "endpoint_comments":
1620
endpoint_comments = value
1721

0 commit comments

Comments
 (0)