Clarify documentation for paginator jmespath

[mdavis-xyz]

In this part of the docs, there's an example of using jmespath with a paginator.

I'm not an expert in JMESPath, but isn't "Contents[?Size > `100`][]" the same as "Contents[?Size > `100`]"? I tried both and they give the same results. So should we simplify this?

I think it would also be beneficial to state how to do this without any filtering. i.e. "Contents[]" (as opposed to * or . or something else a new user may guess.) (Or if there's another way of flattening without filtering, like .build_full_result() but as a generator not in-memory list, document that instead.)

And I think it would be beneficial to point out that the string Contents is specific to the API call. It's not usable for other paginators.

[stobrien89]

Hi @mdavis-xyz,

Thanks for pointing this out!

The flatten projection is redundant in this example because there are no lists in the result set to flatten—Contents is an array of objects. You're more than welcome to submit a PR to remove that if you'd like.

For your second point, we do provide a hyperlink to the JMESpath documentation on the page, but are you suggesting a separate example?

I agree that Contents can be a little confusing out of context. I think it'd also be helpful to add something that indicates Contents is specific to that response.

[mdavis-xyz]

Yes I was suggesting a separate example. I think it's unclear from the existing documentation that there's a way to iterate over all resources from a paginator without nested for loops. A separate example would make that clear. Or maybe just a comment saying that if you remove the contents of the square bracket that will result in a flattened iterator?

[stobrien89]

Hi @mdavis-xyz,

Thanks for clarifying. I think it would be helpful to include a note/comment (before the link to JMESpath) saying an empty square bracket will result in a flattened iterator, but I don't think it necessarily warrants a separate example since there are plenty in the JMESpath documentation.