osc-lib 3.2.0__tar.gz → 4.0.0__tar.gz

{osc-lib-3.2.0 → osc_lib-4.0.0}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ default_language_version:
   python: python3
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
       - id: mixed-line-ending
@@ -22,7 +22,7 @@ repos:
     hooks:
       - id: doc8
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.4
+    rev: v0.9.6
     hooks:
       - id: ruff
         args: ['--fix', '--unsafe-fixes']
@@ -34,3 +34,18 @@ repos:
         additional_dependencies:
           - flake8-import-order~=0.18.2
         exclude: '^(doc|releasenotes|tools)/.*$'
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - cliff
+          - keystoneauth1
+          - types-requests
+        # keep this in-sync with '[mypy] exclude' in 'setup.cfg'
+        exclude: |
+          (?x)(
+            doc/.*
+            | examples/.*
+            | releasenotes/.*
+          )

{osc-lib-3.2.0 → osc_lib-4.0.0}/ChangeLog

@@ -1,6 +1,35 @@
 CHANGES
 =======
 
+4.0.0
+-----
+
+* typing: Enable disallow\_subclassing\_any
+* tests: Resolve TODO
+* utils: Deprecate legacy client-specific helpers
+* utils: Remove support for legacy format functions
+* utils: Group similar utilities together
+* utils: Don't warn for partial formatter classes
+* typing: Add typing to osc\_lib.utils
+* typing: Add typing to osc\_lib.command
+* clientmanager: Deprecate ClientCache
+* typing: Add typing to osc\_lib.clientmanager
+* typing: Add typing to osc\_lib.shell
+* typing: Add typing to osc\_lib.logs, osc\_lib.i18n
+* typing: Add typing to osc\_lib.cli
+* api: Deprecate BaseAPI
+* typing: Add typing to osc\_lib.api
+* Remove unused docs Makefile
+* typing: Add typing to osc\_lib.exceptions
+* pre-commit: Enable mypy
+* typing: Fix initial typing issues
+* Update master for stable/2025.1
+* Add pagination helpers
+* pre-commit: Enable ruff S (bandit) checks
+* pre-commit: Bump versions
+* tests: Use consistent output widths
+* reno: Update master for unmaintained/2023.1
+
 3.2.0
 -----
 

osc_lib-4.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: osc-lib
+Version: 4.0.0
+Summary: OpenStackClient Library
+Home-page: https://docs.openstack.org/osc-lib/latest/
+Author: OpenStack
+Author-email: openstack-discuss@lists.openstack.org
+Project-URL: Bug Tracker, https://storyboard.openstack.org/#!/project/openstack/osc-lib
+Project-URL: Documentation, https://docs.openstack.org/osc-lib/latest/
+Project-URL: Source Code, https://opendev.org/openstack/osc-lib/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: OpenStack
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: cliff>=4.9.0
+Requires-Dist: keystoneauth1>=5.10.0
+Requires-Dist: openstacksdk>=0.15.0
+Requires-Dist: oslo.i18n>=3.15.3
+Requires-Dist: oslo.utils>=3.33.0
+Requires-Dist: pbr!=2.1.0,>=2.0.0
+Requires-Dist: requests>=2.14.2
+Requires-Dist: stevedore>=1.20.0
+
+=======
+osc-lib
+=======
+
+.. image:: https://img.shields.io/pypi/v/osc-lib.svg
+    :target: https://pypi.org/project/osc-lib/
+    :alt: Latest Version
+
+OpenStackClient (aka OSC) is a command-line client for OpenStack. osc-lib
+is a package of common support modules for writing OSC plugins.
+
+* `PyPi`_ - package installation
+* `Online Documentation`_
+* `Launchpad project`_ - part of OpenStackClient
+* `Bugs`_ - issue tracking
+* `Source`_
+* `Developer` - getting started as a developer
+* `Contributing` - contributing code
+* `Testing` - testing code
+* IRC: #openstack-sdks on OFTC (irc.oftc.net)
+* License: Apache 2.0
+
+.. _PyPi: https://pypi.org/project/osc-lib
+.. _Online Documentation: http://docs.openstack.org/osc-lib/latest/
+.. _Launchpad project: https://launchpad.net/python-openstackclient
+.. _Bugs: https://storyboard.openstack.org/#!/project_group/80
+.. _Source: https://opendev.org/openstack/osc-lib
+.. _Developer: http://docs.openstack.org/project-team-guide/project-setup/python.html
+.. _Contributing: http://docs.openstack.org/infra/manual/developers.html
+.. _Testing: http://docs.openstack.org/osc-lib/latest/contributor/#testing
+.. _Release Notes: https://docs.openstack.org/releasenotes/osc-lib
+
+Getting Started
+===============
+
+osc-lib can be installed from PyPI using pip::
+
+    pip install osc-lib
+
+Transition From OpenStackclient
+===============================
+
+This library was extracted from the main OSC repo after the OSC 2.4.0 release.
+The following are the changes to imports that will cover the majority of
+transition to using osc-lib:
+
+* openstackclient.api.api -> osc_lib.api.api
+* openstackclient.api.auth -> osc_lib.api.auth
+* openstackclient.api.utils -> osc_lib.api.utils
+* openstackclient.common.command -> osc_lib.command.command
+* openstackclient.common.commandmanager -> osc_lib.command.commandmanager
+* openstackclient.common.exceptions -> osc_lib.exceptions
+* openstackclient.common.logs -> osc_lib.logs
+* openstackclient.common.parseractions -> osc_lib.cli.parseractions
+* openstackclient.common.session -> osc_lib.session
+* openstackclient.common.utils -> osc_lib.utils
+* openstackclient.i18n -> osc_lib.i18n
+* openstackclient.shell -> osc_lib.shell
+
+Also, some of the test fixtures and modules may be used:
+
+* openstackclient.tests.fakes -> osc_lib.tests.fakes
+* openstackclient.tests.utils -> osc_lib.tests.utils
+

{osc-lib-3.2.0 → osc_lib-4.0.0}/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-3.2.0 → osc_lib-4.0.0}/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-3.2.0 → osc_lib-4.0.0}/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-3.2.0 → osc_lib-4.0.0}/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)