cgse 2023.38.0__py3-none-any.whl → 2024.1.3__py3-none-any.whl

egse/resource.py

@@ -1,333 +0,0 @@
-"""
-This module provides convenience functions to use resources in your code without
-the need to specify an absolute path or try to locate the resources in your local
-installation (which is time-consuming, error-prone, and introduces quite some
-redundancy).
-
-Resources can be files of different format that are distributed together with the
-source code, e.g.
-
-    * image data
-    * icons
-    * YAML files
-    * binary files, e.g. dynamic libraries
-    * style files for GUI applications
-    * calibration files distributed with the source code
-
-Each of the resources have a fixed location within the source tree and is identified
-with a resource identifier. There are a number of default identifier that are defined
-as follows:
-
-    * `icons`: located in the sub-folder 'icons'
-    * `images`: located in the sub-folder 'images'
-    * `lib`: located in sub-folder 'lib'
-
-Resource locations are determined during startup at a number of predefined
-locations for the following resource identifiers:
-
-    * from known hardcoded folder names, e.g. 'images', 'icons', and 'lib'.
-
-Resources can be accessed from the code without specifying the absolute pathname,
-using a `:/resource_od/` that is known by the resource module. A wildcard can be
-introduces after the `resource_id` to indicate the resource is in one of the
-sub-directories.
-
-Example usage:
-    * get_resource(":/icons/open-document.png")
-    * get_resource(":/styles/dark.qss")
-    * get_resource(":/lib/*/EtherSpaceLink_v34_86.dylib")
-
-A new `resource_id` can be added with the `add_resource_id()` function, specifying a
-resource_id string and location. When the `force=True` keyword is given, an existing
-resource_id can be changed.
-
-Alternatives
-
-The `egse.config` module has a number of alternatives for locating files and resources.
-
-    * find_file(..) and find_files(..)
-    * find_dir(..) and find_dirs(..)
-    * get_resource_dirs()
-    * get_resource_path()
-
-The functions for finding files and directories are more flexible, but take more
-time and effort. They are mainly used for dynamically searching for a file or
-folder, not necessarily within the source code location.
-
-The resource specific functions in the egse.config module will be deprecated when
-their functionality is fully replaced by this `egse.resource` module.
-
-"""
-
-import logging
-import re
-from pathlib import Path
-from typing import Dict
-from typing import Union
-
-from egse.config import find_first_occurrence_of_dir
-from egse.config import find_files
-from egse.exceptions import InternalError
-
-MODULE_LOGGER = logging.getLogger(__name__)
-
-
-class ResourceError(Exception):
-    """Base class, raised when a resource is not defined."""
-
-
-class AmbiguityError(ResourceError):
-    """Raised when more than one option is possible."""
-
-
-class NoSuchFileError(ResourceError):
-    """Raised when no file could be found for the given resource."""
-
-
-__all__ = [
-    "get_resource",
-    "get_resource_locations",
-    "add_resource_id",
-    "initialise_resources",
-    "ResourceError",
-    "AmbiguityError",
-    "NoSuchFileError",
-]
-
-# Testing regex: https://pythex.org
-
-PATTERN = re.compile(r"^:/(\w+)/(\*+/)?(.*)$")
-
-DEFAULT_RESOURCES = {
-    "icons": "/icons",
-    "images": "/images",
-    "lib": "/lib",
-    "styles": "/styles",
-    "data": "/data",
-    "aeudata": "/aeu/arbdata",
-}
-
-resources_root = Path(__file__).parent
-resources = {}
-
-__initialised__ = False
-
-
-def check_if_file_exists(filename: Union[Path, str], resource_id: str = None) -> Path:
-    """
-    Check if the given filename exists. If the filename exists, return the filename, else raise a
-    NoSuchFileError.
-
-    Args:
-        filename (Path|str): an absolute filename
-        resource_id (str): a resource identifier
-
-    Return:
-        The given filename if it exists.
-
-    Raises:
-        NoSuchFileError if the given filename doesn't exist.
-    """
-    filename = Path(filename)
-    if filename.is_file():
-        return filename
-
-    if resource_id:
-        raise NoSuchFileError(
-            f"The file '{filename.name}' could not be found for the given resource '{resource_id}'")
-    else:
-        raise NoSuchFileError(f"The file '{filename.name}' doesn't exist.")
-
-
-def contains_wildcard(filename: str):
-    """
-    Returns True if the filename contains a wildcard, otherwise False.
-    A wildcard is an asterisk '*' or a question mark '?' character.
-    """
-    if '*' in filename:
-        return True
-    if '?' in filename:
-        return True
-
-    return False
-
-
-def get_resource_locations() -> Dict[str, Path]:
-    """
-    Returns a dictionary of names that can be used as resource location.
-    The keys are strings that are recognised as valid resource identifiers, the
-    values are their actual absolute path names.
-    """
-    if not __initialised__:
-        MODULE_LOGGER.warning("Resources have not been initialised.")
-
-    return resources.copy()
-
-
-def initialise_resources(root: Union[Path, str] = Path(__file__).parent):
-    """
-    Initialise the default resources.
-
-    The argument `root` specifies the root location for the resources. If not specified,
-    the location of this module is taken as the root location. So, if you have installed
-    this package with `pip install`, you should give the location of your project's source
-    code as the root argument.
-
-    Args:
-        root (Path|str): the root location for the resources.
-
-    Returns:
-        None.
-    """
-    global resources_root
-    global __initialised__
-
-    if __initialised__:
-        MODULE_LOGGER.warning("Resources have already been initialised.")
-        return
-
-    resources_root = Path(root)
-
-    #  the resources with their absolute path names
-
-    for resource_id in DEFAULT_RESOURCES:
-        folder = find_first_occurrence_of_dir(DEFAULT_RESOURCES[resource_id], root=resources_root)
-        resources[resource_id] = folder
-
-    MODULE_LOGGER.debug(f"Resources have been defined: {DEFAULT_RESOURCES=}")
-
-    __initialised__ = True
-
-
-def add_resource_id(resource_id: str, location: Union[Path, str], force=False):
-    """
-    Adds a resource identifier with the given location. Resources can then be specified
-    using this resource id.
-
-    The location can be an absolute or relative pathname. In the latter case an
-    absolute pathname will be constructed using the resource root location that was
-    given during the initialisation (calling `initialise_resources()`).
-
-    If the resource identifier already exists, a ValueError will be raised unless
-    you specify the `force=True` argument.
-
-    Args:
-        resource_id (str): a resource identifier
-        location (Path|str: an absolute or relative pathname
-        force (bool): force adding even if the resource_id exists
-
-    Returns:
-        ValueError if the location can not be determined.
-    """
-    # Check if id already exists, overwrite or raise exception?
-
-    if resource_id in resources and force is False:
-        raise ValueError(f"Resource identifier '{resource_id}' already exists.")
-
-    # Check if location exists and is a directory.
-
-    location = Path(location)
-
-    if location.is_absolute() and location.is_dir():
-        resources[resource_id] = location
-
-    if not location.is_absolute():
-        location = resources_root / location
-        if location.is_dir():
-            resources[resource_id] = location
-        else:
-            raise ValueError(f"Unknown location {location=}")
-
-
-def get_resource(resource_locator: str) -> Path:
-    """
-    Returns the absolute Path for the given resource_locator. The resource_locator consists of
-    a resource_id, an optional wildcard and a filename separated by a forward slash '/' and
-    started by a colon ':'.
-
-        ':/<resource_id>/[*/]<filename>'
-
-    If the resource_locator starts with a colon ':', the name will be interpreted as a resource_id
-    and filename combination and parsed as such
-
-    If the resource_locator doesn't start with a colon ':', then the string will be interpreted as a
-    Path name and returned if that path exists, otherwise a ResourceError is raised.
-
-    The filename can contain the wildcard '*' and/or '?', however the use of a wildcard in the
-    filename can still only match one unique filename. This can be useful e.g. if you know the
-    filename except for one part of it like a timestamp. Used, e.g., for matching Setup files which
-    are unique filenames with a timestamp.
-
-    Args:
-        resource_locator (str): a special resource name or a filename
-
-    Returns:
-        a Path with the absolute filename for the resource.
-
-    Raises:
-        ResourceError when no file could be found or the search is ambiguous.
-
-    """
-    # Try to match the special resource syntax `:/resource_id/` or `:/resource_id/*/`
-
-    if resource_locator.startswith(':'):
-
-        if not __initialised__:
-            MODULE_LOGGER.warning("Resources have not been initialised.")
-
-        match = PATTERN.fullmatch(resource_locator)
-        resource_id = match[1]
-        filename = match[3]
-        try:
-            resource_location = Path(resources[resource_id])
-        except KeyError:
-            raise ResourceError(f"Resource not defined: {resource_id}")
-
-        # Match can be only three things
-        #   - None in which case the file must be in the resource location directly
-        #   - '*/' in which case the file must be in a sub-folder of the resource
-        #   - '**/' to find the file in any sub-folder below the given resource
-
-        if match[2] is None:
-            if contains_wildcard(filename):
-                files = list(find_files(filename, root=resource_location))
-
-                if len(files) == 1:
-                    filename = files[0]
-                elif len(files) == 0:
-                    raise NoSuchFileError(f"No file found that matches {filename=} for the given "
-                                          f"resource '{resource_id}'.")
-                else:
-                    raise AmbiguityError(f"The {filename=} found {len(files)} matches for "
-                                         f"the given resource '{resource_id}'.")
-
-            return check_if_file_exists(resource_location / filename, resource_id)
-
-        elif match[2] == "*/":
-            files = list(find_files(filename, root=resource_location))
-
-            if len(files) == 1:
-                return files[0]
-            elif len(files) == 0:
-                raise NoSuchFileError(
-                    f"The {filename=} could not be found for the given resource '{resource_id}'."
-                )
-            else:
-                raise AmbiguityError(f"The {filename=} was found {len(files)} times for "
-                                     f"the given resource '{resource_id}'.")
-        elif match[2] == '**/':
-            raise NotImplementedError(f"The '**' to walk the tree is not yet implemented.")
-        else:
-            raise InternalError(
-                f"This shouldn't happen, the match is {match[2]=} for {resource_locator=}")
-    else:
-        return check_if_file_exists(Path(resource_locator))
-
-
-initialise_resources()
-
-if __name__ == "__main__":
-
-    import rich
-    rich.print("Default resources:")
-    rich.print(get_resource_locations())

