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

osc_lib/api/api.py

@@ -13,6 +13,10 @@
 
 """Base API Library"""
 
+import builtins
+import typing as ty
+import warnings
+
 from keystoneauth1 import exceptions as ksa_exceptions
 from keystoneauth1 import session as ksa_session
 import requests
@@ -42,8 +46,12 @@ class BaseAPI:
     HEADER_NAME = "OpenStack-API-Version"
 
     def __init__(
-        self, session=None, service_type=None, endpoint=None, **kwargs
-    ):
+        self,
+        session: ty.Optional[ksa_session.Session] = None,
+        service_type: ty.Optional[str] = None,
+        endpoint: ty.Optional[str] = None,
+        **kwargs: ty.Any,
+    ) -> None:
         """Base object that contains some common API objects and methods
 
         :param keystoneauth1.session.Session session:
@@ -58,6 +66,12 @@ class BaseAPI:
             Keyword arguments passed to keystoneauth1.session.Session().
         """
 
+        warnings.warn(
+            'The BaseAPI class is deprecated for removal. Consider using '
+            'openstacksdk instead else vendoring this code into your client',
+            category=DeprecationWarning,
+        )
+
         super().__init__()
 
         # Create a keystoneauth1.session.Session if one is not supplied
@@ -69,7 +83,7 @@ class BaseAPI:
         self.service_type = service_type
         self.endpoint = self._munge_endpoint(endpoint)
 
-    def _munge_endpoint(self, endpoint):
+    def _munge_endpoint(self, endpoint: ty.Optional[str]) -> ty.Optional[str]:
         """Hook to allow subclasses to massage the passed-in endpoint
 
         Hook to massage passed-in endpoints from arbitrary sources,
@@ -90,7 +104,13 @@ class BaseAPI:
         else:
             return endpoint
 
-    def _request(self, method, url, session=None, **kwargs):
+    def _request(
+        self,
+        method: str,
+        url: str,
+        session: ty.Optional[ksa_session.Session] = None,
+        **kwargs: ty.Any,
+    ) -> requests.Response:
         """Perform call into session
 
         All API calls are funneled through this method to provide a common
@@ -136,7 +156,13 @@ class BaseAPI:
 
     # The basic action methods all take a Session and return dict/lists
 
-    def create(self, url, session=None, method=None, **params):
+    def create(
+        self,
+        url: str,
+        session: ty.Optional[ksa_session.Session] = None,
+        method: ty.Optional[str] = None,
+        **params: ty.Any,
+    ) -> ty.Union[requests.Response, ty.Any]:
         """Create a new resource
 
         :param string url:
@@ -156,7 +182,12 @@ class BaseAPI:
         except requests.JSONDecodeError:
             return ret
 
-    def delete(self, url, session=None, **params):
+    def delete(
+        self,
+        url: str,
+        session: ty.Optional[ksa_session.Session] = None,
+        **params: ty.Any,
+    ) -> requests.Response:
         """Delete a resource
 
         :param string url:
@@ -169,13 +200,13 @@ class BaseAPI:
 
     def list(
         self,
-        path,
-        session=None,
-        body=None,
-        detailed=False,
-        headers=None,
-        **params,
-    ):
+        path: str,
+        session: ty.Optional[ksa_session.Session] = None,
+        body: ty.Any = None,
+        detailed: bool = False,
+        headers: ty.Optional[dict[str, str]] = None,
+        **params: ty.Any,
+    ) -> ty.Union[requests.Response, ty.Any]:
         """Return a list of resources
 
         GET ${ENDPOINT}/${PATH}?${PARAMS}
@@ -226,11 +257,11 @@ class BaseAPI:
 
     def find_attr(
         self,
-        path,
-        value=None,
-        attr=None,
-        resource=None,
-    ):
+        path: str,
+        value: ty.Optional[str] = None,
+        attr: ty.Optional[str] = None,
+        resource: ty.Optional[str] = None,
+    ) -> ty.Any:
         """Find a resource via attribute or ID
 
         Most APIs return a list wrapped by a dict with the resource
@@ -260,7 +291,7 @@ class BaseAPI:
         if resource is None:
             resource = path
 
-        def getlist(kw):
+        def getlist(kw: dict[str, ty.Any]) -> ty.Any:
             """Do list call, unwrap resource dict if present"""
             ret = self.list(path, **kw)
             if isinstance(ret, dict) and resource in ret:
@@ -290,7 +321,12 @@ class BaseAPI:
             msg % {'resource': resource, 'attr': attr, 'value': value}
         )
 
