feat(parameters): accept boto3_client to support private endpoints and ease testing

aws_lambda_powertools/utilities/parameters/appconfig.py

@@ -9,6 +9,7 @@
 
 import boto3
 from botocore.config import Config
+from mypy_boto3_appconfig import AppConfigClient
 
 from ...shared import constants
 from ...shared.functions import resolve_env_var_choice
@@ -30,7 +31,9 @@ class AppConfigProvider(BaseProvider):
     config: botocore.config.Config, optional
         Botocore configuration to pass during client initialization
     boto3_session : boto3.session.Session, optional
-            Boto3 session to use for AWS API communication
+            Boto3 session to use for AWS API communication, will not be used if boto3_client is not None
+    boto3_client: AppConfigClient, optional
+            Boto3 Client to use for AWS API communication, will be used instead of boto3_session if both provided
 
     Example
     -------
@@ -68,14 +71,19 @@ def __init__(
         application: Optional[str] = None,
         config: Optional[Config] = None,
         boto3_session: Optional[boto3.session.Session] = None,
+        boto3_client: Optional[AppConfigClient] = None,
     ):
         """
         Initialize the App Config client
         """
 
         config = config or Config()
-        session = boto3_session or boto3.session.Session()
-        self.client = session.client("appconfig", config=config)
+        if boto3_client is not None:
+            self.client = boto3_client
+        else:
+            session = boto3_session or boto3.session.Session()
+            self.client: AppConfigClient = session.client("appconfig", config=config)
+
         self.application = resolve_env_var_choice(
             choice=application, env=os.getenv(constants.SERVICE_NAME_ENV, "service_undefined")
         )

aws_lambda_powertools/utilities/parameters/secrets.py

@@ -7,6 +7,7 @@
 
 import boto3
 from botocore.config import Config
+from mypy_boto3_secretsmanager import SecretsManagerClient
 
 from .base import DEFAULT_MAX_AGE_SECS, DEFAULT_PROVIDERS, BaseProvider
 
@@ -20,7 +21,9 @@ class SecretsProvider(BaseProvider):
     config: botocore.config.Config, optional
         Botocore configuration to pass during client initialization
     boto3_session : boto3.session.Session, optional
-            Boto3 session to use for AWS API communication
+            Boto3 session to use for AWS API communication, will not be used if boto3_client is not None
+    boto3_client: SecretsManagerClient, optional
+            Boto3 Client to use for AWS API communication, will be used instead of boto3_session if both provided
 
     Example
     -------
@@ -60,14 +63,22 @@ class SecretsProvider(BaseProvider):
 
     client: Any = None
 
-    def __init__(self, config: Optional[Config] = None, boto3_session: Optional[boto3.session.Session] = None):
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        boto3_session: Optional[boto3.session.Session] = None,
+        boto3_client: Optional[SecretsManagerClient] = None,
+    ):
         """
         Initialize the Secrets Manager client
         """
 
         config = config or Config()
-        session = boto3_session or boto3.session.Session()
-        self.client = session.client("secretsmanager", config=config)
+        if boto3_client is not None:
+            self.client = boto3_client
+        else:
+            session = boto3_session or boto3.session.Session()
+            self.client: SecretsManagerClient = session.client("secretsmanager", config=config)
 
         super().__init__()
 

aws_lambda_powertools/utilities/parameters/ssm.py

@@ -7,6 +7,7 @@
 
 import boto3
 from botocore.config import Config
+from mypy_boto3_ssm import SSMClient
 
 from .base import DEFAULT_MAX_AGE_SECS, DEFAULT_PROVIDERS, BaseProvider
 
@@ -20,7 +21,9 @@ class SSMProvider(BaseProvider):
     config: botocore.config.Config, optional
         Botocore configuration to pass during client initialization
     boto3_session : boto3.session.Session, optional
-            Boto3 session to use for AWS API communication
+            Boto3 session to use for AWS API communication, will not be used if boto3_client is not None
+    boto3_client: SSMClient, optional
+            Boto3 Client to use for AWS API communication, will be used instead of boto3_session if both provided
 
     Example
     -------
@@ -76,14 +79,22 @@ class SSMProvider(BaseProvider):
 
     client: Any = None
 
-    def __init__(self, config: Optional[Config] = None, boto3_session: Optional[boto3.session.Session] = None):
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        boto3_session: Optional[boto3.session.Session] = None,
+        boto3_client: Optional[SSMClient] = None,
+    ):
         """
         Initialize the SSM Parameter Store client
         """
 
         config = config or Config()
