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

osc_lib/utils/__init__.py

@@ -15,25 +15,34 @@
 
 """Common client utilities"""
 
+import argparse
+import collections.abc
 import copy
 import functools
 import getpass
 import logging
 import os
 import time
+import typing as ty
 import warnings
 
 from cliff import columns as cliff_columns
+from openstack import resource
 from oslo_utils import importutils
 
 from osc_lib import exceptions
 from osc_lib.i18n import _
 
-
 LOG = logging.getLogger(__name__)
 
+_T = ty.TypeVar('_T')
+
 
-def backward_compat_col_lister(column_headers, columns, column_map):
+def backward_compat_col_lister(
+    column_headers: list[str],
+    columns: list[str],
+    column_map: dict[str, str],
+) -> list[str]:
     """Convert the column headers to keep column backward compatibility.
 
     Replace the new column name of column headers by old name, so that
@@ -65,7 +74,11 @@ def backward_compat_col_lister(column_headers, columns, column_map):
     return column_headers
 
 
-def backward_compat_col_showone(show_object, columns, column_map):
+def backward_compat_col_showone(
+    show_object: collections.abc.MutableMapping[str, _T],
+    columns: list[str],
+    column_map: dict[str, str],
+) -> collections.abc.MutableMapping[str, _T]:
     """Convert the output object to keep column backward compatibility.
 
     Replace the new column name of output object by old name, so that
@@ -95,7 +108,7 @@ def backward_compat_col_showone(show_object, columns, column_map):
     return show_object
 
 
-def build_kwargs_dict(arg_name, value):
+def build_kwargs_dict(arg_name: str, value: _T) -> dict[str, _T]:
     """Return a dictionary containing `arg_name` if `value` is set."""
     kwargs = {}
     if value:
@@ -103,7 +116,11 @@ def build_kwargs_dict(arg_name, value):
     return kwargs
 
 
-def calculate_header_and_attrs(column_headers, attrs, parsed_args):
+def calculate_header_and_attrs(
+    column_headers: collections.abc.Sequence[str],
+    attrs: collections.abc.Sequence[str],
+    parsed_args: argparse.Namespace,
+) -> tuple[collections.abc.Sequence[str], collections.abc.Sequence[str]]:
     """Calculate headers and attribute names based on parsed_args.column.
 
     When --column (-c) option is specified, this function calculates
@@ -138,7 +155,7 @@ def calculate_header_and_attrs(column_headers, attrs, parsed_args):
         return column_headers, attrs
 
 
-def env(*vars, **kwargs):
+def env(*vars: str, **kwargs: ty.Any) -> ty.Optional[str]:
     """Search for the first defined of possibly many env vars
 
     Returns the first environment variable defined in vars, or
@@ -148,10 +165,18 @@ def env(*vars, **kwargs):
         value = os.environ.get(v, None)
         if value:
             return value
-    return kwargs.get('default', '')
 
+    if 'default' in kwargs and kwargs['default'] is not None:
+        return str(kwargs['default'])
+
+    return None
 
-def find_min_match(items, sort_attr, **kwargs):
+
+def find_min_match(
+    items: collections.abc.Sequence[_T],
+    sort_attr: str,
+    **kwargs: ty.Any,
+) -> collections.abc.Sequence[_T]:
     """Find all resources meeting the given minimum constraints
 
     :param items: A List of objects to consider
@@ -160,7 +185,7 @@ def find_min_match(items, sort_attr, **kwargs):
     :rtype: A list of resources osrted by sort_attr that meet the minimums
     """
 
-    def minimum_pieces_of_flair(item):
+    def minimum_pieces_of_flair(item: _T) -> bool:
         """Find lowest value greater than the minumum"""
 
         result = True
@@ -169,10 +194,17 @@ def find_min_match(items, sort_attr, **kwargs):
             result = result and kwargs[k] <= get_field(item, k)
         return result
 
