Add pagination helpers

Add some pagination helpers to configure pagination parameters for
various commands. Two pagination schemes are supported, based on what we
currently support across OSC commands: marker-based pagination and
offset-based pagination.

Change-Id: I551bb4c3ff0568c6df5244a1d0f0669497bee58f
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

openstackclient/common/pagination.py

@@ -0,0 +1,82 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from osc_lib.cli import parseractions
+
+from openstackclient.i18n import _
+
+
+# TODO(stephenfin): Consider moving these to osc-lib since they're broadly
+# useful
+
+
+def add_marker_pagination_option_to_parser(parser):
+    """Add marker-based pagination options to the parser.
+
+    APIs that use marker-based paging use the marker and limit query parameters
+    to paginate through items in a collection.
+
+    Marker-based pagination is often used in cases where the length of the
+    total set of items is either changing frequently, or where the total length
+    might not be known upfront.
+    """
+    parser.add_argument(
+        '--limit',
+        metavar='<limit>',
+        type=int,
+        action=parseractions.NonNegativeAction,
+        help=_(
+            'The maximum number of entries to return. If the value exceeds '
+            'the server-defined maximum, then the maximum value will be used.'
+        ),
+    )
+    parser.add_argument(
+        '--marker',
+        metavar='<marker>',
+        default=None,
+        help=_(
+            'The first position in the collection to return results from. '
+            'This should be a value that was returned in a previous request.'
+        ),
+    )
+
+
+def add_offset_pagination_option_to_parser(parser):
+    """Add offset-based pagination options to the parser.
+
+    APIs that use offset-based paging use the offset and limit query parameters
+    to paginate through items in a collection.
+
+    Offset-based pagination is often used where the list of items is of a fixed
+    and predetermined length.
+    """
+    parser.add_argument(
+        '--limit',
+        metavar='<limit>',
+        type=int,
+        action=parseractions.NonNegativeAction,
+        help=_(
+            'The maximum number of entries to return. If the value exceeds '
+            'the server-defined maximum, then the maximum value will be used.'
+        ),
+    )
+    parser.add_argument(
+        '--offset',
+        metavar='<offset>',
+        type=int,
+        action=parseractions.NonNegativeAction,
+        default=None,
+        help=_(
+            'The (zero-based) offset of the first item in the collection to '
+            'return.'
+        ),
+    )

openstackclient/compute/v2/flavor.py

@@ -25,6 +25,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -292,22 +293,7 @@ class ListFlavor(command.Lister):
             default=False,
             help=_("List additional fields in output"),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar="<flavor-id>",
-            help=_("The last flavor ID of the previous page"),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            metavar='<num-flavors>',
-            help=_(
-                'Maximum number of flavors to display. This is also '
-                'configurable on the server. The actual limit used will be '
-                'the lower of the user-supplied value and the server '
-                'configuration-derived value'
-            ),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/compute/v2/hypervisor.py

@@ -25,6 +25,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
 
@@ -80,27 +81,7 @@ class ListHypervisor(command.Lister):
                 "when using microversion 2.52 or lower"
             ),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<marker>',
-            help=_(
-                "The UUID of the last hypervisor of the previous page; "
-                "displays list of hypervisors after 'marker'. "
-                "(supported with --os-compute-api-version 2.33 or above)"
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            metavar='<limit>',
-            type=int,
-            help=_(
-                "Maximum number of hypervisors to display. Note that there "
-                "is a configurable max limit on the server, and the limit "
-                "that is used will be the minimum of what is requested "
-                "here and what is configured in the server. "
-                "(supported with --os-compute-api-version 2.33 or above)"
-            ),
-        )
         parser.add_argument(
             '--long',
             action='store_true',

openstackclient/compute/v2/keypair.py

@@ -27,6 +27,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -296,15 +297,7 @@ class ListKeypair(command.Lister):
             ),
         )
         identity_common.add_project_domain_option_to_parser(parser)
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            help=_('The last keypair ID of the previous page'),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            help=_('Maximum number of keypairs to display'),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/compute/v2/server.py

@@ -33,6 +33,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 from openstackclient.network import common as network_common
@@ -2370,29 +2371,7 @@ class ListServer(command.Lister):
                 'Mutually exclusive with "--no-name-lookup|-n" option.'
             ),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<server>',
