Skip to content

Commit 57eb44b

Browse files
leandrodamascenaleandrodamascena
committed
Improving docstring
1 parent 3bf45df commit 57eb44b

File tree

2 files changed

+148
-22
lines changed

2 files changed

+148
-22
lines changed

‎aws_lambda_powertools/utilities/parameters/secrets.py

+97-19
Original file line numberDiff line numberDiff line change
@@ -121,13 +121,36 @@ def _get_multiple(self, path: str, **sdk_options) -> Dict[str, str]:
121121
raise NotImplementedError()
122122

123123
def _create_secret(self, name: str, **sdk_options):
124+
"""
125+
Create a secret with the given name.
126+
127+
Parameters:
128+
----------
129+
name: str
130+
The name of the secret.
131+
**sdk_options:
132+
Additional options to be passed to the create_secret method.
133+
134+
Raises:
135+
SetSecretError: If there is an error setting the secret.
136+
"""
124137
try:
125138
sdk_options["Name"] = name
126139
return self.client.create_secret(**sdk_options)
127140
except Exception as exc:
128141
raise SetSecretError(f"Error setting secret - {str(exc)}") from exc
129142

130143
def _update_secret(self, name: str, **sdk_options):
144+
"""
145+
Update a secret with the given name.
146+
147+
Parameters:
148+
----------
149+
name: str
150+
The name of the secret.
151+
**sdk_options:
152+
Additional options to be passed to the create_secret method.
153+
"""
131154
sdk_options["SecretId"] = name
132155
return self.client.put_secret_value(**sdk_options)
133156

@@ -140,13 +163,28 @@ def set(
140163
**sdk_options,
141164
) -> SetSecretResponse:
142165
"""
143-
Modifies the details of a secret, including metadata and the secret value.
166+
Modify the details of a secret or create a new secret if it doesn't already exist.
167+
It includes metadata and the secret value.
168+
169+
We aim to minimize API calls by assuming that the secret already exists and needs updating.
170+
If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:
171+
172+
173+
┌────────────────────────┐ ┌─────────────────┐
174+
┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
175+
│ └────────────────────────┘ └─────────────────┘ │
176+
│ │
177+
│ │
178+
│ ▼
179+
┌─────────────────┐ ┌─────────────────────┐
180+
│Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
181+
└─────────────────┘ └─────────────────────┘
144182
145183
Parameters
146184
----------
147185
name: str
148-
The ARN or name of the secret to add a new version to.
149-
value: str or bytes
186+
The ARN or name of the secret to add a new version to or create a new one.
187+
value: str, dict or bytes
150188
Specifies text data that you want to encrypt and store in this new version of the secret.
151189
client_request_token: str, optional
152190
This value helps ensure idempotency. Recommended that you generate
@@ -156,13 +194,39 @@ def set(
156194
sdk_options: dict, optional
157195
Dictionary of options that will be passed to the Secrets Manager update_secret API call
158196
197+
Raises
198+
------
199+
SetSecretError
200+
When attempting to update or create a secret fails.
201+
159202
Returns:
160203
-------
161-
Version ID of the newly created version of the secret.
204+
SetSecretResponse:
205+
The dict returned by boto3.
206+
207+
Example
208+
-------
209+
**Sets a secret***
210+
211+
>>> from aws_lambda_powertools.utilities import parameters
212+
>>>
213+
>>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")
214+
215+
**Sets a secret and includes an client_request_token**
216+
217+
>>> from aws_lambda_powertools.utilities import parameters
218+
>>> import uuid
219+
>>>
220+
>>> parameters.set_secret(
221+
name="my-secret",
222+
value='{"password": "supers3cr3tllam@passw0rd"}',
223+
client_request_token=str(uuid.uuid4())
224+
)
162225
163226
URLs:
164227
-------
165228
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
229+
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
166230
"""
167231