-        session = boto3_session or boto3.session.Session()
-        self.client = session.client("ssm", config=config)
+        if boto3_client is not None:
+            self.client = boto3_client
+        else:
+            session = boto3_session or boto3.session.Session()
+            self.client: SSMClient = session.client("ssm", config=config)
 
         super().__init__()
 

docs/utilities/parameters.md

@@ -24,14 +24,14 @@ This utility requires additional permissions to work as expected.
 ???+ note
     Different parameter providers require different permissions.
 
-Provider | Function/Method | IAM Permission
-------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
-SSM Parameter Store | `get_parameter`, `SSMProvider.get`  | `ssm:GetParameter`
-SSM Parameter Store | `get_parameters`, `SSMProvider.get_multiple` | `ssm:GetParametersByPath`
-Secrets Manager | `get_secret`, `SecretsManager.get` | `secretsmanager:GetSecretValue`
-DynamoDB | `DynamoDBProvider.get` | `dynamodb:GetItem`
-DynamoDB | `DynamoDBProvider.get_multiple` | `dynamodb:Query`
-App Config | `AppConfigProvider.get_app_config`, `get_app_config` | `appconfig:GetConfiguration`
+| Provider            | Function/Method                                      | IAM Permission                  |
+| ------------------- | ---------------------------------------------------- | ------------------------------- |
+| SSM Parameter Store | `get_parameter`, `SSMProvider.get`                   | `ssm:GetParameter`              |
+| SSM Parameter Store | `get_parameters`, `SSMProvider.get_multiple`         | `ssm:GetParametersByPath`       |
+| Secrets Manager     | `get_secret`, `SecretsManager.get`                   | `secretsmanager:GetSecretValue` |
+| DynamoDB            | `DynamoDBProvider.get`                               | `dynamodb:GetItem`              |
+| DynamoDB            | `DynamoDBProvider.get_multiple`                      | `dynamodb:Query`                |
+| App Config          | `AppConfigProvider.get_app_config`, `get_app_config` | `appconfig:GetConfiguration`    |
 
 ### Fetching parameters
 
@@ -147,10 +147,10 @@ def handler(event, context):
 
 The AWS Systems Manager Parameter Store provider supports two additional arguments for the `get()` and `get_multiple()` methods:
 
-| Parameter     | Default | Description |
-|---------------|---------|-------------|
-| **decrypt**   | `False` | Will automatically decrypt the parameter.
-| **recursive** | `True`  | For `get_multiple()` only, will fetch all parameter values recursively based on a path prefix.
+| Parameter     | Default | Description                                                                                    |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| **decrypt**   | `False` | Will automatically decrypt the parameter.                                                      |
+| **recursive** | `True`  | For `get_multiple()` only, will fetch all parameter values recursively based on a path prefix. |
 
 ```python hl_lines="6 8" title="Example with get() and get_multiple()"
 from aws_lambda_powertools.utilities import parameters
@@ -189,9 +189,9 @@ For single parameters, you must use `id` as the [partition key](https://docs.aws
 
 	DynamoDB table with `id` partition key and `value` as attribute
 
-	| id         | value  |
-	|--------------|----------|
-	| my-parameter | my-value |
+ | id           | value    |
+ | ------------ | -------- |
+ | my-parameter | my-value |
 
 With this table, `dynamodb_provider.get("my-param")` will return `my-value`.
 
@@ -223,11 +223,11 @@ You can retrieve multiple parameters sharing the same `id` by having a sort key
 
 	DynamoDB table with `id` primary key, `sk` as sort key` and `value` as attribute
 
-	| id        | sk    |   value  |
-	|-------------|---------|------------|
-	| my-hash-key | param-a | my-value-a |
-	| my-hash-key | param-b | my-value-b |
-	| my-hash-key | param-c | my-value-c |
+ | id          | sk      | value      |
+ | ----------- | ------- | ---------- |
+ | my-hash-key | param-a | my-value-a |
+ | my-hash-key | param-b | my-value-b |
+ | my-hash-key | param-c | my-value-c |
 
 With this table, `dynamodb_provider.get_multiple("my-hash-key")` will return a dictionary response in the shape of `sk:value`.
 
@@ -261,12 +261,12 @@ With this table, `dynamodb_provider.get_multiple("my-hash-key")` will return a d
 
 DynamoDB provider can be customized at initialization to match your table structure:
 
