osc-lib 3.1.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

osc_lib/cli/pagination.py

@@ -0,0 +1,83 @@
+# 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.
+
+import argparse
+
+from osc_lib.cli import parseractions
+from osc_lib.i18n import _
+
+
+def add_marker_pagination_option_to_parser(
+    parser: argparse.ArgumentParser,
+) -> None:
+    """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: argparse.ArgumentParser,
+) -> None:
+    """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.'
+        ),
+    )

osc_lib/cli/parseractions.py

@@ -16,9 +16,13 @@
 """argparse Custom Actions"""
 
 import argparse
+import collections.abc
+import typing as ty
 
 from osc_lib.i18n import _
 
+_T = ty.TypeVar('_T')
+
 
 class KeyValueAction(argparse.Action):
     """A custom action to parse arguments as key=value pairs
@@ -26,7 +30,16 @@ class KeyValueAction(argparse.Action):
     Ensures that ``dest`` is a dict and values are strings.
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
+        if not isinstance(values, str):
+            raise TypeError('expected str')
+
         # Make sure we have an empty dict rather than None
         if getattr(namespace, self.dest, None) is None:
             setattr(namespace, self.dest, {})
@@ -37,12 +50,12 @@ class KeyValueAction(argparse.Action):
             # NOTE(qtang): Prevent null key setting in property
             if '' == values_list[0]:
                 msg = _("Property key must be specified: %s")
-                raise argparse.ArgumentTypeError(msg % str(values))
+                raise argparse.ArgumentError(self, msg % str(values))
             else:
-                getattr(namespace, self.dest, {}).update([values_list])
+                getattr(namespace, self.dest, {}).update(dict([values_list]))
         else:
             msg = _("Expected 'key=value' type, but got: %s")
-            raise argparse.ArgumentTypeError(msg % str(values))
+            raise argparse.ArgumentError(self, msg % str(values))
 
 
 class KeyValueAppendAction(argparse.Action):
@@ -51,7 +64,16 @@ class KeyValueAppendAction(argparse.Action):
     Ensures that ``dest`` is a dict and values are lists of strings.
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
+        if not isinstance(values, str):
+            raise TypeError('expected str')
+
         # Make sure we have an empty dict rather than None
         if getattr(namespace, self.dest, None) is None:
             setattr(namespace, self.dest, {})
@@ -62,7 +84,7 @@ class KeyValueAppendAction(argparse.Action):
             # NOTE(qtang): Prevent null key setting in property
             if '' == key:
                 msg = _("Property key must be specified: %s")
-                raise argparse.ArgumentTypeError(msg % str(values))
+                raise argparse.ArgumentError(self, msg % str(values))
 
             dest = getattr(namespace, self.dest)
             if key in dest:
@@ -71,7 +93,7 @@ class KeyValueAppendAction(argparse.Action):
                 dest[key] = [value]
         else:
             msg = _("Expected 'key=value' type, but got: %s")
-            raise argparse.ArgumentTypeError(msg % str(values))
+            raise argparse.ArgumentError(self, msg % str(values))
 
 
 class MultiKeyValueAction(argparse.Action):
@@ -86,13 +108,19 @@ class MultiKeyValueAction(argparse.Action):
 
     def __init__(
         self,
-        option_strings,
-        dest,
-        nargs=None,
-        required_keys=None,
-        optional_keys=None,
-        **kwargs
-    ):
+        option_strings: ty.Sequence[str],
+        dest: str,
+        nargs: ty.Union[int, str, None] = None,
+        required_keys: ty.Optional[ty.Sequence[str]] = None,
+        optional_keys: ty.Optional[ty.Sequence[str]] = None,
+        const: ty.Optional[_T] = None,
+        default: ty.Union[_T, str, None] = None,
+        type: ty.Optional[collections.abc.Callable[[str], _T]] = None,
+        choices: ty.Optional[collections.abc.Iterable[_T]] = None,
+        required: bool = False,
+        help: ty.Optional[str] = None,
+        metavar: ty.Union[str, tuple[str, ...], None] = None,
+    ) -> None:
         """Initialize the action object, and parse customized options
 
         Required keys and optional keys can be specified when initializing