-    def find_bulk(self, path, headers=None, **kwargs):
+    def find_bulk(
+        self,
+        path: str,
+        headers: ty.Optional[dict[str, str]] = None,
+        **kwargs: ty.Any,
+    ) -> builtins.list[ty.Any]:
         """Bulk load and filter locally
 
         :param string path:
@@ -318,7 +354,7 @@ class BaseAPI:
 
         return ret
 
-    def find_one(self, path, **kwargs):
+    def find_one(self, path: str, **kwargs: ty.Any) -> ty.Any:
         """Find a resource by name or ID
 
         :param string path:
@@ -339,11 +375,11 @@ class BaseAPI:
 
     def find(
         self,
-        path,
-        value=None,
-        attr=None,
-        headers=None,
-    ):
+        path: str,
+        value: ty.Optional[str] = None,
+        attr: ty.Optional[str] = None,
+        headers: ty.Optional[dict[str, str]] = None,
+    ) -> ty.Any:
         """Find a single resource by name or ID
 
         :param string path:
@@ -356,7 +392,7 @@ class BaseAPI:
             Headers dictionary to pass to requests
         """
 
-        def raise_not_found():
+        def raise_not_found() -> ty.NoReturn:
             msg = _("%s not found") % value
             raise exceptions.NotFound(404, msg)
 

osc_lib/api/auth.py

@@ -14,7 +14,9 @@
 """Authentication Library"""
 
 import argparse
+import typing as ty
 
+from keystoneauth1.identity import base as identity_base
 from keystoneauth1.identity.v3 import k2k
 from keystoneauth1.loading import base
 
@@ -22,16 +24,25 @@ from osc_lib import exceptions as exc
 from osc_lib.i18n import _
 from osc_lib import utils
 
+if ty.TYPE_CHECKING:
+    from openstack import connection
+
 
 # Initialize the list of Authentication plugins early in order
 # to get the command-line options
 PLUGIN_LIST = None
 
+
+class _OptionDict(ty.TypedDict):
+    env: str
+    help: str
+
+
 # List of plugin command line options
-OPTIONS_LIST = {}
+OPTIONS_LIST: dict[str, _OptionDict] = {}
 
 
-def get_plugin_list():
+def get_plugin_list() -> frozenset[str]:
     """Gather plugin list and cache it"""
 
     global PLUGIN_LIST
@@ -41,7 +52,7 @@ def get_plugin_list():
     return PLUGIN_LIST
 
 
-def get_options_list():
+def get_options_list() -> dict[str, _OptionDict]:
     """Gather plugin options so the help action has them available"""
 
     global OPTIONS_LIST
@@ -65,7 +76,10 @@ def get_options_list():
     return OPTIONS_LIST
 
 
-def check_valid_authorization_options(options, auth_plugin_name):
+def check_valid_authorization_options(
+    options: 'connection.Connection',
+    auth_plugin_name: str,
+) -> None:
     """Validate authorization options, and provide helpful error messages."""
     if (
         options.auth.get('project_id')
@@ -86,16 +100,15 @@ def check_valid_authorization_options(options, auth_plugin_name):
         )
 
 
-def check_valid_authentication_options(options, auth_plugin_name):
-    """Validate authentication options, and provide helpful error messages
-
-    :param required_scope: indicate whether a scoped token is required
-
-    """
-
+def check_valid_authentication_options(
+    options: 'connection.Connection',
+    auth_plugin_name: str,
+) -> None:
+    """Validate authentication options, and provide helpful error messages."""
     # Get all the options defined within the plugin.
-    plugin_opts = base.get_plugin_options(auth_plugin_name)
-    plugin_opts = {opt.dest: opt for opt in plugin_opts}
+    plugin_opts = {
+        opt.dest: opt for opt in base.get_plugin_options(auth_plugin_name)
+    }
 
     # NOTE(aloga): this is an horrible hack. We need a way to specify the
     # required options in the plugins. Using the "required" argument for
@@ -141,7 +154,9 @@ def check_valid_authentication_options(options, auth_plugin_name):
         )
 
 