-    return sort_items(filter(minimum_pieces_of_flair, items), sort_attr)
+    return sort_items(list(filter(minimum_pieces_of_flair, items)), sort_attr)
 
 
-def find_resource(manager, name_or_id, **kwargs):
+# TODO(stephenfin): We should return a proper type, but how to do so without
+# using generics? We should also deprecate this but there are a lot of users
+# still.
+def find_resource(
+    manager: ty.Any,
+    name_or_id: str,
+    **kwargs: ty.Any,
+) -> ty.Any:
     """Helper for the _find_* methods.
 
     :param manager: A client manager class
@@ -200,7 +232,7 @@ def find_resource(manager, name_or_id, **kwargs):
     # enough information, and domain information is necessary.
     try:
         return manager.get(name_or_id)
-    except Exception:
+    except Exception:  # noqa: S110
         pass
 
     if kwargs:
@@ -208,7 +240,7 @@ def find_resource(manager, name_or_id, **kwargs):
         # for example: /projects/demo&domain_id=30524568d64447fbb3fa8b7891c10dd
         try:
             return manager.get(name_or_id, **kwargs)
-        except Exception:
+        except Exception:  # noqa: S110
             pass
 
     # Case 3: Try to get entity as integer id. Keystone does not have integer
@@ -242,7 +274,7 @@ def find_resource(manager, name_or_id, **kwargs):
             kwargs[manager.resource_class.NAME_ATTR] = name_or_id
         else:
             kwargs['name'] = name_or_id
-    except Exception:
+    except Exception:  # noqa: S110
         pass
 
     # finally try to find entity by name
@@ -279,26 +311,25 @@ def find_resource(manager, name_or_id, **kwargs):
     # Case 5: For client with no find function, list all resources and hope
     # to find a matching name or ID.
     count = 0
-    for resource in manager.list():
-        if (
-            resource.get('id') == name_or_id
-            or resource.get('name') == name_or_id
-        ):
+    for res in manager.list():
+        if res.get('id') == name_or_id or res.get('name') == name_or_id:
             count += 1
-            _resource = resource
+            _res = res
     if count == 0:
         # we found no match, report back this error:
         msg = _("Could not find resource %s")
         raise exceptions.CommandError(msg % name_or_id)
     elif count == 1:
-        return _resource
+        return _res
     else:
         # we found multiple matches, report back this error
         msg = _("More than one resource exists with the name or ID '%s'.")
         raise exceptions.CommandError(msg % name_or_id)
 
 
-def format_dict(data, prefix=None):
+def format_dict(
+    data: dict[str, ty.Any], prefix: ty.Optional[str] = None
+) -> str:
     """Return a formatted string of key value pairs
 
     :param data: a dict
@@ -326,11 +357,13 @@ def format_dict(data, prefix=None):
     return output[:-2]
 
 
-def format_dict_of_list(data, separator='; '):
+def format_dict_of_list(
+    data: ty.Optional[dict[str, list[ty.Any]]], separator: str = '; '
+) -> ty.Optional[str]:
     """Return a formatted string of key value pair
 
     :param data: a dict, key is string, value is a list of string, for example:
-                 {u'public': [u'2001:db8::8', u'172.24.4.6']}
+                 {'public': ['2001:db8::8', '172.24.4.6']}
     :param separator: the separator to use between key/value pair
                       (default: '; ')
     :return: a string formatted to {'key1'=['value1', 'value2']} with separated
@@ -351,7 +384,9 @@ def format_dict_of_list(data, separator='; '):
     return separator.join(output)
 
 
-def format_list(data, separator=', '):
+def format_list(
+    data: ty.Optional[list[ty.Any]], separator: str = ', '
+) -> ty.Optional[str]:
     """Return a formatted strings
 
     :param data: a list of strings
@@ -364,7 +399,9 @@ def format_list(data, separator=', '):
     return separator.join(sorted(data))
 
 
-def format_list_of_dicts(data):
+def format_list_of_dicts(
+    data: ty.Optional[list[dict[str, ty.Any]]],
+) -> ty.Optional[str]:
     """Return a formatted string of key value pairs for each dict
 
     :param data: a list of dicts
@@ -376,10 +413,10 @@ def format_list_of_dicts(data):
     return '\n'.join(format_dict(i) for i in data)
 
 
-def format_size(size):
+def format_size(size: ty.Union[int, float, None]) -> str:
     """Display size of a resource in a human readable format
 
-    :param string size:
+    :param size:
         The size of the resource in bytes.
 
     :returns:
@@ -394,19 +431,22 @@ def format_size(size):
     base = 1000.0
     index = 0
 
-    if size is None:
-        size = 0
-    while size >= base:
+    size_ = float(size) if size is not None else 0.0
+    while size_ >= base:
         index = index + 1
-        size = size / base
+        size_ = size_ / base
 
