automation-traverse 0.1.0__tar.gz

automation_traverse-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: automation-traverse
+Version: 0.1.0
+Summary: Automate tasks in graph format
+Author-email: Michael Renken <michaelarenken@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SudoVim/automation-traverse
+Project-URL: Issues, https://github.com/SudoVim/automation-traverse/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# automation-traverse
+
+Project for setting up a graph of nodes that can be traversed as part of a
+suite of automated tasks. This project builds on top of the
+"automation-entities" project.

automation_traverse-0.1.0/README.md

@@ -0,0 +1,5 @@
+# automation-traverse
+
+Project for setting up a graph of nodes that can be traversed as part of a
+suite of automated tasks. This project builds on top of the
+"automation-entities" project.

automation_traverse-0.1.0/automation_traverse/__init__.py

@@ -0,0 +1 @@
+

automation_traverse-0.1.0/automation_traverse/asserter.py

@@ -0,0 +1,48 @@
+"""
+module pertaining to asserting
+"""
+
+import pprint
+from typing import Any, Dict
+
+from automation_entities.context import Context
+from automation_entities.entities import Entity
+
+
+class DictAsserter(Entity):
+    """
+    asserter for asserting on ``dict`` keys and values
+
+    .. attribute:: val
+
+        ``dict`` representing the dict values
+    """
+
+    val: Dict[Any, Any]
+
+    def __init__(self, context: Context, val: Dict[Any, Any]) -> None:
+        self.val = val
+        super().__init__(context, pprint.pformat(val))
+
+    def get_value(self, key: Any) -> Any:
+        """
+        get and return the value corresponding to the given *key*
+        """
+        with self.interaction():
+            _ = self.request(f"get_value {key}")
+
+            if key not in self.val:
+                raise AssertionError(f"{self.val} does not contain key {key}")
+
+            with self.result() as result:
+                val = self.val[key]
+                result.log(f"Val: {pprint.pformat(val)}")
+
+                if isinstance(val, dict):
+                    val = self.__class__(
+                        self.context, val  # pyright: ignore[reportUnknownArgumentType]
+                    )
+                return val
+
+    def __getitem__(self, key: Any) -> Any:
+        return self.get_value(key)

automation_traverse-0.1.0/automation_traverse/context.py