egse/rst.py

@@ -1,135 +0,0 @@
-import yaml
-import logging
-import inspect
-import textwrap
-
-module_logger = logging.getLogger(__name__)
-
-
-def create_args_list(cmd):
-    s = ""
-    if 'args' not in cmd:
-        return s
-    for arg_name in cmd['args'].keys():
-        s += f"{arg_name}, "
-    if 'kwargs' not in cmd:
-        return s[:-2]
-    for arg_name in cmd['kwargs'].keys():
-        s += f"{arg_name}={cmd['kwargs'][arg_name].split('|')[1].strip()}, "
-    return s[:-2]
-
-
-def handle_description(d):
-    s = textwrap.indent(inspect.cleandoc(d), "      ")
-    return s + "\n\n"
-
-
-def handle_args(d):
-    s = ""
-    for arg_name in d:
-        arg_type, arg_desc = [x.strip() for x in d[arg_name].split('|', 1)]
-        s += f"      :param {arg_type} {arg_name}: {arg_desc}\n"
-    return s + "\n\n"
-
-
-def handle_kwargs(d):
-    s = ""
-    for arg_name in d:
-        arg_type, arg_default, arg_desc = [x.strip() for x in d[arg_name].split('|', 2)]
-        s += f"      :param {arg_type} {arg_name}: {arg_desc} [default: {arg_default}]"
-    return s + "\n\n"
-
-
-def handle_returns(d):
-    s = ""
-    if d == "None":
-        return s
-    return_type, return_desc = [x.strip() for x in d.split('|', 2)]
-    s += f"      :returns: (*{return_type}*) {return_desc}\n"
-    # s += f"      :rtype: {return_type}\n"
-    return s + "\n"
-
-
-def handle_todos(d):
-    return f"      .. todo:: {d}\n\n"
-
-
-def handle_notes(d):
-    return f"      .. note:: {d}\n\n"
-
-
-def handle_class_description(d):
-    s = textwrap.indent(inspect.cleandoc(d), "   ")
-    return s + "\n\n"
-
-
-class RSTError(Exception):
-    pass
-
-
-class ReStructuredText(object):
-    """
-    .. todo:: implement proper indentation though a instance variable or something
-    .. todo:: there should also be overall class documentation loaded from the YAML file
-    """
-
-    def __init__(self):
-        pass
-
-    def _read_yaml(self, filename):
-        with open(filename, 'r') as stream:
-            try:
-                yaml_document = yaml.load(stream)
-            except yaml.YAMLError as exc:
-                module_logger.error(exc)
-                raise RSTError(f"Error loading YAML document {filename}") from exc
-        return yaml_document
-
-    def create_auto_class_from_yaml(self, yaml_file):
-
-        yaml_document = self._read_yaml(yaml_file)
-
-        class_name = yaml_document['ProxyClass']
-
-        rst_msg = f".. class:: {class_name}\n\n"
-
-        if 'ClassDescription' in yaml_document:
-            rst_msg += handle_class_description(yaml_document['ClassDescription'])
-
-        cmd_tag = "Commands"
-
-        for cmd in yaml_document[cmd_tag]:
-            rst_msg += self.create_command(yaml_document[cmd_tag], cmd)
-            rst_msg += "\n"
-
-        return rst_msg
-
-    def create_command(self, d, cmd):
-
-        rst_msg = f"   .. method:: {cmd}({create_args_list(d[cmd])})\n\n"
-
-        d = d[cmd]
-
-        if 'description' in d:
-            rst_msg += handle_description(d['description'])
-
-        if 'args' in d:
-            rst_msg += handle_args(d['args'])
-
-        if 'kwargs' in d:
-            rst_msg += handle_kwargs(d['kwargs'])
-
-        if 'returns' in d:
-            rst_msg += handle_returns(d['returns'])
-
-        if 'todo' in d:
-            rst_msg += handle_todos(d['todo'])
-
-        if 'note' in d:
-            rst_msg += handle_notes(d['note'])
-
-        return rst_msg
-
-
-if __name__ == "__main__":
-    pass