@@ -106,14 +134,24 @@ class MultiKeyValueAction(argparse.Action):
             msg = _("Parameter 'nargs' is not allowed, but got %s")
             raise ValueError(msg % nargs)
 
-        super(MultiKeyValueAction, self).__init__(
-            option_strings, dest, **kwargs
+        super().__init__(
+            option_strings,
+            dest,
+            nargs=nargs,
+            const=const,
+            default=default,
+            type=type,
+            choices=choices,
+            required=required,
+            help=help,
+            metavar=metavar,
         )
 
         # required_keys: A list of keys that is required. None by default.
         if required_keys and not isinstance(required_keys, list):
             msg = _("'required_keys' must be a list")
             raise TypeError(msg)
+
         self.required_keys = set(required_keys or [])
 
         # optional_keys: A list of keys that is optional. None by default.
@@ -122,7 +160,7 @@ class MultiKeyValueAction(argparse.Action):
             raise TypeError(msg)
         self.optional_keys = set(optional_keys or [])
 
-    def validate_keys(self, keys):
+    def validate_keys(self, keys: ty.Sequence[str]) -> None:
         """Validate the provided keys.
 
         :param keys: A list of keys to validate.
@@ -136,12 +174,13 @@ class MultiKeyValueAction(argparse.Action):
                     "Invalid keys %(invalid_keys)s specified.\n"
                     "Valid keys are: %(valid_keys)s"
                 )
-                raise argparse.ArgumentTypeError(
+                raise argparse.ArgumentError(
+                    self,
                     msg
                     % {
                         'invalid_keys': ', '.join(invalid_keys),
                         'valid_keys': ', '.join(valid_keys),
-                    }
+                    },
                 )
 
         if self.required_keys:
@@ -151,35 +190,45 @@ class MultiKeyValueAction(argparse.Action):
                     "Missing required keys %(missing_keys)s.\n"
                     "Required keys are: %(required_keys)s"
                 )
-                raise argparse.ArgumentTypeError(
+                raise argparse.ArgumentError(
+                    self,
                     msg
                     % {
                         'missing_keys': ', '.join(missing_keys),
                         'required_keys': ', '.join(self.required_keys),
-                    }
+                    },
                 )
 
-    def __call__(self, parser, namespace, values, metavar=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
+        if not isinstance(values, str):
+            raise TypeError('expected str')
+
         # Make sure we have an empty list rather than None
         if getattr(namespace, self.dest, None) is None:
             setattr(namespace, self.dest, [])
 
-        params = {}
+        params: dict[str, str] = {}
         for kv in values.split(','):
-            # Add value if an assignment else raise ArgumentTypeError
+            # Add value if an assignment else raise ArgumentError
             if '=' in kv:
                 kv_list = kv.split('=', 1)
                 # NOTE(qtang): Prevent null key setting in property
                 if '' == kv_list[0]:
                     msg = _("Each property key must be specified: %s")
-                    raise argparse.ArgumentTypeError(msg % str(kv))
+                    raise argparse.ArgumentError(self, msg % str(kv))
                 else:
-                    params.update([kv_list])
+                    params.update(dict([kv_list]))
             else:
                 msg = _(
                     "Expected comma separated 'key=value' pairs, but got: %s"
                 )
-                raise argparse.ArgumentTypeError(msg % str(kv))
+                raise argparse.ArgumentError(self, msg % str(kv))
 
         # Check key validation
         self.validate_keys(list(params))
@@ -196,38 +245,48 @@ class MultiKeyValueCommaAction(MultiKeyValueAction):
     Ex. key1=val1,val2,key2=val3 => {"key1": "val1,val2", "key2": "val3"}
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
         """Overwrite the __call__ function of MultiKeyValueAction
 
         This is done to handle scenarios where we may have comma seperated
         data as a single value.
         """
+        if not isinstance(values, str):
+            msg = _("Invalid key=value pair, non-string value provided: %s")
+            raise argparse.ArgumentError(self, msg % str(values))
+
         # Make sure we have an empty list rather than None
         if getattr(namespace, self.dest, None) is None:
             setattr(namespace, self.dest, [])
 
-        params = {}
+        params: dict[str, str] = {}
         key = ''
         for kv in values.split(','):
-            # Add value if an assignment else raise ArgumentTypeError
+            # Add value if an assignment else raise ArgumentError
             if '=' in kv:
                 kv_list = kv.split('=', 1)
                 # NOTE(qtang): Prevent null key setting in property
                 if '' == kv_list[0]:
                     msg = _("A key must be specified before '=': %s")
-                    raise argparse.ArgumentTypeError(msg % str(kv))
+                    raise argparse.ArgumentError(self, msg % str(kv))
                 else:
-                    params.update([kv_list])
+                    params.update(dict([kv_list]))
                 key = kv_list[0]
             else:
                 # If the ',' split does not have key=value pair, then it
                 # means the current value is a part of the previous
                 # key=value pair, so append it.
                 try:
-                    params[key] = "%s,%s" % (params[key], kv)
+                    params[key] = f"{params[key]},{kv}"
                 except KeyError:
                     msg = _("A key=value pair is required: %s")
-                    raise argparse.ArgumentTypeError(msg % str(kv))
+                    raise argparse.ArgumentError(self, msg % str(kv))
 
         # Check key validation
         self.validate_keys(list(params))
@@ -245,7 +304,17 @@ class RangeAction(argparse.Action):
     '6:9' sets ``dest`` to (6, 9)
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
+        if not isinstance(values, str):
+            msg = _("Invalid range, non-string value provided")
+            raise argparse.ArgumentError(self, msg)
+
         range = values.split(':')
         if len(range) == 0:
             # Nothing passed, return a zero default
@@ -279,9 +348,19 @@ class NonNegativeAction(argparse.Action):
     Ensures the value is >= 0.
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: ty.Union[str, ty.Sequence[ty.Any], None],
+        option_string: ty.Optional[str] = None,
+    ) -> None:
+        if not isinstance(values, (str, int, float)):
+            msg = _("%s expected a non-negative integer")
+            raise argparse.ArgumentError(self, msg % str(option_string))
+
         if int(values) >= 0:
             setattr(namespace, self.dest, values)
         else:
             msg = _("%s expected a non-negative integer")
-            raise argparse.ArgumentTypeError(msg % str(option_string))
+            raise argparse.ArgumentError(self, msg % str(option_string))

osc_lib/clientmanager.py

@@ -17,7 +17,12 @@
 
 import copy
 import logging
+import typing as ty
+import warnings
 
+from keystoneauth1 import access as ksa_access
+from keystoneauth1 import session as ksa_session
+from openstack.config import cloud_region
 from openstack.config import loader as config  # noqa
 from openstack import connection
 from oslo_utils import strutils
@@ -25,20 +30,23 @@ from oslo_utils import strutils
 from osc_lib.api import auth
 from osc_lib import exceptions
 
-
 LOG = logging.getLogger(__name__)
 
-PLUGIN_MODULES = []
-
 
-class ClientCache(object):
+class ClientCache:
     """Descriptor class for caching created client handles."""
 
-    def __init__(self, factory):
+    def __init__(self, factory: ty.Any) -> None:
+        warnings.warn(
+            "The ClientCache class is deprecated for removal as it has no "
+            "users.",
+            category=DeprecationWarning,
+        )
+
         self.factory = factory
         self._handle = None
 
-    def __get__(self, instance, owner):
+    def __get__(self, instance: ty.Any, owner: ty.Any) -> ty.Any:
         # Tell the ClientManager to login to keystone
         if self._handle is None:
             try:
@@ -50,9 +58,15 @@ class ClientCache(object):
         return self._handle
 
 
-class ClientManager(object):
+class _PasswordHelper(ty.Protocol):
+    def __call__(self, prompt: ty.Optional[str] = None) -> str: ...
+
+
+class ClientManager:
     """Manages access to API clients, including authentication."""
 
+    session: ksa_session.Session
+
     # NOTE(dtroyer): Keep around the auth required state of the _current_
     #                command since ClientManager has no visibility to the
     #                command itself; assume auth is not required.
@@ -60,12 +74,12 @@ class ClientManager(object):
 
     def __init__(
         self,
-        cli_options=None,
-        api_version=None,
-        pw_func=None,
-        app_name=None,
-        app_version=None,
-    ):
+        cli_options: cloud_region.CloudRegion,
+        api_version: ty.Optional[dict[str, str]],
+        pw_func: ty.Optional[_PasswordHelper] = None,
+        app_name: ty.Optional[str] = None,
+        app_version: ty.Optional[str] = None,
+    ) -> None:
         """Set up a ClientManager
 
         :param cli_options:
@@ -93,7 +107,6 @@ class ClientManager(object):
         self.timing = self._cli_options.timing
 
         self._auth_ref = None
-        self.session = None
 
         # self.verify is the Requests-compatible form
         # self.cacert is the form used by the legacy client libs
@@ -124,7 +137,7 @@ class ClientManager(object):
         # prior to dereferrencing auth_ref.
         self._auth_setup_completed = False
 
-    def setup_auth(self):
+    def setup_auth(self) -> None:
         """Set up authentication
 
         This is deferred until authentication is actually attempted because
@@ -145,12 +158,14 @@ class ClientManager(object):
 
         # Horrible hack alert...must handle prompt for null password if
         # password auth is requested.
-        if self.auth_plugin_name.endswith(
-            'password'
-        ) and not self._cli_options.auth.get('password'):
+        if (
+            self.auth_plugin_name.endswith('password')
+            and not self._cli_options.auth.get('password')
+            and self._pw_callback is not None
+        ):
             self._cli_options.auth['password'] = self._pw_callback()
 
-        LOG.info('Using auth plugin: %s', self.auth_plugin_name)
+        LOG.debug('Using auth plugin: %s', self.auth_plugin_name)
         LOG.debug(
             'Using parameters %s',
             strutils.mask_password(self._cli_options.auth),
@@ -177,7 +192,10 @@ class ClientManager(object):
 
         self._auth_setup_completed = True
 
-    def validate_scope(self):
+    def validate_scope(self) -> None:
+        if not self._auth_ref:
+            raise Exception('no authentication information')
+
         if self._auth_ref.project_id is not None:
             # We already have a project scope.
             return
@@ -194,7 +212,7 @@ class ClientManager(object):
         )
 
     @property
-    def auth_ref(self):
+    def auth_ref(self) -> ty.Optional[ksa_access.AccessInfo]:
         """Dereference will trigger an auth if it hasn't already"""
         if (
             not self._auth_required
@@ -208,11 +226,11 @@ class ClientManager(object):
             self._auth_ref = self.auth.get_auth_ref(self.session)
         return self._auth_ref
 
-    def _override_for(self, service_type):
-        key = '%s_endpoint_override' % service_type.replace('-', '_')
-        return self._cli_options.config.get(key)
+    def _override_for(self, service_type: str) -> ty.Optional[str]:
+        key = '{}_endpoint_override'.format(service_type.replace('-', '_'))
+        return ty.cast(ty.Optional[str], self._cli_options.config.get(key))
 
-    def is_service_available(self, service_type):
+    def is_service_available(self, service_type: str) -> ty.Optional[bool]:
         """Check if a service type is in the current Service Catalog"""
         # If there is an override, assume the service is available
         if self._override_for(service_type):
@@ -236,8 +254,11 @@ class ClientManager(object):
         return service_available
 
     def get_endpoint_for_service_type(
-        self, service_type, region_name=None, interface='public'
-    ):
+        self,
+        service_type: str,
+        region_name: ty.Optional[str] = None,
+        interface: str = 'public',
+    ) -> ty.Optional[str]:
         """Return the endpoint URL for the service type."""
         # Overrides take priority unconditionally
         override = self._override_for(service_type)
@@ -262,5 +283,5 @@ class ClientManager(object):
             )
         return endpoint
 