@@ -0,0 +1,202 @@
+from typing import IO, Any, Dict, Generic, List, Optional, Type
+
+from automation_entities.context import Context, Subcontext
+from typing_extensions import override
+
+from .emitters import Emitter, LogLevel, T
+
+
+class TraverseContext(Context, Generic[T]):
+    """
+    :class:`automation_entities.context.Context` that supports multiple
+    :class:`Emitter` s.
+    """
+
+    emitters: List[Emitter[T]]
+
+    def __init__(
+        self,
+        config_defaults: Optional[  # pyright: ignore[reportUnknownParameterType]
+            dict  # pyright: ignore[reportMissingTypeArgument]
+        ] = None,
+        subcontext_class: Optional[Type[Subcontext]] = None,
+    ):
+        super().__init__(  # pyright: ignore[reportUnknownMemberType]
+            config_defaults, subcontext_class
+        )
+
+        self.emitters = []
+
+    def add_emitter(self, emitter: Emitter[T]) -> None:
+        """
+        Add the given *emitter* to the :attr:`emitters` list.
+        """
+        self.emitters.append(emitter)
+
+    @override
+    def subcontext(
+        self, message: str, log_level: LogLevel = LogLevel.INFO
+    ) -> "TraverseSubcontext[T]":
+        """
+        subcontext implementation that creates a :class:`TraverseSubcontext`
+        subcontext rather than the original.
+        """
+        for emitter in self.emitters:
+            emitter.log_message(log_level, message)
+
+        return TraverseSubcontext(self, self)
+
+    def pop_subcontext(self, context_level: int) -> None:
+        """
+        Pop all emitters back to the given *context_level*.
+        """
+        for emitter in self.emitters:
+            emitter.pop_subcontext(context_level)
+
+    @override
+    def log(self, message: str) -> None:
+        """
+        Log the given *message* as info.
+        """
+        self.log_info(message)
+
+    def log_file(
+        self, description: str, extension: str, mode: str = "w"
+    ) -> "TraverseFile":
+        """
+        Log the given *description* and create a file of the given *extension*
+        and *mode*.
+        """
+        return TraverseFile(
+            [e.log_file(description, extension, mode) for e in self.emitters],
+        )
+
+    def log_message(self, log_level: LogLevel, message: str) -> None:
+        """
+        Log the given *message* at the given *log_level* to all configured
+        emitters. For more information on *log_level*, see
+        :meth:`emitters.Emitter.log_message`.
+        """
+        for emitter in self.emitters:
+            emitter.log_message(log_level, message)
+
+    def log_debug(self, message: str) -> None:
+        """
+        log the given *message* at debug level.
+        """
+        self.log_message(LogLevel.DEBUG, message)
+
+    def log_procedure(self, message: str) -> None:
+        """
+        log the given *message* at procedure level.
+        """
+        self.log_message(LogLevel.PROCEDURE, message)
+
+    def log_info(self, message: str) -> None:
+        """
+        log the given *message* at info level.
+        """
+        self.log_message(LogLevel.INFO, message)
+
+    def log_skip(self, message: str) -> None:
+        """
+        log the given *message* at skip level.
+        """
+        self.log_message(LogLevel.SKIP, message)
+
+    def log_success(self, message: str) -> None:
+        """
+        log the given *message* at success level.
+        """
+        self.log_message(LogLevel.SUCCESS, message)
+
+    def log_error(self, message: str) -> None:
+        """
+        log the given *message* at error level.
+        """
+        self.log_message(LogLevel.ERROR, message)
+
+    def log_fail(self, message: str) -> None:
+        """
+        log the given *message* at fail level.
+        """
+        self.log_message(LogLevel.FAIL, message)
+
+    def log_catastrophic(self, message: str) -> None:
+        """
+        log the given *message* at catastrophic level.
+        """
+        self.log_message(LogLevel.CATASTROPHIC, message)
+
+    def log_response(self, task: T, response: Dict[str, Any]) -> None:
+        """
+        log the given *response* for the given *task*
+        """
+        for emitter in self.emitters:
+            emitter.log_response(task, response)
+
+
+class TraverseSubcontext(Subcontext, Generic[T]):
+    """
+    :class:`automation_entities.context.Subcontext` that supports multiple
+    :class:`automation_traverse.emitters.Emitter` s.
+    """
+
+    tranverse_context: "TraverseContext[T]"
+
+    def __init__(self, context: "Context", tranverse_context: "TraverseContext[T]"):
+        super().__init__(context)
+
+        self.tranverse_context = tranverse_context
+
+    @override
+    def __enter__(self) -> "TraverseSubcontext[T]":
+        _ = super().__enter__()
+
+        for emitter in self.tranverse_context.emitters:
+            emitter.subcontext()
+
+        return self
+
+    @override
+    def __exit__(self, *args: Any, **kwds: Any) -> None:
+        super().__exit__(*args, **kwds)  # pyright: ignore[reportUnknownMemberType]
+
+        self.tranverse_context.pop_subcontext(self.tranverse_context.log_position)
+
+
+class TraverseFile:
+    """
+    File-like object that multiplexes multiple file-like objects into one
+    object.
+
+    .. autoattribute:: fobjs
+    """
+
+    #: file objects wrapped by this class
+    fobjs: List[IO[str]]
+
+    def __init__(self, fobjs: List[IO[str]]) -> None:
+        self.fobjs = fobjs
+
+    def __enter__(self) -> "TraverseFile":
+        return self
+
+    def __exit__(self, *args: Any, **kwds: Any) -> None:
+        self.close()
+
+    def write(self, data: str) -> int:
+        """
+        Write *data* to all :attr:`fobjs`
+        """
+        if not self.fobjs:
+            return len(data)
+
+        return min(fobj.write(data) for fobj in self.fobjs)
+
+    def close(self) -> None:
+        """
+        Close all :attr:`fobjs`
+        """
+        for fobj in self.fobjs:
+            fobj.close()

automation_traverse-0.1.0/automation_traverse/discover.py

