docs(parameters): snippets split, improved, and lint (#1564)

* chore(parameters): refactoring examples

* chore(parameters): adding cache examples

* chore(parameters): adding builtin examples and fix mypy errors

* chore(parameters): adding all providers with custom config

* chore(parameters): adding custom provider

* chore(parameters): adding custom provider

* chore(parameters): adding custom provider

* chore(parameters): adding DynamoDB provider

* chore(parameters): adding tests - mock

* chore(parameters): adding more tests

* chore(parameters): adding appconfig builtin provider

* chore(parameters): adding final examples

* chore(parameters): adding final examples

* chore(parameters): highlights - small changes

* fix(docs): broken link in boto3_session

* fix(docs): improve constrast ratio

* fix(docs): typing and correctness on null endpoint

* (chore): addressing Ruben's feedbacks

* (chore): import errors

---------

Signed-off-by: Leandro Damascena <[email protected]>
Co-authored-by: heitorlessa <[email protected]>

Author: leandrodamascena

docs/utilities/parameters.md

@@ -0,0 +1,22 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: IdKeyAttr
+            AttributeType: S
+        -   AttributeName: SkKeyAttr
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: IdKeyAttr
+            KeyType: HASH
+        -   AttributeName: SkKeyAttr
+            KeyType: RANGE
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_custom_fields.yaml

@@ -0,0 +1,22 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: id
+            AttributeType: S
+        -   AttributeName: sk
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: id
+            KeyType: HASH
+        -   AttributeName: sk
+            KeyType: RANGE
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_table_recursive.yaml

@@ -0,0 +1,18 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: id
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: id
+            KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_table_single.yaml

@@ -0,0 +1,21 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = parameters.get_app_config(
+            name="config", environment="dev", application="comments", force_fetch=True
+        )
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/appconfig_force_fetch.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = parameters.get_app_config(
+            name="config", environment="dev", application="comments", max_age=20
+        )
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/appconfig_with_cache.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+import requests
+from botocore.config import Config
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+config = Config(region_name="sa-east-1")
+appconf_provider = parameters.AppConfigProvider(environment="dev", application="comments", config=config)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = appconf_provider.get("config")
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_appconfig.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(table_name="ParameterTable", endpoint_url="http://localhost:8000")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in DynamoDB Table
+        endpoint_comments: Any = dynamodb_provider.get("comments_endpoint")
+
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_custom_endpoint.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(
+    table_name="ParameterTable", key_attr="IdKeyAttr", sort_attr="SkKeyAttr", value_attr="ValueAttr"
+)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in DynamoDB Table
+        endpoint_comments: Any = dynamodb_provider.get("comments_endpoint")
+
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_custom_fields.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(table_name="ParameterTable")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Retrieve multiple parameters using HASH KEY
+        all_parameters: Any = dynamodb_provider.get_multiple("config")
+        endpoint_comments = "https://jsonplaceholder.typicode.com/noexists/"
+        limit = 2
+
+        for parameter, value in all_parameters.items():
+
+            if parameter == "endpoint_comments":
+                endpoint_comments = value
+
+            if parameter == "limit":
+                limit = int(value)
+
+        # the value of parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[limit]}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}