Skip to content

Bugfix within shorthand example generation for map-type parameters in documentation #9982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aemous wants to merge 3 commits into
base: v2
Choose a base branch
from
+30 −3
Open

Bugfix within shorthand example generation for map-type parameters in documentation #9982

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e5ef24
Update ParamShorthand DocGen to fix the case of a structure within a …
aemous Jan 12, 2026
fe1c361
Raise max-stack to 4.
aemous Jan 13, 2026
3d5e295
Update test for testing deeply nested shorthand.
aemous Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions awscli/argprocess.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,7 +437,7 @@ class ParamShorthandDocGen(ParamShorthand):
"""Documentation generator for param shorthand syntax."""

_DONT_DOC = object()
_MAX_STACK = 3
_MAX_STACK = 4
Copy link
Contributor

@hssyoo hssyoo Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like setting _MAX_STACK to 3 was an intentional choice: #1467

Instead of defining more logic to remove long shorthand syntax if it's over a certain threshold, I'm inclined to just not change _MAX_STACK unless we think there's enough value coming from net-new shorthand syntax docs.

Copy link
Contributor Author

@aemous aemous Jan 15, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of defining more logic to remove long shorthand syntax if it's over a certain threshold, I'm inclined to just not change _MAX_STACK unless we think there's enough value coming from net-new shorthand syntax docs.

Fair. Just to clarify my original perspective, by making the bugfix so that map adds to the stack, some shorthand syntax that had map as the parameter type will now have a stack size of 4 instead of 3, now causing those to no longer show in docs. Technically these examples always had a stack size of 4 in theory (map + 3 other levels), just that map never added to the stack, so it was actually 3 in practice.

So maybe the 61 shorthand examples that will be removed technically should not have been generated previously. I'll revert to 3 in next revision. Just leaving that context here.


def supports_shorthand(self, argument_model):
"""Checks if a CLI argument supports shorthand syntax."""
Expand Down Expand Up @@ -539,7 +539,11 @@ def _list_docs(self, argument_model, stack):

def _map_docs(self, argument_model, stack):
k = argument_model.key
value_docs = self._shorthand_docs(argument_model.value, stack)
stack.append(argument_model.value.name)
try:
value_docs = self._shorthand_docs(argument_model.value, stack)
finally:
stack.pop()
start = 'KeyName1=%s,KeyName2=%s' % (value_docs, value_docs)
if k.enum and not stack:
start += '\n\nWhere valid key names are:\n'
Expand Down
25 changes: 24 additions & 1 deletion tests/unit/test_argprocess.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -857,7 +857,12 @@ def test_skip_deeply_nested_shorthand(self):
'C': {
'type': 'structure',
'members': {
'D': {'type': 'string'},
'D': {
'type': 'structure',
'members': {
'E': {'type': 'string'},
},
}
},
}
},
Expand All @@ -869,6 +874,24 @@ def test_skip_deeply_nested_shorthand(self):
generated_example = self.get_generated_example_for(argument)
self.assertEqual(generated_example, '')

def test_structure_within_map(self):
argument = self.create_argument(
{
'A': {
'type': 'map',
'key': {'type': 'string'},
'value': {
'type': 'structure',
'members': {
'B': {'type': 'string'},
},
},
},
}
)
generated_example = self.get_generated_example_for(argument)
self.assertEqual('A={KeyName1={B=string},KeyName2={B=string}}', generated_example)


class TestUnpackJSONParams(BaseArgProcessTest):
def setUp(self):
Expand Down
Loading