@@ -0,0 +1,85 @@
+"""
+module for discovering objects in Python
+"""
+
+import importlib.util
+import os
+from types import ModuleType
+from typing import Any, Dict, Iterator, Tuple, Type
+
+from .task import Task
+
+ImportedModuleKey = Tuple[str, str]
+
+imported_modules: Dict[ImportedModuleKey, ModuleType] = {}
+
+
+def import_module(pypath: str, filepath: str) -> ModuleType:
+    """
+    Import and return the module at the given *pypath* and *filepath*
+    """
+    key = (pypath, filepath)
+    if key not in imported_modules:
+        spec = importlib.util.spec_from_file_location(pypath, filepath)
+        if spec is None or spec.loader is None:
+            raise ValueError(f"module {key} not found")
+
+        new_module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(new_module)
+        imported_modules[key] = new_module
+
+    return imported_modules[key]
+
+
+def walk_modules(start_point: str) -> Iterator[Tuple[str, ModuleType]]:
+    """
+    walk over all modules from the given *start_point*
+    """
+    start_point = os.path.abspath(start_point)
+    for root, _, files in os.walk(start_point):
+        relpath = os.path.relpath(root, os.path.dirname(start_point))
+        module_path = tuple(relpath.split(os.path.sep))
+
+        for fname in files:
+            if fname == "__init__.py":
+                filepath = os.path.join(root, fname)
+                pypath = ".".join(module_path)
+                new_module = import_module(pypath, filepath)
+                yield pypath, new_module
+
+            elif fname.endswith("__.py"):
+                continue
+
+            elif fname.endswith(".py"):
+                filepath = os.path.join(root, fname)
+                pypath = ".".join(module_path + (fname[:-3],))
+                new_module = import_module(pypath, filepath)
+                yield pypath, new_module
+
+
+def walk_object(obj: Any) -> Iterator[Any]:
+    """
+    Walk over the given object for its members
+    """
+    for attr in dir(obj):
+        yield attr, obj.__getattribute__(attr)
+
+
+def walk_tasks(
+    start_point: str,
+    discover_all: bool = False,
+) -> Iterator[Tuple[str, str, Type[Task]]]:
+    """
+    Walk over a module and return its tasks
+
+    :param bool discover_all: whether or not to discover tasks not marked
+        as discoverable
+    """
+    for modulepath, module in walk_modules(start_point):
+        for objname, obj in walk_object(module):
+            if (
+                isinstance(obj, type)
+                and issubclass(obj, Task)
+                and (discover_all or obj.DISCOVER)
+            ):
+                yield modulepath, objname, obj

automation_traverse-0.1.0/automation_traverse/emitters/__init__.py

@@ -0,0 +1,3 @@
+from .emitter import Emitter, LogLevel, T
+
+__all__ = ["T", "Emitter", "LogLevel"]

automation_traverse-0.1.0/automation_traverse/emitters/emitter.py