-    def get_configuration(self):
+    def get_configuration(self) -> dict[str, ty.Any]:
         return copy.deepcopy(self._cli_options.config)

osc_lib/command/command.py

@@ -13,7 +13,9 @@
 #   under the License.
 
 import abc
+import argparse
 import logging
+import typing as ty
 
 from cliff import command
 from cliff import lister
@@ -24,20 +26,27 @@ from osc_lib.i18n import _
 
 
 class CommandMeta(abc.ABCMeta):
-    def __new__(mcs, name, bases, cls_dict):
-        if 'log' not in cls_dict:
-            cls_dict['log'] = logging.getLogger(
-                cls_dict['__module__'] + '.' + name
+    def __new__(
+        mcs: type['CommandMeta'],
+        name: str,
+        bases: tuple[type[ty.Any], ...],
+        namespace: dict[str, ty.Any],
+    ) -> 'CommandMeta':
+        if 'log' not in namespace:
+            namespace['log'] = logging.getLogger(
+                namespace['__module__'] + '.' + name
             )
-        return super(CommandMeta, mcs).__new__(mcs, name, bases, cls_dict)
+        return super().__new__(mcs, name, bases, namespace)
 
 
 class Command(command.Command, metaclass=CommandMeta):
-    def run(self, parsed_args):
+    log: logging.Logger
+
+    def run(self, parsed_args: argparse.Namespace) -> int:
         self.log.debug('run(%s)', parsed_args)
-        return super(Command, self).run(parsed_args)
+        return super().run(parsed_args)
 
-    def validate_os_beta_command_enabled(self):
+    def validate_os_beta_command_enabled(self) -> None:
         if not self.app.options.os_beta_command:
             msg = _(
                 'Caution: This is a beta command and subject to '
@@ -46,7 +55,9 @@ class Command(command.Command, metaclass=CommandMeta):
             )
             raise exceptions.CommandError(msg)
 
-    def deprecated_option_warning(self, old_option, new_option):
+    def deprecated_option_warning(
+        self, old_option: str, new_option: str
+    ) -> None:
         """Emit a warning for use of a deprecated option"""
         self.log.warning(
             _("The %(old)s option is deprecated, please use %(new)s instead.")

osc_lib/command/timing.py

@@ -13,13 +13,23 @@
 
 """Timing Implementation"""
 
+import argparse
+import typing as ty
+
 from osc_lib.command import command
 
+if ty.TYPE_CHECKING:
+    from osc_lib import shell
+
 
 class Timing(command.Lister):
     """Show timing data"""
 
-    def take_action(self, parsed_args):
+    app: 'shell.OpenStackShell'
+
+    def take_action(
+        self, parsed_args: argparse.Namespace
+    ) -> tuple[tuple[str, ...], list[ty.Any]]:
         column_headers = (
             'URL',
             'Seconds',

osc_lib/exceptions.py

@@ -15,6 +15,8 @@
 
 """Exception definitions."""
 
+import typing as ty
+
 
 class CommandError(Exception):
     pass
@@ -59,7 +61,15 @@ class InvalidValue(Exception):
 class ClientException(Exception):
     """The base exception class for all exceptions this library raises."""
 
-    def __init__(self, code, message=None, details=None):
+    http_status: int
+    message: str
+
+    def __init__(
+        self,
+        code: ty.Union[int, str],
+        message: ty.Optional[str] = None,
+        details: ty.Optional[str] = None,
+    ):
         if not isinstance(code, int) and message is None:
             message = code
             code = self.http_status
@@ -67,8 +77,8 @@ class ClientException(Exception):
         self.message = message or self.__class__.message
         self.details = details
 
-    def __str__(self):
-        return "%s (HTTP %s)" % (self.message, self.code)
+    def __str__(self) -> str:
+        return f"{self.message} (HTTP {self.code})"
 
 
 class BadRequest(ClientException):