-            default=None,
-            help=_(
-                'The last server of the previous page. Display '
-                'list of servers after marker. Display all servers if not '
-                'specified. When used with ``--deleted``, the marker must '
-                'be an ID, otherwise a name or ID can be used.'
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            metavar='<num-servers>',
-            type=int,
-            default=None,
-            help=_(
-                "Maximum number of servers to display. If limit equals -1, "
-                "all servers will be displayed. If limit is greater than "
-                "'osapi_max_limit' option of Nova API, "
-                "'osapi_max_limit' will be used instead."
-            ),
-        )
         parser.add_argument(
             '--changes-before',
             metavar='<changes-before>',

openstackclient/compute/v2/server_event.py

@@ -26,6 +26,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
 LOG = logging.getLogger(__name__)
@@ -143,21 +144,7 @@ class ListServerEvent(command.Lister):
                 "(supported with --os-compute-api-version 2.66 or above)"
             ),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            help=_(
-                'The last server event ID of the previous page '
-                '(supported by --os-compute-api-version 2.58 or above)'
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            help=_(
-                'Maximum number of server events to display '
-                '(supported by --os-compute-api-version 2.58 or above)'
-            ),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/compute/v2/server_group.py

@@ -24,9 +24,9 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
-
 LOG = logging.getLogger(__name__)
 
 
@@ -191,28 +191,7 @@ class ListServerGroup(command.Lister):
         )
         # TODO(stephenfin): This should really be a --marker option, but alas
         # the API doesn't support that for some reason
-        parser.add_argument(
+        pagination.add_offset_pagination_option_to_parser(parser)
-            '--offset',
-            metavar='<offset>',
-            type=int,
-            default=None,
-            help=_(
-                'Index from which to start listing servers. This should '
-                'typically be a factor of --limit. Display all servers groups '
-                'if not specified.'
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            metavar='<limit>',
-            type=int,
-            default=None,
-            help=_(
-                "Maximum number of server groups to display. "
-                "If limit is greater than 'osapi_max_limit' option of Nova "
-                "API, 'osapi_max_limit' will be used instead."
-            ),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/compute/v2/server_migration.py

@@ -19,6 +19,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -54,28 +55,7 @@ class ListMigration(command.Lister):
             ],
             help=_('Filter migrations by type'),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<marker>',
-            help=_(
-                "The last migration of the previous page; displays list "
-                "of migrations after 'marker'. Note that the marker is "
-                "the migration UUID. "
-                "(supported with --os-compute-api-version 2.59 or above)"
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            metavar='<limit>',
-            type=int,
-            help=_(
-                "Maximum number of migrations to display. Note that there "
-                "is a configurable max limit on the server, and the limit "
-                "that is used will be the minimum of what is requested "
-                "here and what is configured in the server. "
-                "(supported with --os-compute-api-version 2.59 or above)"
-            ),
-        )
         parser.add_argument(
             '--changes-since',
             dest='changes_since',

openstackclient/image/v2/image.py

@@ -31,6 +31,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.common import progressbar
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
@@ -805,9 +806,9 @@ class ListImage(command.Lister):
             default=False,
             help=_('List additional fields in output'),
         )
-
         # --page-size has never worked, leave here for silent compatibility
         # We'll implement limit/marker differently later
+        # TODO(stephenfin): Remove this in the next major version bump
         parser.add_argument(
             "--page-size",
             metavar="<size>",
@@ -823,22 +824,7 @@ class ListImage(command.Lister):
                 "specified separated by comma"
             ),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            "--limit",
-            metavar="<num-images>",
-            type=int,
-            help=_("Maximum number of images to display."),
-        )
-        parser.add_argument(
-            '--marker',
-            metavar='<image>',
-            default=None,
-            help=_(
-                "The last image of the previous page. Display "
-                "list of images after marker. Display all images if not "
-                "specified. (name or ID)"
-            ),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/object/v1/container.py

@@ -22,9 +22,9 @@ from osc_lib.cli import parseractions
 from osc_lib.command import command
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
-
 LOG = logging.getLogger(__name__)
 
 
@@ -127,22 +127,12 @@ class ListContainer(command.Lister):
             metavar="<prefix>",
             help=_("Filter list using <prefix>"),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            "--marker",
-            metavar="<marker>",
-            help=_("Anchor for paging"),
-        )
         parser.add_argument(
             "--end-marker",
             metavar="<end-marker>",
             help=_("End anchor for paging"),
         )
-        parser.add_argument(
-            "--limit",
-            metavar="<num-containers>",
-            type=int,
-            help=_("Limit the number of containers returned"),
-        )
         parser.add_argument(
             '--long',
             action='store_true',

openstackclient/object/v1/object.py

@@ -23,6 +23,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
 
@@ -140,22 +141,12 @@ class ListObject(command.Lister):
             metavar="<delimiter>",
             help=_("Roll up items with <delimiter>"),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            "--marker",
-            metavar="<marker>",
-            help=_("Anchor for paging"),
-        )
         parser.add_argument(
             "--end-marker",
             metavar="<end-marker>",
             help=_("End anchor for paging"),
         )
