regscale-cli 6.16.0.0__py3-none-any.whl

regscale/utils/__init__.py

@@ -0,0 +1,7 @@
+from .dict_utils import *
+from .click_utils import *
+from .files import *
+from .graphql_client import *
+from .string import *
+from .numbers import *
+from .lists import *

regscale/utils/b64conversion.py

@@ -0,0 +1,14 @@
+from base64 import b64decode, b64encode
+from io import BytesIO
+
+
+def encode_file_to_base64(file_path):
+    with open(file_path, "rb") as file:
+        file_bytes = file.read()
+        encoded_string = b64encode(file_bytes)
+        return encoded_string.decode("utf-8")
+
+
+def decode_base64_to_bytesio(encoded_string):
+    decoded_bytes = b64decode(encoded_string)
+    return BytesIO(decoded_bytes)

regscale/utils/click_utils.py

@@ -0,0 +1,118 @@
+"""Provide utilities for interacting with click Objects."""
+
+from typing import Any, Dict, Optional, Union
+
+import click
+
+
+def process_click_group(
+    group: Union[click.Group, click.Command],
+    prefix: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Process a click group into a dictionary
+
+    :param Union[click.Group, click.Command] group: a click.Group or click.Command to extract info from
+    :param Optional[str] prefix: an optional prefix to name the application, defaults to `group.name`
+    :return: a dictionary of the click group
+    :rtype: Dict[str, Any]
+    """
+    prefix = f"{group.name}" if prefix is None else f"{prefix}__{group.name}"
+    cmd_dict = {
+        "group": group,
+        "group_name": prefix,
+    }
+    for cmd_name, cmd in group.commands.items():
+        new_prefix = f"{prefix}__{cmd_name}"
+        if isinstance(cmd, click.Group):
+            cmd_dict[cmd_name] = process_click_group(cmd, new_prefix)
+        elif isinstance(cmd, click.Command):
+            cmd_dict[cmd_name] = process_command(cmd, new_prefix)
+    return cmd_dict
+
+
+def process_command(
+    cmd: click.Command,
+    cmd_name: str,
+) -> Dict[str, Any]:
+    """
+    Process a click command into a dictionary
+
+    :param click.Command cmd: a click.Command object
+    :param str cmd_name: the name of the command
+    :return: a dictionary of the click command
+    :rtype: Dict[str, Any]
+    """
+    return {
+        "cmd": cmd,
+        "name": cmd_name,
+        "params": {param.name: process_option(param) for param in cmd.params if isinstance(param, click.Option)},
+        "callback": cmd.callback,
+    }
+
+
+def process_option(
+    option: click.Option,
+) -> Dict[str, Any]:
+    """
+    Process a click Option
+
+    :param click.Option option: a click Option object
+    :return: a dictionary of the click option
+    :rtype: Dict[str, Any]
+    """
+    return {
+        "option": option,
+        "name": option.name,
+        "default": option.default,
+        "type": str(option.type),
+        "prompt": option.prompt,
+        "confirmation_prompt": option.confirmation_prompt,
+        "is_flag": option.is_flag,
+        "is_bool_flag": option.is_bool_flag,
+        "count": option.count,
+        "allow_from_autoenv": option.allow_from_autoenv,
+        "expose_value": option.expose_value,
+        "is_eager": option.is_eager,
+        "callback": option.callback,
+    }
+
+
+def find_file_path_parameters(group: Union[click.Group, click.Command], prefix: str = None) -> dict:
+    """
+    Find all file path parameters in a click group
+
+    :param Union[click.Group, click.Command] group: a click.Group or click.Command to extract info from
+    :param str prefix: an optional prefix to name the application, defaults to `group.name`
+    :return: a dictionary of file path parameters
+    :rtype: dict
+    """
+    file_path_parameters = {}
+
+    def add_to_dict(_key: str, _param: Any) -> None:
+        """
+        Helper function to add to the dictionary
+
+        :param str _key: the key to add to the dictionary
+        :param Any _param: the parameter to add to the dictionary
+        :rtype: None
+        """
+        if _key not in file_path_parameters:
+            file_path_parameters[_key] = []
+        file_path_parameters[_key].append(_param)
+
+    for cmd_name, cmd in group.commands.items():
+        current_suffix = cmd_name if not prefix else f"{prefix}__{cmd_name}"
+
+        if isinstance(cmd, click.Group):
+            file_path_parameters[cmd_name] = find_file_path_parameters(cmd, prefix)
+            inner_parameters = find_file_path_parameters(cmd, current_suffix)
+            for key, values in inner_parameters.items():
+                add_to_dict(key, values)
+        else:
+            for param in cmd.params:
+                if isinstance(param.type, (click.Path, click.File)):
+                    add_to_dict(current_suffix, param)
+                elif "file" in param.name or "path" in param.name:
+                    add_to_dict(current_suffix, param)
+    return file_path_parameters

regscale/utils/decorators.py

@@ -0,0 +1,48 @@
+"""
+App decorators
+"""
+
+import warnings
+import functools
+
+
+def deprecated(reason="This method is deprecated and may be removed in a future version."):
+    """
+    Decorator to mark functions as deprecated.
+
+    :param reason: The reason for deprecation.
+    """
+
+    def decorator(func):
+        """
+        Decorator to mark functions as deprecated.
+        :param func:
+        :return:
+        """
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            """
+            Wrapper function to mark functions as deprecated.
+            :param args:
+            :param kwargs:
+            :return:
+            """
+            warnings.warn(f"{func.__name__} is deprecated: {reason}", category=DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class classproperty:  # pylint: disable=invalid-name # noqa: N801
+    """
+    A class property decorator.
+    """
+
+    def __init__(self, func):
+        self.func = func
+
+    def __get__(self, instance, owner):
+        return self.func(owner)

regscale/utils/dict_utils.py

@@ -0,0 +1,59 @@
+"""
+This module contains utility functions for working with dictionaries.
+"""
+
+from typing import Dict, List, Tuple, Any, Optional
+
+
+def get_value(data: dict, key: str) -> Any:
+    """
+    Get a value from a dictionary even if nested dict using dot notation.
+    If the value is within a list, return a list of values. (e.g. "key1.key2" -> {key1: {key2: value2}}) -> value2
+    also fetches values from nested lists. (e.g. "key1.key2" -> {key1: [{key2: value2}, {key2: value3}]} -> [value2, value3])
+    :param dict data: The dictionary to get the value from.
+    :param str key: The key to get the value for.
+    :return: The value from the dictionary or None if the key is not found.
+    :rtype: Any
+    """
+    keys = key.split(".")
+    value = data
+    for k in keys:
+        if isinstance(value, list):
+            value = [item.get(k, None) if isinstance(item, dict) else None for item in value]
+        elif isinstance(value, dict):
+            value = value.get(k, None)
+        else:
+            return None
+        if value and any(isinstance(i, list) for i in value):
+            value = [item for sublist in value for item in sublist if item is not None]
+    return value
+
+
+def flatten_dict(
+    d: Dict[str, Any], prefix: str = "", result: Optional[List[Tuple[str, Any]]] = None
+) -> List[Tuple[str, Any]]:
+    """
+    Recursively flattens a nested dictionary or list of dictionaries into a list of tuples,
+    preserving the hierarchy in the keys.
+
+    :param Dict[str, Any] d: The dictionary or list of dictionaries to flatten.
+    :param str prefix: The current prefix representing the hierarchy of keys, defaults to an empty string.
+    :param Optional[List[Tuple[str, Any]]] result: The accumulated list of tuples, This is used internally and should
+        not be set by the caller. defaults to None.
+    :return: A list of tuples where each tuple is a key-value pair, with the key representing the hierarchical path.
+    :rtype: List[Tuple[str, Any]]
+    """
+    if result is None:
+        result = []
+    if isinstance(d, dict):
+        for key, value in d.items():
+            new_key = f"{prefix}{key}" if prefix else key
+            if isinstance(value, (dict, list)):
+                flatten_dict(value, f"{new_key}.", result)
+            else:
+                result.append((new_key, value))
+    elif isinstance(d, list):
+        for index, item in enumerate(d):
+            flatten_dict(item, f"{prefix}{index}.", result)
+
+    return result

regscale/utils/files.py

@@ -0,0 +1,79 @@
+"""Provide functions for dealing with files."""
+
+import os
+from pathlib import Path
+from tempfile import gettempdir
+from types import TracebackType
+from typing import Union, TextIO, Optional, Type
+
+
+def print_file_contents(file_path: Union[str, Path]) -> None:
+    """
+    Print a file's contents to the console.
+
+    :param Union[str, Path] file_path: a string or Path object
+    :rtype: None
+    """
+    if isinstance(file_path, str):
+        file_path = Path(file_path)
+    if file_path.is_file():
+        print(f'File "{file_path}" found!')
+        print(file_path.read_text(encoding="utf-8"))
+
+
+def print_current_directory(print_yaml: bool = False) -> None:
+    """
+    Print the contents of the current directory and its path
+
+    :param bool print_yaml: should the contents of the yaml file be printed, defaults to False
+    :rtype: None
+    """
+    current_dir = os.getcwd()
+    print(f"Current Working Directory: {current_dir}")
+    if print_yaml:
+        init_file = os.path.join(current_dir, "init.yaml")
+        print_file_contents(init_file)
+
+
+class CustomTempFile:
+    """
+    A context manager for creating temporary files
+
+    :param Union[str, Path] filename: the name of the file
+    :param bool delete: should the file be deleted when the context is exited? (default: True)
+    """
+
+    def __init__(self, filename: Union[str, Path], delete: bool = True):
+        self.temp_dir = gettempdir()
+        self.temp_filename = os.path.join(self.temp_dir, filename)
+        self.delete = delete
+        self.temp_file = None
+
+    def __enter__(self) -> TextIO:
+        """
+        Open the file with read/write permissions
+
+        :return: the file object
+        :rtype: TextIO
+        """
+        self.temp_file = open(self.temp_filename, "w+")
+        return self.temp_file
+
+    def __exit__(
+        self, exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]
+    ) -> None:
+        """
+        Close the file
+
+        :param Optional[Type[BaseException]] exc_type: The exception type
+        :param Optional[BaseException] exc_val: The exception value
+        :param Optional[TracebackType] exc_tb: The traceback
+        :rtype: None
+        """
+        # Close the file
+        if self.temp_file:
+            self.temp_file.close()
+
+        # Optionally, delete the file
+        if self.delete:
+            os.remove(self.temp_filename)

regscale/utils/fxns.py

@@ -0,0 +1,30 @@
+"""Provide utilities for dealing with functions."""
+
+import inspect
+from typing import Any, List
+
+
+def get_callback_param(command: Any) -> List[str]:
+    """
+    Return a list of parameter names in the callback function of a command
+
+    :param Any command: a function to get the parameters for
+    :return: a list of parameter names
+    :rtype: List[str]
+    """
+    callback = command.callback
+    sig = inspect.signature(callback)
+    return list(sig.parameters.keys())
+
+
+def get_callback_defaults(command: Any) -> dict:
+    """
+    Return a dictionary of callback defaults.
+
+    :param Any command: a function to get the defaults for
+    :return: a dictionary of parameter names and their defaults
+    :rtype: dict
+    """
+    callback = command.callback
+    sig = inspect.signature(callback)
+    return {name: param.default if param.default != param.empty else None for name, param in sig.parameters.items()}

regscale/utils/graphql_client.py

@@ -0,0 +1,113 @@
+"""
+A module for making paginated GraphQL queries.
+"""
+
+import logging
+from typing import List, Dict, Optional, Any
+
+from regscale.core.app.utils.app_utils import create_progress_object
+
+logger = logging.getLogger(__name__)
+
+
+class PaginatedGraphQLClient:
+    """
+    A class for making paginated GraphQL queries.
+
+    :param str endpoint: The GraphQL endpoint.
+    :param str query: The GraphQL query.
+    :param Optional[Dict[str, str]] headers: Optional headers to include in the request.
+    :param str logging_level: The logging level for the client (default: 'CRITICAL').
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        query: str,
+        headers: Optional[Dict[str, str]] = None,
+        logging_level: str = logging.CRITICAL,
+    ) -> None:
+        from gql import gql, Client  # Optimize import performance
+        from gql.transport.requests import RequestsHTTPTransport
+        from gql.transport.requests import log as requests_logger
+
+        self.log_level = logging_level
+        self.endpoint = endpoint
+        self.query = gql(query)
+        self.headers = headers or {}  # Ensure headers are a dictionary
+        self.transport = RequestsHTTPTransport(url=endpoint, headers=self.headers)
+        self.client = Client(transport=self.transport)
+        self.job_progress = create_progress_object()
+        requests_logger.setLevel(level=self.log_level)
+
+    def fetch_all(
+        self,
+        topic_key: str,
+        variables: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Fetches all results from the paginated query.
+
+        :param str topic_key: The key to the topic in the response.
+        :param Optional[Dict[str, Any]] variables: Optional query variables.
+        :return: A list of results.
+        :rtype: List[Dict[str, Any]]
+        """
+        self.job_progress.add_task("[#f68d1f]Fetching data...", total=None)
+        results = []
+        next_cursor = None
+        has_next_page = True
+        page_info_default = {"hasNextPage": False, "endCursor": None}
+        while has_next_page:
+            data = self.fetch_page(variables=variables, after=next_cursor)
+            if data:
+                results.extend(data.get(topic_key, {}).get("nodes", []))
+                page_info = data.get(topic_key, {}).get("pageInfo", page_info_default)
+                logger.debug(f"pageInfo: {page_info}")
+                has_next_page = page_info.get("hasNextPage", False)
+                next_cursor = page_info.get("endCursor", None)
+                if not has_next_page:
+                    break
+            else:
+                break
+        return results
+
+    def fetch_page(self, variables: Optional[Dict[str, Any]] = None, after: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Fetches a single page of results.
+
+        :param Optional[Dict[str, Any]] variables: Optional query variables.
+        :param Optional[str] after: The cursor for pagination (optional, defaults to None for the first page).
+        :return: A dictionary containing the fetched page of results and pagination information.
+        :rtype: Dict[str, Any]
+        :raises: Exception if an error occurs during the query execution
+        """
+        variables = variables or {}
+        variables["after"] = after
+
+        try:
+            result = self.client.execute(self.query, variable_values=variables)
+            return result
+        except Exception as e:
+            logger.error(f"An error occurred while executing the query: {str(e)}", exc_info=True)
+            logger.error(f"Query: {self.query}")
+            logger.error(f"Variables: {variables}")
+            raise
+
+    def fetch_results(self, variables: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Fetches a single page of results.
+
+        :param Optional[Dict[str, Any]] variables: Optional query variables.
+        :return: A dictionary containing the fetched page of results and pagination information.
+        :rtype: Dict[str, Any]
+        :raises: Exception if an error occurs during the query execution
+        """
+        try:
+            result = self.client.execute(self.query, variable_values=variables)
+            return result
+        except Exception as e:
+            logger.error(f"An error occurred while executing the query: {str(e)}", exc_info=True)
+            logger.error(f"Query: {self.query}")
+            logger.error(f"Variables: {variables}")
+            raise

regscale/utils/lists.py

@@ -0,0 +1,16 @@
+"""Provide utility functions for dealing with lists."""
+
+from typing import Any, Tuple
+
+
+def add_and_return_unique(*lists: Tuple[Any]) -> list:  # noqa: DOC103
+    """Add lists together and return a list of unique elements
+
+    :param Tuple[Any] *lists: lists to add together
+    :return: a list of unique elements
+    :rtype: list
+    """
+    unique_elements = set()
+    for lst in lists:
+        unique_elements.update(lst)
+    return list(unique_elements)

regscale/utils/numbers.py

@@ -0,0 +1,12 @@
+"""Define functions relating to numbers"""
+
+from typing import Any
+
+
+def is_number(value: Any) -> bool:
+    """Determine if a value is a number
+    :param Any value: value to check
+    :return: whether the value is a number
+    :rtype: bool
+    """
+    return isinstance(value, (int, float, complex))

regscale/utils/shell.py

@@ -0,0 +1,148 @@
+"""Define methods for use with CLI operations."""
+
+from pprint import pprint
+from shlex import split as shlexsplit
+from subprocess import (
+    check_output,
+    Popen,
+    PIPE,
+    run,
+    CalledProcessError,
+)
+from typing import Union
+
+
+def strbyte(string: str, encoding: str = "utf-8") -> bytes:
+    """Convert a string to bytes
+
+    String will have `\n` append and converted to encoding.
+
+    :param str string: the string to convert to bytes
+    :param str encoding: the encoding to use, defaults to "utf-8"
+    :return: a bytes object
+    :rtype: bytes
+    """
+    if not string.endswith("\n"):
+        string += "\n"
+    return bytes(string, encoding=encoding)
+
+
+# FIXME - this was useful early on -- will any of this be useful once the SDK is in-place?
+def send_input_to_process_via_communicate(
+    process: Popen,
+    input_: str,
+    encoding: str = "utf-8",
+) -> tuple:
+    """Send an input string to a process
+
+    When passed a Popen process, send the input as an encoded bytes
+
+    :param Popen process: the Popen process
+    :param str input_: a string to send to the process
+    :param str encoding: specify the encoding, defaults to "utf-8"
+    :return: a tuple of stdout, stderr
+    :rtype: tuple
+    """
+    return process.communicate(strbyte(string=input_, encoding=encoding))
+
+
+def run_command(
+    cmd: Union[str, list],
+) -> bool:
+    """Run a shell command
+
+    Use python subprocess to run a command.
+
+    :param Union[str, list] cmd: a list or string of commands to execute
+    :raises CalledProcessError: if the command returns an error
+    :return: a bool indicating success or failure
+    :rtype: bool
+    """
+    if isinstance(cmd, str):
+        cmd = shlexsplit(cmd)
+    try:
+        run(cmd, check=True, stdout=PIPE, stderr=PIPE)
+        return True
+    except CalledProcessError as exc:
+        print(f"Command '{' '.join(cmd)}' returned with error (code {exc.returncode}): {exc.output.decode()}")
+        raise exc
+
+
+def run_command_and_store_output(
+    cmd: Union[str, list],
+    output: bool = False,
+) -> str:
+    """Run a shell command and store the output
+
+    Runs a simple shell command and stores the output as a string.
+
+    :param Union[str, list] cmd: a list or string of commands
+    :param bool output: should pprint be used to display, defaults to False
+    :return: A string of the command output
+    :rtype: str
+    """
+    if isinstance(cmd, list):
+        cmd = " ".join(cmd)
+    cmd_output = check_output(cmd, shell=True, text=True)
+    if output:
+        pprint(f"Command output:\n{cmd_output}")
+    return cmd_output
+
+
+def send_input_to_process(
+    process: Popen,
+    input_: str,
+) -> None:
+    """Send an input string to a process
+
+    When passed a Popen process, send the input as an encoded bytes
+
+    :param Popen process: the Popen process
+    :param str input_: a string to send to the process
+    return: None
+    """
+    process.stdin.write(input_)
+    process.stdin.flush()
+
+
+def run_command_interactively(
+    cmd: Union[str, list],
+    inputs: Union[str, list],
+    output: bool = False,
+    include_error: bool = False,
+) -> str:
+    """Run a command by sending inputs
+
+    Runs a shell command and send inputs to it
+
+    :param Union[str, list] cmd: the initial command to invoke
+    :param Union[str, list] inputs: a single str of inputs or a list to pass to the command interactively
+    :param bool output: should output be pprinted? defaults to False
+    :param bool include_error: should error be output as well?, default False
+    :return: A string of the command output
+    :rtype: str
+    """
+    if isinstance(cmd, list):
+        cmd = " ".join(cmd)
+
+    process = Popen(shlexsplit(cmd), stdin=PIPE, stdout=PIPE, stderr=PIPE, text=True)
+
+    if isinstance(inputs, str):
+        inputs = [inputs]
+
+    for input_ in inputs:
+        send_input_to_process(process=process, input_=input_)
+
+    stdout, stderr = process.communicate()
+    output_std = stdout or ""
+    output_err = stderr or ""
+
+    if output:
+        pprint(output_std)
+        if include_error:
+            pprint(output_err)
+
+    result = output_std
+    if include_error:
+        result += "\n" + output_err
+    return result