-    padded = f'{size:.1f}'
+    padded = f'{size_:.1f}'
     stripped = padded.rstrip('0').rstrip('.')
 
     return f'{stripped}{suffix[index]}'
 
 
-def get_client_class(api_name, version, version_map):
+def get_client_class(
+    api_name: str,
+    version: ty.Union[str, int, float],
+    version_map: dict[str, type[_T]],
+) -> ty.Any:
     """Returns the client class for the requested API version
 
     :param api_name: the name of the API, e.g. 'compute', 'image', etc
@@ -414,6 +454,12 @@ def get_client_class(api_name, version, version_map):
     :param version_map: a dict of client classes keyed by version
     :rtype: a client class for the requested API version
     """
+    warnings.warn(
+        "This function is deprecated and is not necessary with openstacksdk."
+        "Consider vendoring this if necessary.",
+        category=DeprecationWarning,
+    )
+
     try:
         client_path = version_map[str(version)]
     except (KeyError, ValueError):
@@ -436,7 +482,14 @@ def get_client_class(api_name, version, version_map):
     return importutils.import_class(client_path)
 
 
-def get_dict_properties(item, fields, mixed_case_fields=None, formatters=None):
+def get_dict_properties(
+    item: dict[str, _T],
+    fields: collections.abc.Sequence[str],
+    mixed_case_fields: ty.Optional[collections.abc.Sequence[str]] = None,
+    formatters: ty.Optional[
+        dict[str, type[cliff_columns.FormattableColumn[ty.Any]]]
+    ] = None,
+) -> tuple[ty.Any, ...]:
     """Return a tuple containing the item properties.
 
     :param item: a single dict resource
@@ -457,7 +510,7 @@ def get_dict_properties(item, fields, mixed_case_fields=None, formatters=None):
             field_name = field.replace(' ', '_')
         else:
             field_name = field.lower().replace(' ', '_')
-        data = item[field_name] if field_name in item else ''
+        data: ty.Any = item[field_name] if field_name in item else ''
         if field in formatters:
             formatter = formatters[field]
             # columns must be either a subclass of FormattableColumn
@@ -472,16 +525,7 @@ def get_dict_properties(item, fields, mixed_case_fields=None, formatters=None):
                 and issubclass(formatter.func, cliff_columns.FormattableColumn)
             ):
                 data = formatter(data)
-            # otherwise it's probably a legacy-style function
-            elif callable(formatter):
-                warnings.warn(
-                    'The usage of formatter functions is now discouraged. '
-                    'Consider using cliff.columns.FormattableColumn instead. '
-                    'See reviews linked with bug 1687955 for more detail.',
-                    category=DeprecationWarning,
-                )
-                if data is not None:
-                    data = formatter(data)
+            # otherwise it's invalid
             else:
                 msg = "Invalid formatter provided."
                 raise exceptions.CommandError(msg)
@@ -490,31 +534,14 @@ def get_dict_properties(item, fields, mixed_case_fields=None, formatters=None):
     return tuple(row)
 
 
-def get_effective_log_level():
-    """Returns the lowest logging level considered by logging handlers
-
-    Retrieve and return the smallest log level set among the root
-    logger's handlers (in case of multiple handlers).
-    """
-    root_log = logging.getLogger()
-    min_log_lvl = logging.CRITICAL
-    for handler in root_log.handlers:
-        min_log_lvl = min(min_log_lvl, handler.level)
-    return min_log_lvl
-
-
-def get_field(item, field):
-    try:
-        if isinstance(item, dict):
-            return item[field]
-        else:
-            return getattr(item, field)
-    except Exception:
-        msg = _("Resource doesn't have field %s")
-        raise exceptions.CommandError(msg % field)
-
-
-def get_item_properties(item, fields, mixed_case_fields=None, formatters=None):
+def get_item_properties(
+    item: dict[str, _T],
+    fields: collections.abc.Sequence[str],
+    mixed_case_fields: ty.Optional[collections.abc.Sequence[str]] = None,
+    formatters: ty.Optional[
+        dict[str, type[cliff_columns.FormattableColumn[ty.Any]]]
+    ] = None,
+) -> tuple[ty.Any, ...]:
     """Return a tuple containing the item properties.
 
     :param item: a single item resource (e.g. Server, Project, etc)