-| Parameter      | Mandatory | Default | Description |
-|----------------|-----------|---------|-------------|
-| **table_name** | **Yes**   | *(N/A)* | Name of the DynamoDB table containing the parameter values.
-| **key_attr**   | No        | `id`    | Hash key for the DynamoDB table.
-| **sort_attr**  | No        | `sk`    | Range key for the DynamoDB table. You don't need to set this if you don't use the `get_multiple()` method.
-| **value_attr** | No        | `value` | Name of the attribute containing the parameter value.
+| Parameter      | Mandatory | Default | Description                                                                                                |
+| -------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| **table_name** | **Yes**   | *(N/A)* | Name of the DynamoDB table containing the parameter values.                                                |
+| **key_attr**   | No        | `id`    | Hash key for the DynamoDB table.                                                                           |
+| **sort_attr**  | No        | `sk`    | Range key for the DynamoDB table. You don't need to set this if you don't use the `get_multiple()` method. |
+| **value_attr** | No        | `value` | Name of the attribute containing the parameter value.                                                      |
 
 ```python hl_lines="3-8" title="Customizing DynamoDBProvider to suit your table design"
 from aws_lambda_powertools.utilities import parameters
@@ -467,22 +467,22 @@ def handler(event, context):
 
 Here is the mapping between this utility's functions and methods and the underlying SDK:
 
-| Provider            | Function/Method                 | Client name      | Function name |
-|---------------------|---------------------------------|------------------|----------------|
-| SSM Parameter Store | `get_parameter`                 | `ssm`            | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter) |
-| 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) |
-| SSM Parameter Store | `SSMProvider.get`               | `ssm`            | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter) |
-| 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) |
+| Provider            | Function/Method                 | Client name      | Function name                                                                                                                                             |
+| ------------------- | ------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SSM Parameter Store | `get_parameter`                 | `ssm`            | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter)                             |
+| 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)           |
+| SSM Parameter Store | `SSMProvider.get`               | `ssm`            | [get_parameter](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm.html#SSM.Client.get_parameter)                             |
+| 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)           |
 | 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) |
 | Secrets Manager     | `SecretsManager.get`            | `secretsmanager` | [get_secret_value](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html#SecretsManager.Client.get_secret_value) |
-| DynamoDB            | `DynamoDBProvider.get`          | `dynamodb`       | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table)) | [get_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.get_item)
-| DynamoDB            | `DynamoDBProvider.get_multiple` | `dynamodb`       | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table)) | [query](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.query)
-| App Config          | `get_app_config`                | `appconfig`      | [get_configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/appconfig.html#AppConfig.Client.get_configuration) |
+| DynamoDB            | `DynamoDBProvider.get`          | `dynamodb`       | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table))                                        | [get_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.get_item) |
+| DynamoDB            | `DynamoDBProvider.get_multiple` | `dynamodb`       | ([Table resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table))                                        | [query](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#DynamoDB.Table.query)       |
+| App Config          | `get_app_config`                | `appconfig`      | [get_configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/appconfig.html#AppConfig.Client.get_configuration)         |
 
 
 ### Customizing boto configuration
 
-The **`config`** and **`boto3_session`** parameters enable you to pass in a custom [botocore config object](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html) or a custom [boto3 session](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html) when constructing any of the built-in provider classes.
+The **`config`** , **`boto3_session`**, and **`boto3_client`**  parameters enable you to pass in a custom [botocore config object](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html) , [boto3 session](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html), or  a [boto3 client](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/boto3.html) when constructing any of the built-in provider classes.
 
 ???+ tip
 	You can use a custom session for retrieving parameters cross-account/region and for snapshot testing.
@@ -516,6 +516,22 @@ The **`config`** and **`boto3_session`** parameters enable you to pass in a cust
 		...
 	```
 
+=== "Custom client"
+
+	```python hl_lines="2 4 5"
+	from aws_lambda_powertools.utilities import parameters
+	import boto3
+
+	boto3_client= boto3.client("ssm")
+	ssm_provider = parameters.SSMProvider(boto3_client=boto3_client)
+
+	def handler(event, context):
+		# Retrieve a single parameter
+		value = ssm_provider.get("/my/parameter")
+		...
+	```
+
+
 ## Testing your code
 
 For unit testing your applications, you can mock the calls to the parameters utility to avoid calling AWS APIs. This