Docs: Incorrect example for SSMProvider.get_multiple

[bram-tv]

What were you searching in the docs?

Documentation for the get_multiple call of the SSMProvider.

Is this related to an existing documentation section?

https://docs.powertools.aws.dev/lambda/python/latest/api/utilities/parameters/ssm.html

How can we improve?

The examples listed under:

• Retrieves multiple parameter values from Systems Manager Parameter Store using a path prefix
• Retrieves multiple parameter values from Systems Manager Parameter Store passing options to the SDK call

do not appear to be correct.

Taking the first example:

>>> from aws_lambda_powertools.utilities.parameters import SSMProvider
>>> ssm_provider = SSMProvider()
>>>
>>> values = ssm_provider.get_multiple("/my/path/prefix")
>>>
>>> for key, value in values.items():
...     print(key, value)
/my/path/prefix/a   Parameter value a
/my/path/prefix/b   Parameter value b
/my/path/prefix/c   Parameter value c

This shows that /my/path/prefix/ is part of the key name but that is not (or no longer the case).
Looking at the code:

powertools-lambda-python/aws_lambda_powertools/utilities/parameters/ssm.py

Line 215 in 2c44207

# Standardize the parameter name

                # Standardize the parameter name
                # The parameter name returned by SSM will contain the full path.
                # However, for readability, we should return only the part after
                # the path.
                name = parameter["Name"]
                if name.startswith(path):
                    name = name[len(path) :]
                name = name.lstrip("/")

It always removes the path from the name.

Got a suggestion in mind?

Updates the example to:

>>> ...
>>> for key, value in values.items():
...     print(key, value)
a   Parameter value a
b   Parameter value b
c   Parameter value c

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[leandrodamascena]

Hi @bram-tv! Thanks so much for raising this issue! We strive to keep our documentation and docstring as up-to-date as possible, but sometimes we miss something, like this case. This case is the docstring of the method and we can update it to make it clearer for our customers.

Do you think it's worth putting something like: "considering the path /my/path/prefix/ which has the parameters a, b and c...?" This way it makes the example more explicit for the user that we remove the path.

Do you have bandwidth to send a PR to fix this?

Thanks!

[heitorlessa]

@leandrodamascena taking this one FYI

[heitorlessa]

Apologies for the delay @bram-tv but we've got a PR now. Besides API docs, I've also improved the User Guide docs with more details and examples too (including comments in the code snippet provided).

Can't thank you enough for taking the time in helping us improve the docs.

---

[heitorlessa]

Now in stage (prod after our release this week): https://docs.powertools.aws.dev/lambda/python/stage/api/utilities/parameters/index.html#aws_lambda_powertools.utilities.parameters.get_parameters

User-guide docs: https://docs.powertools.aws.dev/lambda/python/stage/utilities/parameters/#fetching-parameters

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under 2.22.0 version!