@@ -538,19 +565,19 @@ def get_item_properties(item, fields, mixed_case_fields=None, formatters=None):
         data = getattr(item, field_name, '')
         if field in formatters:
             formatter = formatters[field]
+            # columns must be either a subclass of FormattableColumn
             if isinstance(formatter, type) and issubclass(
                 formatter, cliff_columns.FormattableColumn
             ):
                 data = formatter(data)
-            elif callable(formatter):
-                warnings.warn(
-                    'The usage of formatter functions is now discouraged. '
-                    'Consider using cliff.columns.FormattableColumn instead. '
-                    'See reviews linked with bug 1687955 for more detail.',
-                    category=DeprecationWarning,
-                )
-                if data is not None:
-                    data = formatter(data)
+            # or a partial wrapping one (to allow us to pass extra parameters)
+            elif (
+                isinstance(formatter, functools.partial)
+                and isinstance(formatter.func, type)
+                and issubclass(formatter.func, cliff_columns.FormattableColumn)
+            ):
+                data = formatter(data)
+            # otherwise it's invalid
             else:
                 msg = "Invalid formatter provided."
                 raise exceptions.CommandError(msg)
@@ -559,7 +586,35 @@ def get_item_properties(item, fields, mixed_case_fields=None, formatters=None):
     return tuple(row)
 
 
-def get_password(stdin, prompt=None, confirm=True):
+def get_effective_log_level() -> int:
+    """Returns the lowest logging level considered by logging handlers
+
+    Retrieve and return the smallest log level set among the root
+    logger's handlers (in case of multiple handlers).
+    """
+    root_log = logging.getLogger()
+    min_log_lvl = logging.CRITICAL
+    for handler in root_log.handlers:
+        min_log_lvl = min(min_log_lvl, handler.level)
+    return min_log_lvl
+
+
+def get_field(item: _T, field: str) -> ty.Any:
+    try:
+        if isinstance(item, dict):
+            return item[field]
+        else:
+            return getattr(item, field)
+    except Exception:
+        msg = _("Resource doesn't have field %s")
+        raise exceptions.CommandError(msg % field)
+
+
+def get_password(
+    stdin: ty.TextIO,
+    prompt: ty.Optional[str] = None,
+    confirm: bool = True,
+) -> str:
     message = prompt or "User Password:"
     if hasattr(stdin, 'isatty') and stdin.isatty():
         try:
@@ -579,19 +634,18 @@ def get_password(stdin, prompt=None, confirm=True):
     raise exceptions.CommandError(msg)
 
 
-def is_ascii(string):
+def is_ascii(string: ty.Union[str, bytes]) -> bool:
     try:
-        (
+        if isinstance(string, bytes):
             string.decode('ascii')
-            if isinstance(string, bytes)
-            else string.encode('ascii')
-        )
+        else:
+            string.encode('ascii')
         return True
     except (UnicodeEncodeError, UnicodeDecodeError):
         return False
 
 
-def read_blob_file_contents(blob_file):
+def read_blob_file_contents(blob_file: str) -> str:
     try:
         with open(blob_file) as file:
             blob = file.read().strip()
@@ -601,7 +655,11 @@ def read_blob_file_contents(blob_file):
         raise exceptions.CommandError(msg % blob_file)
 
 
-def sort_items(items, sort_str, sort_type=None):
+def sort_items(
+    items: collections.abc.Sequence[_T],
+    sort_str: str,
+    sort_type: ty.Optional[type[ty.Any]] = None,
+) -> collections.abc.Sequence[_T]:
     """Sort items based on sort keys and sort directions given by sort_str.
 
     :param items: a list or generator object of items
@@ -640,7 +698,7 @@ def sort_items(items, sort_str, sort_type=None):
             if direction == 'desc':
                 reverse = True
 
-        def f(x):
+        def f(x: ty.Any) -> ty.Any:
             # Attempts to convert items to same 'sort_type' if provided.
             # This is due to Python 3 throwing TypeError if you attempt to
             # compare different types
@@ -659,15 +717,15 @@ def sort_items(items, sort_str, sort_type=None):
 
 
 def wait_for_delete(
-    manager,
-    res_id,
-    status_field='status',
-    error_status=['error'],
-    exception_name=['NotFound'],
-    sleep_time=5,
-    timeout=300,
-    callback=None,
-):
+    manager: ty.Any,
+    res_id: str,
+    status_field: str = 'status',
+    error_status: collections.abc.Sequence[str] = ['error'],
+    exception_name: collections.abc.Sequence[str] = ['NotFound'],
+    sleep_time: int = 5,
+    timeout: int = 300,
+    callback: ty.Optional[collections.abc.Callable[[int], None]] = None,
+) -> bool:
     """Wait for resource deletion
 
     :param manager: the manager from which we can get the resource