168232
if isinstance(value, dict):
@@ -301,37 +365,46 @@ def set_secret(
301365
**sdk_options,
302366
) -> str:
303367
"""
304-
Retrieve a parameter value from AWS Secrets Manager
368+
Modify the details of a secret or create a new secret if it doesn't already exist.
369+
It includes metadata and the secret value.
370+
371+
We aim to minimize API calls by assuming that the secret already exists and needs updating.
372+
If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:
373+
374+
375+
┌────────────────────────┐ ┌─────────────────┐
376+
┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
377+
│ └────────────────────────┘ └─────────────────┘ │
378+
│ │
379+
│ │
380+
│ ▼
381+
┌─────────────────┐ ┌─────────────────────┐
382+
│Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
383+
└─────────────────┘ └─────────────────────┘
305384
306385
Parameters
307386
----------
308387
name: str
309-
Name of the parameter
310-
value: str or bytes
311-
Secret value to set
388+
The ARN or name of the secret to add a new version to or create a new one.
389+
value: str, dict or bytes
390+
Specifies text data that you want to encrypt and store in this new version of the secret.
312391
client_request_token: str, optional
313392
This value helps ensure idempotency. Recommended that you generate
314393
a UUID-type value to ensure uniqueness within the specified secret.
315394
This value becomes the VersionId of the new version. This field is
316395
autopopulated if not provided.
317-
version_stages: list[str], optional
318-
A list of staging labels that are attached to this version of the secret.
319396
sdk_options: dict, optional
320-
Dictionary of options that will be passed to the get_secret_value call
397+
Dictionary of options that will be passed to the Secrets Manager update_secret API call
321398
322399
Raises
323400
------
324-
SetParameterError
325-
When the secrets provider fails to set a secret value or secret binary for
326-
a given name.
401+
SetSecretError
402+
When attempting to update or create a secret fails.
327403
328404
Returns:
329405
-------
330-
Version ID of the newly created version of the secret.
331-
332-
URLs:
333-
-------
334-
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
406+
SetSecretResponse:
407+
The dict returned by boto3.
335408
336409
Example
337410
-------
@@ -350,6 +423,11 @@ def set_secret(
350423
value='{"password": "supers3cr3tllam@passw0rd"}',
351424
client_request_token="61f2af5f-5f75-44b1-a29f-0cc37af55b11"
352425
)
426+
427+
URLs:
428+
-------
429+
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
430+
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
353431
"""
354432

355433
# Only create the provider if this function is called at least once

‎aws_lambda_powertools/utilities/parameters/ssm.py

+51-3
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,54 @@ def set(
233233
kms_key_id: str | None = None,
234234
**sdk_options,
235235
) -> PutParameterResponse:
236+
"""
237+
Sets a parameter in AWS Systems Manager Parameter Store.
238+
239+
Parameters
240+
----------
241+
name: str
242+
The fully qualified name includes the complete hierarchy of the parameter name and name.
243+
value: str
244+
The parameter value
245+
parameter_type: str, optional
246+
Type of the parameter. Allowed values are String, StringList, and SecureString
247+
overwrite: bool, optional
248+
If the parameter value should be overwritten, False by default
249+
tier: str, optional
250+
The parameter tier to use. Allowed values are Standard, Advanced, and Intelligent-Tiering
251+
description: str, optional
252+
The description of the parameter
253+
kms_key_id: str, optional
254+
The KMS key id to use to encrypt the parameter
255+
sdk_options: dict, optional
256+
Dictionary of options that will be passed to the Parameter Store get_parameter API call
257+
258+
Raises
259+
------
260+
SetParameterError
261+
When the parameter provider fails to retrieve a parameter value for
262+
a given name.
263+
264+
URLs:
265+
-------
266+
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ssm/client/put_parameter.html
267+
268+
Example
269+
-------
270+
**Sets a parameter value from Systems Manager Parameter Store**
271+
272+
>>> from aws_lambda_powertools.utilities import parameters
273+
>>>
274+
>>> response = parameters.set_parameter(name="/my/example/parameter", value="More Powertools")
275+
>>>
276+
>>> print(response)
277+
123
278+
279+
Returns
280+
-------
281+
PutParameterResponse
282+
The dict returned by boto3.
283+
"""
236284
opts = {
237285
"Name": name,
238286
"Value": value,
@@ -929,8 +977,7 @@ def set_parameter(
929977
Raises
930978
------
931979
SetParameterError
932-
When the parameter provider fails to retrieve a parameter value for
933-
a given name.
980+
When attempting to set a parameter fails.
934981
935982
URLs:
936983
-------
@@ -949,7 +996,8 @@ def set_parameter(
949996
950997
Returns
951998
-------
952-
int: The status code indicating the success or failure of the operation.
999+
PutParameterResponse
1000+
The dict returned by boto3.
9531001
"""
9541002

9551003
# Only create the provider if this function is called at least once

0 commit comments

Comments
 (0)