@@ -0,0 +1,152 @@
+import collections
+import os
+from enum import Enum
+from typing import IO, Any, Dict, Generic, TypeVar
+
+
+class LogLevel(Enum):
+    """
+    Enum indicating the different valid log levels when logging messages to an
+    emitter.
+
+    .. autoattribute:: DEBUG
+    .. autoattribute:: PROCEDURE
+    .. autoattribute:: INFO
+    .. autoattribute:: SKIP
+    .. autoattribute:: SUCCESS
+    .. autoattribute:: ERROR
+    .. autoattribute:: FAIL
+    .. autoattribute:: CATASTROPHIC
+    """
+
+    #: Messages meant to provide deeper insight that isn't always necessary
+    DEBUG = "debug"
+
+    #: Messages pertaining to the traversal procedure
+    PROCEDURE = "procedure"
+
+    #: Informational messages about what's happening in the task
+    INFO = "info"
+
+    #: Message indicating text related to a task skip
+    SKIP = "skip"
+
+    #: Message indicating some level of success
+    SUCCESS = "success"
+
+    #: Something unexpected happened which may not be recoverable
+    ERROR = "error"
+
+    #: A specific condition in the task has failed and is likely recoverable
+    FAIL = "fail"
+
+    #: Something unrecoverrable happened that requires human attention
+    CATASTROPHIC = "catastrophic"
+
+
+T = TypeVar("T")
+
+
+class Emitter(Generic[T]):
+    """
+    An emitter is an abstraction that exists to determine how various debug
+    information is to be passed on to the user. This is done through the
+    various hooks that are required to be implememented.
+
+    .. attribute:: tasks
+
+        :var:`T`\\s run under this emitter
+
+    .. attribute:: context_level
+
+        `int` context level starting from 0
+
+    .. automethod:: subcontext
+    .. automethod:: pop_subcontext
+    .. automethod:: log_message
+    .. automethod:: log_file
+    .. automethod:: finalize
+    """
+
+    tasks: "collections.OrderedDict[T, None]"
+
+    #: Context level starting from 0
+    context_level: int
+
+    def __init__(self):
+        self.context_level = 0
+        self.tasks = collections.OrderedDict()
+
+    def start_task(self, instance: T) -> None:
+        """
+        Hook that exists to inject some behavior in event of a new test
+        *instance* starting.
+        """
+        self.tasks[instance] = None
+
+    def end_task(self, instance: T) -> None:  # pyright: ignore[reportUnusedParameter]
+        """
+        Hook that exists to inject some behavior in event of a new test
+        *instance* ending.
+        """
+
+    def subcontext(self) -> None:
+        """
+        Enter into a new subcontext. The idea behind this method is to allow
+        emitters to nest output inside of other output in an effort to be able
+        to collapse and expand text information.
+
+        If overridden by a subclass, be sure to call this original method
+        to retain the default functionality.
+        """
+        self.context_level += 1
+
+    def pop_subcontext(self, context_level: int) -> None:
+        """
+        Pop subcontext to the given *context_level*, which starts from 0 before
+        the first :meth:`subcontext` call.
+
+        If overridden by a subclass, be sure to call this original method
+        to retain the default functionality.
+        """
+        self.context_level = context_level
+
+    def log_message(
+        self,
+        log_level: LogLevel,  # pyright: ignore[reportUnusedParameter]
+        message: str,  # pyright: ignore[reportUnusedParameter]
+        end: str = "\n",  # pyright: ignore[reportUnusedParameter]
+    ) -> None:
+        """
+        Log the given *message* at the given *log_level*. If a multi-line
+        message is given, it's expected to be handled appropriately by the
+        emitter.
+        """
+
+    def log_file(
+        self,
+        description: str,  # pyright: ignore[reportUnusedParameter]
+        extension: str,  # pyright: ignore[reportUnusedParameter]
+        mode: str = "w",
+    ) -> IO[str]:
+        """
+        Create a file object with the given *description* and file *extension*.
+        This object will be used by the caller. It's up to the caller to close
+        it when done.
+        """
+        return open(os.devnull, mode)
+
+    def log_response(
+        self,
+        task: T,  # pyright: ignore[reportUnusedParameter]
+        response: Dict[str, Any],  # pyright: ignore[reportUnusedParameter]
+    ) -> None:
+        """
+        Log the given *response* for a task.
+        """
+
+    def finalize(self):
+        """
+        Hook for finalizing the emitter in case there's something that needs to
+        be cleaned up.
+        """

automation_traverse-0.1.0/automation_traverse/emitters/simple_log.py