-def build_auth_plugins_option_parser(parser):
+def build_auth_plugins_option_parser(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
     """Auth plugins options builder
 
     Builds dynamically the list of options expected by each available
@@ -206,13 +221,13 @@ def build_auth_plugins_option_parser(parser):
 
 
 def get_keystone2keystone_auth(
-    local_auth,
-    service_provider,
-    project_id=None,
-    project_name=None,
-    project_domain_id=None,
-    project_domain_name=None,
-):
+    local_auth: identity_base.BaseIdentityPlugin,
+    service_provider: str,
+    project_id: ty.Optional[str] = None,
+    project_name: ty.Optional[str] = None,
+    project_domain_id: ty.Optional[str] = None,
+    project_domain_name: ty.Optional[str] = None,
+) -> k2k.Keystone2Keystone:
     """Return Keystone 2 Keystone authentication for service provider.
 
     :param local_auth: authentication to use with the local Keystone

osc_lib/api/utils.py

@@ -13,13 +13,18 @@
 
 """API Utilities Library"""
 
+import typing as ty
+
+
+_T = ty.TypeVar('_T', bound=list[ty.Any])
+
 
 def simple_filter(
-    data=None,
-    attr=None,
-    value=None,
-    property_field=None,
-):
+    data: ty.Optional[_T] = None,
+    attr: ty.Optional[str] = None,
+    value: ty.Optional[str] = None,
+    property_field: ty.Optional[str] = None,
+) -> ty.Optional[_T]:
     """Filter a list of dicts
 
     :param list data:

osc_lib/cli/client_config.py

@@ -14,7 +14,9 @@
 """OpenStackConfig subclass for argument compatibility"""
 
 import logging
+import typing as ty
 
+from keystoneauth1.loading import identity as ksa_loading
 from openstack.config import exceptions as sdk_exceptions
 from openstack.config import loader as config
 from oslo_utils import strutils
@@ -23,10 +25,12 @@ from oslo_utils import strutils
 LOG = logging.getLogger(__name__)
 
 
-# Sublcass OpenStackConfig in order to munge config values
+# Subclass OpenStackConfig in order to munge config values
 # before auth plugins are loaded
-class OSC_Config(config.OpenStackConfig):
-    def _auth_select_default_plugin(self, config):
+class OSC_Config(config.OpenStackConfig):  # type: ignore
+    def _auth_select_default_plugin(
+        self, config: dict[str, ty.Any]
+    ) -> dict[str, ty.Any]:
         """Select a default plugin based on supplied arguments
 
         Migrated from auth.select_auth_plugin()
@@ -59,7 +63,9 @@ class OSC_Config(config.OpenStackConfig):
         LOG.debug("Auth plugin {} selected".format(config['auth_type']))
         return config
 
-    def _auth_v2_arguments(self, config):
+    def _auth_v2_arguments(
+        self, config: dict[str, ty.Any]
+    ) -> dict[str, ty.Any]:
         """Set up v2-required arguments from v3 info
 
         Migrated from auth.build_auth_params()
@@ -72,41 +78,49 @@ class OSC_Config(config.OpenStackConfig):
                 config['auth']['tenant_name'] = config['auth']['project_name']
         return config
 
-    def _auth_v2_ignore_v3(self, config):
+    def _auth_v2_ignore_v3(
+        self, config: dict[str, ty.Any]
+    ) -> dict[str, ty.Any]:
         """Remove v3 arguments if present for v2 plugin
 
         Migrated from clientmanager.setup_auth()
         """
-
         # NOTE(hieulq): If USER_DOMAIN_NAME, USER_DOMAIN_ID, PROJECT_DOMAIN_ID
         # or PROJECT_DOMAIN_NAME is present and API_VERSION is 2.0, then
         # ignore all domain related configs.
-        if str(config.get('identity_api_version', '')).startswith(
-            '2'
-        ) and config.get('auth_type').endswith('password'):
-            domain_props = [
-                'project_domain_id',
-                'project_domain_name',
-                'user_domain_id',
-                'user_domain_name',
-            ]
-            for prop in domain_props:
-                if config['auth'].pop(prop, None) is not None:
-                    if config.get('cloud'):
-                        LOG.warning(
-                            "Ignoring domain related config {} for {}"
-                            "because identity API version is 2.0".format(
-                                prop, config['cloud']
-                            )
-                        )
-                    else:
-                        LOG.warning(
-                            f"Ignoring domain related config {prop} because"
-                            " identity API version is 2.0"
+        if not str(config.get('identity_api_version', '')).startswith('2'):
+            return config
+
+        if not config.get('auth_type') or not config['auth_type'].endswith(
+            'password'
+        ):
+            return config
+
+        domain_props = [
+            'project_domain_id',
+            'project_domain_name',
+            'user_domain_id',
+            'user_domain_name',
+        ]
+        for prop in domain_props:
+            if config['auth'].pop(prop, None) is not None:
+                if config.get('cloud'):
+                    LOG.warning(
+                        "Ignoring domain related config {} for {}"
+                        "because identity API version is 2.0".format(
+                            prop, config['cloud']
                         )
+                    )
+                else:
+                    LOG.warning(
+                        f"Ignoring domain related config {prop} because"
+                        " identity API version is 2.0"
+                    )
         return config
 
-    def _auth_default_domain(self, config):
+    def _auth_default_domain(
+        self, config: dict[str, ty.Any]
+    ) -> dict[str, ty.Any]:
         """Set a default domain from available arguments
 
         Migrated from clientmanager.setup_auth()
@@ -147,7 +161,7 @@ class OSC_Config(config.OpenStackConfig):
                 config['auth']['user_domain_id'] = default_domain
         return config
 