-        parser.add_argument(
-            "--limit",
-            metavar="<num-objects>",
-            type=int,
-            help=_("Limit the number of objects returned"),
-        )
         parser.add_argument(
             '--long',
             action='store_true',

openstackclient/volume/v1/volume.py

@@ -26,6 +26,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
 
@@ -372,20 +373,7 @@ class ListVolume(command.Lister):
             default=False,
             help=_('List additional fields in output'),
         )
-        parser.add_argument(
+        pagination.add_offset_pagination_option_to_parser(parser)
-            '--offset',
-            type=int,
-            action=parseractions.NonNegativeAction,
-            metavar='<offset>',
-            help=_('Index from which to start listing volumes'),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            action=parseractions.NonNegativeAction,
-            metavar='<num-volumes>',
-            help=_('Maximum number of volumes to display'),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/volume/v2/volume.py

@@ -26,6 +26,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -456,18 +457,7 @@ class ListVolume(command.Lister):
             default=False,
             help=_('List additional fields in output'),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<volume>',
-            help=_('The last volume ID of the previous page'),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            action=parseractions.NonNegativeAction,
-            metavar='<num-volumes>',
-            help=_('Maximum number of volumes to display'),
-        )
         return parser
 
     def take_action(self, parsed_args):

openstackclient/volume/v2/volume_backup.py

@@ -26,9 +26,9 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 
-
 LOG = logging.getLogger(__name__)
 
 
@@ -272,18 +272,7 @@ class ListVolumeBackup(command.Lister):
                 "Filters results by the volume which they backup (name or ID)"
             ),
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<volume-backup>',
-            help=_('The last backup of the previous page (name or ID)'),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            action=parseractions.NonNegativeAction,
-            metavar='<num-backups>',
-            help=_('Maximum number of backups to display'),
-        )
         parser.add_argument(
             '--all-projects',
             action='store_true',

openstackclient/volume/v2/volume_snapshot.py

@@ -25,6 +25,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -228,18 +229,6 @@ class ListVolumeSnapshot(command.Lister):
             default=False,
             help=_('List additional fields in output'),
         )
-        parser.add_argument(
-            '--marker',
-            metavar='<volume-snapshot>',
-            help=_('The last snapshot ID of the previous page'),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            action=parseractions.NonNegativeAction,
-            metavar='<num-snapshots>',
-            help=_('Maximum number of snapshots to display'),
-        )
         parser.add_argument(
             '--name',
             metavar='<name>',
@@ -268,6 +257,7 @@ class ListVolumeSnapshot(command.Lister):
             default=None,
             help=_('Filters results by a volume (name or ID).'),
         )
+        pagination.add_marker_pagination_option_to_parser(parser)
         return parser
 
     def take_action(self, parsed_args):

openstackclient/volume/v3/volume_attachment.py

@@ -18,6 +18,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -410,20 +411,7 @@ class ListVolumeAttachment(command.Lister):
             metavar='<status>',
             help=_('Filters results by a status. ') + _FILTER_DEPRECATED,
         )
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<marker>',
-            help=_(
-                'Begin returning volume attachments that appear later in '
-                'volume attachment list than that represented by this ID.'
-            ),
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            metavar='<limit>',
-            help=_('Maximum number of volume attachments to return.'),
-        )
         # TODO(stephenfin): Add once we have an equivalent command for
         # 'cinder list-filters'
         # parser.add_argument(

openstackclient/volume/v3/volume_message.py

@@ -21,6 +21,7 @@ from osc_lib.command import command
 from osc_lib import exceptions
 from osc_lib import utils
 
+from openstackclient.common import pagination
 from openstackclient.i18n import _
 from openstackclient.identity import common as identity_common
 
@@ -78,19 +79,7 @@ class ListMessages(command.Lister):
             help=_('Filter results by project (name or ID) (admin only)'),
         )
         identity_common.add_project_domain_option_to_parser(parser)
-        parser.add_argument(
+        pagination.add_marker_pagination_option_to_parser(parser)
-            '--marker',
-            metavar='<message-id>',
-            help=_('The last message ID of the previous page'),
-            default=None,
-        )
-        parser.add_argument(
-            '--limit',
-            type=int,
-            metavar='<limit>',
-            help=_('Maximum number of messages to display'),
-            default=None,
-        )
 
         return parser