@@ -0,0 +1,79 @@
+import collections
+from collections.abc import Mapping
+from typing import Optional
+
+import colorama
+from typing_extensions import override
+
+from .emitter import Emitter, LogLevel, T
+
+
+class SimpleLogEmitter(Emitter[T]):
+    """
+    The SimpleLogEmitter is an abstract :class:`Emitter` implementation that
+    allows for subclasses to simply implement a single :meth:`emit` method
+    to determine where the data goes. The *use_color* argument defaults to
+    ``True`` and determines whether or not log messages should be emitted
+    with color encoding.
+
+    :param bool use_color: whether or not to output in color (default
+        ``True``)
+    :param int context_level_spaces: number of spaces per context level
+        (default 4)
+
+    .. automethod:: emit
+    """
+
+    use_color: bool
+    context_level_spaces: int
+
+    DEFAULT_CONTEXT_LEVEL_SPACES: int = 4
+
+    LOG_LEVEL_COLORS: Mapping[LogLevel, str] = collections.defaultdict(
+        lambda: colorama.Style.RESET_ALL,
+        {
+            LogLevel.DEBUG: colorama.Fore.WHITE + colorama.Style.DIM,
+            LogLevel.PROCEDURE: colorama.Fore.BLUE,
+            LogLevel.INFO: colorama.Fore.WHITE,
+            LogLevel.SKIP: colorama.Fore.MAGENTA + colorama.Style.BRIGHT,
+            LogLevel.SUCCESS: colorama.Fore.GREEN,
+            LogLevel.ERROR: colorama.Fore.RED + colorama.Style.BRIGHT,
+            LogLevel.FAIL: colorama.Fore.RED,
+            LogLevel.CATASTROPHIC: colorama.Fore.CYAN + colorama.Style.BRIGHT,
+        },
+    )
+
+    def __init__(
+        self,
+        use_color: bool = True,
+        context_level_spaces: Optional[int] = None,
+    ):
+        super().__init__()
+
+        self.use_color = use_color
+        self.context_level_spaces = (
+            context_level_spaces or self.DEFAULT_CONTEXT_LEVEL_SPACES
+        )
+
+    @override
+    def log_message(self, log_level: LogLevel, message: str, end: str = "\n") -> None:
+        """
+        Specific information of :meth:`Emitter.log_message` that calls
+        :meth:`emit` with color-encoded text.
+        """
+        spaces = " " * (self.context_level * self.context_level_spaces)
+        color_pre_tag = ""
+        color_post_tag = ""
+        if self.use_color:
+            color_pre_tag = self.LOG_LEVEL_COLORS[log_level]
+            color_post_tag = colorama.Style.RESET_ALL
+
+        for line in message.splitlines() if end == "\n" else message.split(end):
+            line = line.rstrip()
+            self.emit(f"{spaces}{color_pre_tag}{line}{color_post_tag}{end}")
+
+    def emit(self, message: str) -> None:  # pyright: ignore[reportUnusedParameter]
+        """
+        Emit the given *message*. This should be implemented by sub-class
+        implementations.
+        """

automation_traverse-0.1.0/automation_traverse/emitters/terminal.py

@@ -0,0 +1,67 @@
+import io
+import pprint
+import sys
+from typing import Any, Dict, Optional, TextIO, Union
+
+from typing_extensions import override
+
+from .emitter import LogLevel, T
+from .simple_log import SimpleLogEmitter
+
+
+class TerminalEmitter(SimpleLogEmitter[T]):
+    """
+    :class:`SimpleLogEmitter` implementation that logs output to the terminal
+    or to the given *fobj*.
+
+    :param bool use_color: whether or not to output in color (default
+        ``True``)
+    :param bool flush: whether or not to flush to the file after every
+        message
+    :param fobj: file-like object to log to (default :data:`sys.stdout`)
+    :param int context_level_spaces: number of spaces per context level
+        (default 4)
+    """
+
+    flush: bool
+    fobj: Union[io.IOBase, TextIO]
+
+    def __init__(
+        self,
+        use_color: bool = True,
+        flush: bool = True,
+        fobj: Optional[io.IOBase] = None,
+        context_level_spaces: Optional[int] = None,
+    ):
+        super().__init__(
+            use_color=use_color,
+            context_level_spaces=context_level_spaces,
+        )
+
+        self.flush = flush
+        self.fobj = fobj or sys.stdout
+
+    @override
+    def emit(self, message: str) -> None:
+        """
+        Implementation of :meth:`SimpleLogEmitter.emit` that emits the given
+        *message* text to the configured :attr:`fobj`.
+        """
+        _ = self.fobj.write(message)
+        if self.flush:
+            self.fobj.flush()
+
+    @override
+    def log_response(self, task: T, response: Dict[str, Any]) -> None:
+        """
+        Log the given *response* for a task.
+        """
+        self.log_message(
+            LogLevel.PROCEDURE,
+            "\n".join(
+                [
+                    "Response for task:",
+                    pprint.pformat(response),
+                ]
+            ),
+        )