-    def auth_config_hook(self, config):
+    def auth_config_hook(self, config: dict[str, ty.Any]) -> dict[str, ty.Any]:
         """Allow examination of config values before loading auth plugin
 
         OpenStackClient will override this to perform additional checks
@@ -165,7 +179,11 @@ class OSC_Config(config.OpenStackConfig):
             )
         return config
 
-    def _validate_auth(self, config, loader, fixed_argparse=None):
+    def _validate_auth(
+        self,
+        config: dict[str, ty.Any],
+        loader: ksa_loading.BaseIdentityLoader[ty.Any],
+    ) -> dict[str, ty.Any]:
         """Validate auth plugin arguments"""
         # May throw a keystoneauth1.exceptions.NoMatchingPlugin
 
@@ -229,7 +247,8 @@ class OSC_Config(config.OpenStackConfig):
 
         return config
 
-    def load_auth_plugin(self, config):
+    # TODO(stephenfin): Add type once we have typing for SDK
+    def load_auth_plugin(self, config: dict[str, ty.Any]) -> ty.Any:
         """Get auth plugin and validate args"""
 
         loader = self._get_auth_loader(config)

osc_lib/cli/format_columns.py

@@ -15,53 +15,55 @@
 
 """Formattable column for specify content type"""
 
+import typing as ty
+
 from cliff import columns
 
 from osc_lib import utils
 
 
-class DictColumn(columns.FormattableColumn):
+class DictColumn(columns.FormattableColumn[dict[str, ty.Any]]):
     """Format column for dict content"""
 
-    def human_readable(self):
+    def human_readable(self) -> str:
         return utils.format_dict(self._value)
 
-    def machine_readable(self):
+    def machine_readable(self) -> dict[str, ty.Any]:
         return dict(self._value or {})
 
 
-class DictListColumn(columns.FormattableColumn):
+class DictListColumn(columns.FormattableColumn[dict[str, list[ty.Any]]]):
     """Format column for dict, key is string, value is list"""
 
-    def human_readable(self):
-        return utils.format_dict_of_list(self._value)
+    def human_readable(self) -> str:
+        return utils.format_dict_of_list(self._value) or ''
 
-    def machine_readable(self):
+    def machine_readable(self) -> dict[str, list[ty.Any]]:
         return dict(self._value or {})
 
 
-class ListColumn(columns.FormattableColumn):
+class ListColumn(columns.FormattableColumn[list[ty.Any]]):
     """Format column for list content"""
 
-    def human_readable(self):
-        return utils.format_list(self._value)
+    def human_readable(self) -> str:
+        return utils.format_list(self._value) or ''
 
-    def machine_readable(self):
+    def machine_readable(self) -> list[ty.Any]:
         return [x for x in self._value or []]
 
 
-class ListDictColumn(columns.FormattableColumn):
+class ListDictColumn(columns.FormattableColumn[list[dict[str, ty.Any]]]):
     """Format column for list of dict content"""
 
-    def human_readable(self):
-        return utils.format_list_of_dicts(self._value)
+    def human_readable(self) -> str:
+        return utils.format_list_of_dicts(self._value) or ''
 
-    def machine_readable(self):
+    def machine_readable(self) -> list[dict[str, ty.Any]]:
         return [dict(x) for x in self._value or []]
 
 
-class SizeColumn(columns.FormattableColumn):
+class SizeColumn(columns.FormattableColumn[ty.Union[int, float]]):
     """Format column for file size content"""
 
-    def human_readable(self):
+    def human_readable(self) -> str:
         return utils.format_size(self._value)

osc_lib/cli/identity.py

@@ -11,13 +11,19 @@
 #   under the License.
 #
 
+import argparse
+import typing as ty
+
+from openstack import connection
 from openstack import exceptions
 from openstack.identity.v3 import project
 
 from osc_lib.i18n import _
 
 
-def add_project_owner_option_to_parser(parser):
+def add_project_owner_option_to_parser(
+    parser: argparse.ArgumentParser,
+) -> None:
     """Register project and project domain options.
 
     :param parser: argparse.Argument parser object.
@@ -38,7 +44,13 @@ def add_project_owner_option_to_parser(parser):
     )
 
 
-def find_project(sdk_connection, name_or_id, domain_name_or_id=None):
+# TODO(stephenfin): This really doesn't belong here. This should be part of
+# openstacksdk itself.
+def find_project(
+    sdk_connection: connection.Connection,
+    name_or_id: str,
+    domain_name_or_id: ty.Optional[str] = None,
+) -> project.Project:
     """Find a project by its name name or ID.
 
     If Forbidden to find the resource (a common case if the user does not have
@@ -53,7 +65,6 @@ def find_project(sdk_connection, name_or_id, domain_name_or_id=None):
         This can be used when there are multiple projects with a same name.
     :returns: the project object found
     :rtype: `openstack.identity.v3.project.Project`
-
     """
     try:
         if domain_name_or_id:

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.'
+        ),
+    )