egse/search.py

@@ -1,182 +0,0 @@
-"""
-The search module defines some generic search functions.
-
-This code is taken from the book:
-
-    Classic Computer Science Problems in Python, David Kopec, 2019.
-"""
-from __future__ import annotations
-
-from collections import deque
-from typing import TypeVar, Iterable, Sequence, Generic, List, \
-    Callable, Set, Deque, Dict, Any, Optional
-from typing_extensions import Protocol
-from heapq import heappush, heappop
-
-T = TypeVar('T')
-
-
-def linear_contains(iterable: Iterable[T], key: T) -> bool:
-    for item in iterable:
-        if item == key:
-            return True
-    return False
-
-
-# Note that Protocol is used here to define the Comparable type with structural
-# sub-typing. A Comparable type implements the comparison operators.
-# Protocol is defined in PEP-544 [https://www.python.org/dev/peps/pep-0544/]
-
-C = TypeVar('C', bound='Comparable')
-
-
-class Comparable(Protocol):
-    def __eq__(self, other: Any) -> bool:
-        ...
-
-    def __lt__(self: C, other: C) -> bool:
-        ...
-
-    def __gt__(self: C, other: C) -> bool:
-        return (not self < other) and self != other
-
-    def __le__(self: C, other: C) -> bool:
-        return self < other or self == other
-
-    def __ge__(self: C, other: C) -> bool:
-        return not self < other
-
-
-def binary_contains(sequence: Sequence[C], key: C) -> bool:
-    low: int = 0
-    high: int = len(sequence) - 1
-    while low <= high:  # while there is still a search space
-        mid: int = (low + high) // 2
-        if sequence[mid] < key:
-            low = mid + 1
-        elif sequence[mid] > key:
-            high = mid - 1
-        else:
-            return True
-    return False
-
-
-class Stack(Generic[T]):
-    def __init__(self) -> None:
-        self._container: List[T] = []
-
-    @property
-    def empty(self) -> bool:
-        return not self._container
-
-    def push(self, item: T) -> None:
-        self._container.append(item)
-
-    def pop(self) -> T:
-        return self._container.pop()  # LIFO
-
-    def __repr__(self) -> str:
-        return repr(self._container)
-
-
-class Node(Generic[T]):
-    def __init__(self, state: T, parent: Optional[Node], cost: float = 0.0, heuristic: float = 0.0) -> None:
-        self.state: T = state
-        self.parent: Optional[Node] = parent
-        self.cost: float = cost
-        self.heuristic: float = heuristic
-
-    def __lt__(self, other: Node) -> bool:
-        return (self.cost + self.heuristic) < (other.cost + other.heuristic)
-
-
-def depth_first_search(initial: T, goal_test: Callable[[T], bool], successors: Callable[[T], List[T]]) -> Optional[Node[T]]:
-    """
-    The depth-first search (DFS) algorithm goes as deeply as it can before backtracking to its
-    last decision point if it reaches a dead end.
-
-    Args:
-        initial: starting point for the search
-        goal_test: function that defines if the goal is reached or not
-        successors: function that returns all possible states that can be visited next
-
-    Returns:
-        the Node encapsulating the goal state if successful, otherwise None.
-    """
-    frontier: Stack[Node[T]] = Stack()
-    frontier.push(Node(initial, None))
-    explored: Set[T] = set(initial)
-
-    while not frontier.empty:
-        current_node: Node[T] = frontier.pop()
-        current_state: T = current_node.state
-
-        if goal_test(current_state):
-            return current_node
-
-        for child in successors(current_state):
-            if child in explored:
-                continue
-            explored.add(child)
-            frontier.push(Node(child, current_node))
-
-    return None  # we went through everything and never found goal
-
-
-def node_to_path(node: Node[T]) -> List[T]:
-    """
-    Returns the path that was followed from a starting state to reach a goal.
-
-    Args:
-        node:
-
-    Returns:
-        a list of states that were visited to reach the final goal.
-    """
-    path: List[T] = [node.state]
-
-    while node.parent is not None:
-        node = node.parent
-        path.append(node.state)
-    path.reverse()
-    return path
-
-
-class Queue(Generic[T]):
-    def __init__(self) -> None:
-        self._container: Deque[T] = deque()
-
-    @property
-    def empty(self) -> bool:
-        return not self._container
-
-    def push(self, item: T) -> None:
-        self._container.append(item)
-
-    def pop(self) -> T:
-        return self._container.popleft()
-
-    def __repr__(self) -> str:
-        return repr(self._container)
-
-
-def breadth_first_search(initial: T, goal_test: Callable[[T], bool], successors: Callable[[T], List[T]]) -> Optional[Node[T]]:
-    frontier: Queue[Node[T]] = Queue()
-    frontier.push(Node(initial, None))
-    explored: Set[T] = set(initial)
-
-    while not frontier.empty:
-        current_node: Node[T] = frontier.pop()
-        current_state: T = current_node.state
-
-        if goal_test(current_state):
-            return current_node
-
-        for child in successors(current_state):
-            if child in explored:
-                continue
-            explored.add(child)
-            frontier.push(Node(child, current_node))
-
-    return None  # we went through everything and never found goal
-