docs: add examples for shorthands in the parameter utility

Author: nmoutschen

aws_lambda_powertools/utilities/parameters/dynamodb.py

@@ -16,6 +16,17 @@ class DynamoDBProvider(BaseProvider):
     """
     Amazon DynamoDB Parameter Provider
 
+    Parameters
+    ----------
+    table_name: str
+        Name of the DynamoDB table that stores parameters
+    key_attr: str, optional
+        Hash key for the DynamoDB table
+    value_attr: str, optional
+        Attribute that contains the values in the DynamoDB table
+    config: botocore.config.Config, optional
+        Botocore configuration to pass during client initialization
+
     Example
     -------
     **Retrieves a parameter value from a DynamoDB table**
@@ -111,7 +122,7 @@ def _get(self, name: str, **sdk_options) -> str:
         ----------
         name: str
             Name of the parameter
-        sdk_options: dict
+        sdk_options: dict, optional
             Dictionary of options that will be passed to the get_item call
         """
 
@@ -128,9 +139,9 @@ def _get_multiple(self, path: str, sort_attr: str = "sk", **sdk_options) -> Dict
         ----------
         path: str
             Path to retrieve the parameters
-        sort_attr: str
+        sort_attr: str, optional
             Name of the DynamoDB table sort key (defaults to 'sk')
-        sdk_options: dict
+        sdk_options: dict, optional
             Dictionary of options that will be passed to the query call
         """
 

aws_lambda_powertools/utilities/parameters/secrets.py

@@ -15,6 +15,11 @@ class SecretsProvider(BaseProvider):
     """
     AWS Secrets Manager Parameter Provider
 
+    Parameters
+    ----------
+    config: botocore.config.Config, optional
+        Botocore configuration to pass during client initialization
+
     Example
     -------
     **Retrieves a parameter value from Secrets Manager**
@@ -79,13 +84,42 @@ def _get_multiple(self, path: str, **sdk_options) -> Dict[str, str]:
         raise NotImplementedError()
 
 
-def get_secret(name: str, transform: Optional[str] = None, decrypt: bool = False) -> Union[str, dict, bytes]:
+def get_secret(name: str, transform: Optional[str] = None, **sdk_options) -> Union[str, dict, bytes]:
     """
     Retrieve a parameter value from AWS Secrets Manager
+
+    Parameters
+    ----------
+    name: str
+        Name of the parameter
+    transform: str, optional
+        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
+    sdk_options: dict, optional
+        Dictionary of options that will be passed to the get_secret_value call
+
+    Example
+    -------
+    **Retrieves a secret***
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_secret
+        >>>
+        >>> get_secret("my-secret")
+
+    **Retrieves a secret and transforms using a JSON deserializer***
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_secret
+        >>>
+        >>> get_secret("my-secret", transform="json")
+
+    **Retrieves a secret and passes custom arguments to the SDK**
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_secret
+        >>>
+        >>> get_secret("my-secret", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
     """
 
     # Only create the provider if this function is called at least once
     if "secrets" not in DEFAULT_PROVIDERS:
         DEFAULT_PROVIDERS["secrets"] = SecretsProvider()
 
-    return DEFAULT_PROVIDERS["secrets"].get(name, transform=transform, decrypt=decrypt)
+    return DEFAULT_PROVIDERS["secrets"].get(name, transform=transform, **sdk_options)

aws_lambda_powertools/utilities/parameters/ssm.py

@@ -15,6 +15,11 @@ class SSMProvider(BaseProvider):
     """
     AWS Systems Manager Parameter Store Provider
 
+    Parameters
+    ----------
+    config: botocore.config.Config, optional
+        Botocore configuration to pass during client initialization
+
     Example
     -------
     **Retrieves a parameter value from Systems Manager Parameter Store**
@@ -71,9 +76,9 @@ def _get(self, name: str, decrypt: bool = False, **sdk_options) -> str:
         ----------
         name: str
             Parameter name
-        decrypt: bool
+        decrypt: bool, optional
             If the parameter value should be decrypted
-        sdk_options: dict
+        sdk_options: dict, optional
             Dictionary of options that will be passed to the get_parameter call
         """
 
@@ -91,11 +96,11 @@ def _get_multiple(self, path: str, decrypt: bool = False, recursive: bool = Fals
         ----------
         path: str
             Path to retrieve the parameters
-        decrypt: bool
+        decrypt: bool, optional
             If the parameter values should be decrypted
-        recursive: bool
+        recursive: bool, optional
             If this should retrieve the parameter values recursively or not
-        sdk_options: dict
+        sdk_options: dict, optional
             Dictionary of options that will be passed to the get_parameters_by_path call
         """
 
@@ -131,9 +136,32 @@ def _get_multiple(self, path: str, decrypt: bool = False, recursive: bool = Fals
         return retval
 
 
-def get_parameter(name: str, transform: Optional[str] = None) -> Union[str, list, dict, bytes]:
+def get_parameter(name: str, transform: Optional[str] = None, **sdk_options) -> Union[str, list, dict, bytes]:
     """
     Retrieve a parameter value from AWS Systems Manager (SSM) Parameter Store
+
+    Parameters
+    ----------
+    name: str
+        Name of the parameter
+    transform: str, optional
+        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
+    sdk_options: dict, optional
+        Dictionary of options that will be passed to the get_secret_value call
+
+    Example
+    -------
+    **Retrieves a parameter value from Systems Manager Parameter Store**
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_parameter
+        >>>
+        >>> get_parameter("/my/parameter")
+
+    **Retrieves a parameter value and decodes it using a Base64 decoder**
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_parameter
+        >>>
+        >>> get_parameter("/my/parameter", transform='binary')
     """
 
     # Only create the provider if this function is called at least once
@@ -144,10 +172,37 @@ def get_parameter(name: str, transform: Optional[str] = None) -> Union[str, list
 
 
 def get_parameters(
-    path: str, transform: Optional[str] = None, recursive: bool = False, decrypt: bool = False
+    path: str, transform: Optional[str] = None, recursive: bool = False, decrypt: bool = False, **sdk_options
 ) -> Union[Dict[str, str], Dict[str, dict], Dict[str, bytes]]:
     """
     Retrieve multiple parameter values from AWS Systems Manager (SSM) Parameter Store
+
+    Parameters
+    ----------
+    path: str
+        Path to retrieve the parameters
+    transform: str, optional
+        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
+    decrypt: bool, optional
+        If the parameter values should be decrypted
+    recursive: bool, optional
+        If this should retrieve the parameter values recursively or not
+    sdk_options: dict, optional
+        Dictionary of options that will be passed to the get_parameters_by_path call
+
+    Example
+    -------
+    **Retrieves parameter values from Systems Manager Parameter Store**
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_parameter
+        >>>
+        >>> get_parameters("/my/path/parameter")
+
+    **Retrieves parameter values and decodes them using a Base64 decoder**
+
+        >>> from aws_lambda_powertools.utilities.parameters import get_parameter
+        >>>
+        >>> get_parameters("/my/path/parameter", transform='binary')
     """
 
     # Only create the provider if this function is called at least once