@@ -685,6 +743,12 @@ def wait_for_delete(
     :rtype: True on success, False if the resource has gone to error state or
         the timeout has been reached
     """
+    warnings.warn(
+        "This function is deprecated as it does not support openstacksdk "
+        "clients. Consider vendoring this if necessary.",
+        category=DeprecationWarning,
+    )
+
     total_time = 0
     while total_time < timeout:
         try:
@@ -712,14 +776,14 @@ def wait_for_delete(
 
 
 def wait_for_status(
-    status_f,
-    res_id,
-    status_field='status',
-    success_status=['active'],
-    error_status=['error'],
-    sleep_time=5,
-    callback=None,
-):
+    status_f: collections.abc.Callable[[str], object],
+    res_id: str,
+    status_field: str = 'status',
+    success_status: collections.abc.Sequence[str] = ['active'],
+    error_status: collections.abc.Sequence[str] = ['error'],
+    sleep_time: int = 5,
+    callback: ty.Optional[collections.abc.Callable[[int], None]] = None,
+) -> bool:
     """Wait for status change on a resource during a long-running operation
 
     :param status_f: a status function that takes a single id argument
@@ -731,6 +795,12 @@ def wait_for_status(
     :param callback: called per sleep cycle, useful to display progress
     :rtype: True on success
     """
+    warnings.warn(
+        "This function is deprecated as it does not support openstacksdk "
+        "clients. Consider vendoring this if necessary.",
+        category=DeprecationWarning,
+    )
+
     while True:
         res = status_f(res_id)
         status = getattr(res, status_field, '').lower()
@@ -748,8 +818,10 @@ def wait_for_status(
 
 
 def get_osc_show_columns_for_sdk_resource(
-    sdk_resource, osc_column_map, invisible_columns=None
-):
+    sdk_resource: resource.Resource,
+    osc_column_map: dict[str, str],
+    invisible_columns: ty.Optional[collections.abc.Sequence[str]] = None,
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
     """Get and filter the display and attribute columns for an SDK resource.
 
     Common utility function for preparing the output of an OSC show command.

osc_lib/utils/columns.py

@@ -11,13 +11,16 @@
 #   under the License.
 
 import operator
+import typing as ty
 
 LIST_BOTH = 'both'
 LIST_SHORT_ONLY = 'short_only'
 LIST_LONG_ONLY = 'long_only'
 
 
-def get_column_definitions(attr_map, long_listing):
+def get_column_definitions(
+    attr_map: list[tuple[str, str, str]], long_listing: bool
+) -> tuple[list[str], list[str]]:
     """Return table headers and column names for a listing table.
 
     An attribute map (attr_map) is a list of table entry definitions
@@ -73,7 +76,10 @@ def get_column_definitions(attr_map, long_listing):
     return headers, columns
 
 
-def get_columns(item, attr_map=None):
+def get_columns(
+    item: dict[str, ty.Any],
+    attr_map: ty.Optional[list[tuple[str, str, str]]] = None,
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
     """Return pair of resource attributes and corresponding display names.
 
     :param item: a dictionary which represents a resource.
@@ -82,7 +88,12 @@ def get_columns(item, attr_map=None):
 
         .. code-block:: python
 
-           {'id': 'myid', 'name': 'myname', 'foo': 'bar', 'tenant_id': 'mytenan'}
+           {
+               'id': 'myid',
+               'name': 'myname',
+               'foo': 'bar',
+               'tenant_id': 'mytenan',
+           }
 
     :param attr_map: a list of mapping from attribute to display name.
         The same format is used as for get_column_definitions attr_map.
@@ -106,7 +117,7 @@ def get_columns(item, attr_map=None):
         in the alphabetical order.
         Attributes not found in a given attr_map are kept as-is.
     """
-    attr_map = attr_map or tuple([])
+    attr_map = attr_map or []
     _attr_map_dict = dict((col, hdr) for col, hdr, listing_mode in attr_map)
 
     columns = [