[v2] Document minimum and maximum constraints for --page-size (#10413)

Surface min/max value constraints for service-modeled page-sizes in generated documentation and `aws help` pages.

Author: aemous

.changes/next-release/enhancement-Documentation-93552.json

@@ -0,0 +1,5 @@
+{
+  "type": "enhancement",
+  "category": "Documentation",
+  "description": "Update documentation generation so that minimum and maximum value constraints for `--page-size` are surfaced in documentation."
+}

awscli/customizations/paginate.py

@@ -187,6 +187,7 @@ def unify_paging_params(
                 PAGE_SIZE_HELP,
                 parse_type=type_name,
                 serialized_name='PageSize',
+                shape_metadata=limit_key_shape.metadata,
             ),
             shadowed_args,
         )
@@ -367,8 +368,22 @@ class PageArgument(BaseCLIArgument):
         'long': int,
     }
 
-    def __init__(self, name, documentation, parse_type, serialized_name):
-        self.argument_model = model.Shape('PageArgument', {'type': 'string'})
+    SHAPE_CONSTRAINT_KEYS = ('min', 'max')
+
+    def __init__(
+        self,
+        name,
+        documentation,
+        parse_type,
+        serialized_name,
+        shape_metadata=None,
+    ):
+        shape_model = {'type': parse_type}
+        if shape_metadata:
+            for key in self.SHAPE_CONSTRAINT_KEYS:
+                if key in shape_metadata:
+                    shape_model[key] = shape_metadata[key]
+        self.argument_model = model.Shape('PageArgument', shape_model)
         self._name = name
         self._serialized_name = serialized_name
         self._documentation = documentation

tests/functional/docs/test_help_output.py

@@ -353,6 +353,26 @@ def test_paging_documentation_added(self):
         self.assert_contains('When using ``--output text`` and the')
         self.assert_contains('following query expressions: ')
 
+    def test_page_size_documents_constraints(self):
+        session = self.driver.session
+        paginator_config = session.get_paginator_model('s3').get_paginator(
+            'ListBuckets'
+        )
+        limit_key = paginator_config['limit_key']
+        operation_model = session.get_service_model('s3').operation_model(
+            'ListBuckets'
+        )
+        shape_metadata = operation_model.input_shape.members[
+            limit_key
+        ].metadata
+
+        self.driver.main(['s3api', 'list-buckets', 'help'])
+        self.assert_contains('``--page-size``')
+        for constraint in ('min', 'max'):
+            value = shape_metadata.get(constraint)
+            if value is not None:
+                self.assert_contains(f'{constraint}: ``{value}``')
+
 
 class TestMergeBooleanGroupArgs(BaseAWSHelpOutputTest):
     def test_merge_bool_args(self):

tests/unit/customizations/test_paginate.py

@@ -46,6 +46,7 @@ def setUp(self):
         self.bar_param = mock.Mock()
         self.bar_param.type_name = 'string'
         self.bar_param.name = 'Bar'
+        self.bar_param.metadata = {}
         self.params = [self.foo_param, self.bar_param]
         self.operation_model.input_shape.members = {
             "Foo": self.foo_param,
@@ -437,6 +438,59 @@ def test_can_handle_missing_page_size(self):
         )
 
 
+class TestPageSizeConstraints(TestPaginateBase):
+    def test_page_size_copies_min_max_from_limit_key_shape(self):
+        self.bar_param.type_name = 'integer'
+        self.bar_param.metadata = {'min': 1, 'max': 100}
+        argument_table = {
+            'foo': mock.Mock(),
+            'bar': mock.Mock(),
+        }
+        paginate.unify_paging_params(
+            argument_table,
+            self.operation_model,
+            'building-argument-table.foo.bar',
+            self.session,
+        )
+        page_size_arg = argument_table['page-size']
+        self.assertEqual(page_size_arg.argument_model.metadata.get('min'), 1)
+        self.assertEqual(page_size_arg.argument_model.metadata.get('max'), 100)
+
+    def test_page_size_no_constraints_when_limit_key_has_none(self):
+        self.bar_param.type_name = 'integer'
+        self.bar_param.metadata = {}
+        argument_table = {
+            'foo': mock.Mock(),
+            'bar': mock.Mock(),
+        }
+        paginate.unify_paging_params(
+            argument_table,
+            self.operation_model,
+            'building-argument-table.foo.bar',
+            self.session,
+        )
+        page_size_arg = argument_table['page-size']
+        self.assertNotIn('min', page_size_arg.argument_model.metadata)
+        self.assertNotIn('max', page_size_arg.argument_model.metadata)
+
+    def test_page_size_copies_partial_constraints(self):
+        self.bar_param.type_name = 'integer'
+        self.bar_param.metadata = {'min': 1}
+        argument_table = {
+            'foo': mock.Mock(),
+            'bar': mock.Mock(),
+        }
+        paginate.unify_paging_params(
+            argument_table,
+            self.operation_model,
+            'building-argument-table.foo.bar',
+            self.session,
+        )
+        page_size_arg = argument_table['page-size']
+        self.assertEqual(page_size_arg.argument_model.metadata.get('min'), 1)
+        self.assertNotIn('max', page_size_arg.argument_model.metadata)
+
+
 class TestNonPositiveMaxItems:
     def test_positive_integer_does_not_raise_warning(
         self, max_items_page_arg, capsys