markten 0.1.0__py3-none-any.whl

markten/__consts.py

@@ -0,0 +1,5 @@
+"""
+# Markten / consts
+"""
+
+VERSION = "0.1.0"

markten/__init__.py

@@ -0,0 +1,15 @@
+"""
+# MarkTen
+
+A manual marking automation framework.
+"""
+from .__recipe import Recipe
+from . import parameters
+from . import actions
+
+
+__all__ = [
+    'Recipe',
+    'parameters',
+    'actions',
+]

markten/__main__.py

@@ -0,0 +1,34 @@
+"""
+# MarkTen / Main
+
+Programmatic entrypoint to MarkTen, allowing it to be run as a script.
+"""
+import sys
+import os
+from . import __utils as utils
+
+
+def show_info():
+    utils.show_banner()
+    print("Usage:")
+    print("  markten <recipe-script> [arguments]")
+    print("  This will execute the given script in Markten's Python")
+    print("  environment.")
+    print("License: MIT")
+    print("Author: Maddy Guthridge")
+
+
+def main():
+    if len(sys.argv) == 1 or sys.argv[1] in ["-h", "--help"]:
+        show_info()
+        exit(1)
+    else:
+        # Attempt to execute the given file with any remaining arguments
+        recipe = sys.argv[1]
+        args = sys.argv[2:]
+
+        os.execv(sys.executable, ("python", recipe, *args))
+
+
+if __name__ == '__main__':
+    main()

markten/__permutations.py

@@ -0,0 +1,38 @@
+
+
+from collections.abc import Iterable, Mapping, Generator
+from typing import Any
+
+
+def recursive_generator(
+    keys: list[str],
+    params_dict: Mapping[str, Iterable[Any]],
+) -> Generator[dict[str, Any], None, None]:
+    """
+    Recursively iterate over the given keys, producing a dict of values.
+    """
+    keys_head = keys[0]
+    # Base case: this is the last remaining key
+    if len(keys) == 1:
+        for value in params_dict[keys_head]:
+            yield {keys_head: value}
+        return
+
+    # Recursive case, other keys remain, and we need to iterate over those too
+    keys_tail = keys[1:]
+
+    for value in params_dict[keys_head]:
+        # Iterate over remaining keys
+        for current_params in recursive_generator(keys_tail, params_dict):
+            # Overall keys is the union of the current key-value pair with
+            # the params yielded by the recursion
+            yield {keys_head: value} | current_params
+
+
+def dict_permutations_iterator(
+    params: Mapping[str, Iterable[Any]],
+) -> Generator[dict[str, Any], None, None]:
+    """
+    Iterate over all possible parameter values provided by the generators.
+    """
+    return recursive_generator(list(params.keys()), params)

markten/__recipe.py

@@ -0,0 +1,261 @@
+"""
+# MarkTen / Recipe
+
+Contains the definition for the main MarkTen class.
+"""
+import asyncio
+import inspect
+from traceback import print_exception
+from .actions import MarkTenAction
+from typing import Union, Callable, Any
+from collections.abc import Mapping, Iterable
+from .__permutations import dict_permutations_iterator
+from . import __utils as utils
+from .__spinners import SpinnerManager
+
+
+ParameterPermutations = Mapping[str, Iterable[Any]]
+"""
+Mapping containing iterables for all permutations of the available params.
+"""
+
+GeneratedActions = Union[
+    MarkTenAction,
+    tuple[MarkTenAction, ...],
+    Mapping[str, MarkTenAction],
+]
+"""
+`GeneratedActions` is a collection of actions run in parallel as a part of a
+step in the marking recipe.
+
+This can be one of:
+
+* `MarkTenAction`: a single anonymous action, whose result is discarded.
+* `tuple[MarkTenAction, ...]`: a collection of anonymous actions.
+* `Mapping[str, MarkTenAction]`: a collection of named actions, whose results
+  are stored as parameters under the given names.
+"""
+
+ActionGenerator = Callable[..., 'ActionStep']
+"""
+An `ActionGenerator` is a function that may accept any current parameters, and
+must return an `ActionStep`, which is expanded recursively.
+"""
+
+
+ActionStepItem = Union[
+    ActionGenerator,
+    GeneratedActions,
+]
+"""
+Each item in a step must either be a function that generates actions, or
+pre-generated actions.
+"""
+
+
+ActionStep = Union[
+    ActionStepItem,
+    tuple[ActionStepItem, ...]
+]
+"""
+An `ActionStep` is a collection of items that should be executed in parallel.
+"""
+
+GeneratedActionStep = tuple[
+    dict[str, MarkTenAction],
+    list[MarkTenAction]
+]
+"""
+An `ActionStep` after running any action generators.
+
+This is used internally when running the actions.
+
+A tuple of:
+
+* `dict[str, MarkTenAction]`: named actions
+* `list[MarkTenAction]`: anonymous actions
+"""
+
+
+class Recipe:
+    def __init__(
+        self,
+        recipe_name: str,
+    ) -> None:
+        self.__name = recipe_name
+        self.__params: dict[str, Any] = {}
+        self.__steps: list[tuple[str, ActionStep]] = []
+
+    def parameter(self, name: str, values: Iterable[str]) -> None:
+        """
+        Add a single parameter to the recipe.
+        """
+        self.__params[name] = values
+
+    def parameters(self, parameters: ParameterPermutations) -> None:
+        """
+        Add a collection of parameters for the recipe.
+        """
+        self.__params |= dict(parameters)
+
+    def step(self, name: str, step: ActionStep) -> None:
+        """
+        Add a step to the recipe
+        """
+        self.__steps.append((name, step))
+
+    def run(self):
+        """
+        Run the marking recipe for each combination given by the generators.
+        """
+        asyncio.run(self.__do_run())
+
+    async def __do_run(self):
+        """Async implementation of running the marking recipe"""
+        utils.show_banner()
+        print(f"Running recipe '{self.__name}'")
+        for params in dict_permutations_iterator(self.__params):
+            # Begin marking with the given parameters
+            show_current_params(params)
+            try:
+                await self.__run_recipe(params)
+            except Exception as e:
+                print("\n\n")
+                print_exception(e)
+            print()
+
+        print("Recipe ran for all inputs")
+
+    async def __run_recipe(self, params: Mapping[str, Any]):
+        """Execute the marking recipe using the given params"""
+        params = dict(params)
+
+        actions_by_step: list[GeneratedActionStep] = []
+        """
+        Actions ordered by step, used to ensure that we can run any required
+        teardown at the end of the recipe.
+        """
+        for i, (name, step) in enumerate(self.__steps):
+            # Convert the step into a list of actions to be run in parallel
+            actions_to_run = generate_actions_for_step(step, params)
+            actions_by_step.append(actions_to_run)
+
+            spinners = SpinnerManager(f"{i + 1}. {name}")
+
+            # Run all tasks
+            named_tasks: dict[str, asyncio.Task[Any]] = {}
+            anonymous_tasks: list[asyncio.Task[Any]] = []
+            # Named tasks
+            for key, action in actions_to_run[0].items():
+                named_tasks[key] = asyncio.create_task(
+                    action.run(spinners.create_task(action.get_name())))
+            # Anonymous tasks
+            for action in actions_to_run[1]:
+                anonymous_tasks.append(asyncio.create_task(
+                    action.run(spinners.create_task(action.get_name()))))
+            # Start drawing the spinners
+            spinner_task = asyncio.create_task(spinners.spin())
+            # Now wait for them all to resolve
+            results: dict[str, Any] = {}
+            task_errors: list[Exception] = []
+            for key, task in named_tasks.items():
+                try:
+                    results[key] = await task
+                except Exception as e:
+                    task_errors.append(e)
+            for task in anonymous_tasks:
+                try:
+                    await task
+                except Exception as e:
+                    task_errors.append(e)
+
+            # Cancel the spinner task
+            spinner_task.cancel()
+
+            if len(task_errors):
+                raise ExceptionGroup(
+                    f"Task failed on step {i + 1}",
+                    task_errors,
+                )
+
+            # Now merge the results with the params
+            params |= results
+
+        # Now perform the teardown
+        for named_actions, anonymous_actions in reversed(actions_by_step):
+            for action in named_actions.values():
+                await action.cleanup()
+            for action in anonymous_actions:
+                await action.cleanup()
+
+
+def show_current_params(params: Mapping[str, Any]):
+    """
+    Displays the current params to the user.
+    """
+    print()
+    print("Running recipe with given parameters:")
+    for param_name, param_value in params.items():
+        print(f"  {param_name} = {param_value}")
+    print()
+
+
+def generate_actions_for_step(
+    step: ActionStep,
+    params: Mapping[str, Any],
+) -> GeneratedActionStep:
+    """
+    Given a step, generate the actions
+    """
+    if isinstance(step, tuple):
+        result: GeneratedActionStep = ({}, [])
+        for step_item in step:
+            # Use recursion so that we can simplify the handling of multiple
+            # steps
+            result = union_generated_action_step_items(
+                result,
+                generate_actions_for_step(step_item, params)
+            )
+        return result
+    elif isinstance(step, MarkTenAction):
+        # Single anonymous action
+        return ({}, [step])
+    elif isinstance(step, Mapping):
+        # Collection of named actions
+        return (dict(step), [])
+    else:
+        # step is an ActionGenerator function
+        action_fn_output = execute_action_function(step, params)
+        # Parse the result recursively
+        return generate_actions_for_step(action_fn_output, params)
+
+
+def union_generated_action_step_items(
+    a: GeneratedActionStep,
+    b: GeneratedActionStep,
+) -> GeneratedActionStep:
+    """
+    Union a and b.
+    """
+    named_actions = a[0] | b[0]
+    anonymous_actions = a[1] + b[1]
+    return named_actions, anonymous_actions
+
+
+def execute_action_function(
+    fn: ActionGenerator,
+    params: Mapping[str, Any],
+) -> ActionStep:
+    """
+    Execute an action generator function, ensuring only the desired parameters
+    are passed as kwargs.
+    """
+    args = inspect.getfullargspec(fn)
+    kwargs_used = args[2] is not None
+    if kwargs_used:
+        return fn(**params)
+    else:
+        # Only pass the args used
+        named_args = args[0]
+        param_subset = {k: v for k, v in params.items() if k in named_args}
+        return fn(**param_subset)

markten/__spinners.py

@@ -0,0 +1,236 @@
+"""
+# MarkTen / Spinner
+
+Class for displaying multiple parallel spinners.
+
+This is used to report the progress of tasks that run simultaneously.
+"""
+import asyncio
+from enum import Enum
+from . import __term_tools as term
+from .__term_tools import print_clear
+
+
+SPIN_FRAMES = "|/-\\"
+"""
+Spin states to draw
+"""
+SPIN_FRAME_LENGTH = 0.25
+"""
+How often to redraw the spinners
+"""
+
+
+def get_frame(i: int) -> str:
+    """Returns frame number for spinner animation"""
+    return SPIN_FRAMES[i % len(SPIN_FRAMES)]
+
+
+class TaskStatus(Enum):
+    """Status of a task"""
+    Setup = 0
+    """Task is being set up"""
+    Running = 1
+    """Task is running"""
+    Success = 2
+    """Task resolved successfully"""
+    Failure = 3
+    """Task resolved, but failed"""
+
+
+class SpinnerTask:
+    """
+    A single task that is associated with a spinner.
+    """
+
+    def __init__(self, spinners: 'SpinnerManager', name: str) -> None:
+        """
+        Create a spinner task.
+
+        This should only be called by the `SpinnerManager`, which gives a
+        reference to `self`. Use `spinners.create_task(task_name)` instead.
+
+        Args:
+            spinners (SpinnerManager): spinner manager
+            name (str): name of the task
+        """
+        self.__spinners = spinners
+        self.__status = TaskStatus.Setup
+        self.__name = name
+        self.__message: str | None = None
+        self.__logs: list[str] = []
+
+    def log(self, line: str) -> None:
+        """
+        Add message to the task logs.
+        """
+        self.__logs.append(line.strip())
+        self.__spinners.draw_frame()
+
+    def message(self, msg: str | None) -> None:
+        """
+        Set the overall status message of the task.
+        """
+        self.__message = msg
+        self.__spinners.draw_frame()
+
+    def running(self, msg: str | None = None) -> None:
+        """
+        Set the task status as `Running`
+        """
+        self.__status = TaskStatus.Running
+        self.message(msg)
+
+    def succeed(self, msg: str | None = None) -> None:
+        """
+        Set the task status as `Success`
+        """
+        self.__status = TaskStatus.Success
+        self.message(msg)
+
+    def fail(self, msg: str | None = None) -> None:
+        """
+        Set the task status as `Failure`
+        """
+        self.__status = TaskStatus.Failure
+        self.message(msg)
+
+    def is_resolved(self) -> bool:
+        """
+        Returns whether the task has resolved, meaning it finished
+        successfully, or that it failed.
+        """
+        return self.__status in [TaskStatus.Success, TaskStatus.Failure]
+
+    def display(self, i: int) -> list[str]:
+        """
+        Return the lines used to display the spinner's state.
+        """
+        result: list[str] = []
+        msg = f" -- {self.__message}" if self.__message else ""
+        match self.__status:
+            case TaskStatus.Setup:
+                result.append(f"⏳  {get_frame(i)} {self.__name} {msg}")
+            case TaskStatus.Running:
+                result.append(f"⏱️  {get_frame(i)} {self.__name} {msg}")
+            case TaskStatus.Success:
+                result.append(f"✅   {self.__name} {msg}")
+            case TaskStatus.Failure:
+                result.append(f"❌   {self.__name} {msg}")
+
+        for line in self.__logs:
+            result.append(f"  |  {line}")
+        # result.append(" output length:", len(self.__logs))
+        return result
+
+
+class SpinnerManager:
+    """
+    A manager for running spinners.
+
+    Only one spinner manager should be running at once.
+
+    Usage:
+
+        spinners = SpinnerManager("Some complex task")
+        task1 = spinners.create_task("One parallel action")
+        task2 = spinners.create_task("Another action")
+        spinner_task = asyncio.create_task(spinners.spin())
+
+        # Do work...
+
+        spinner_task.cancel()
+    """
+
+    def __init__(self, name: str) -> None:
+        """
+        Create a spinner manager.
+
+        Args:
+            name (str): name of spinner manager (name of step being executed)
+        """
+        self.__name = name
+        """Name of spinner"""
+        self.__task_list: list[SpinnerTask] = []
+        """List of tasks, as they appear while rendering"""
+        # self.__start_line_num = term.get_position()[0]
+        # """Starting line of the output"""
+        term.save_cursor()
+
+    def create_task(self, name: str) -> SpinnerTask:
+        """
+        Create a task to be displayed by the spinner.
+
+        Args:
+            name (str): name of the task being executed within the step.
+        """
+        task = SpinnerTask(self, name)
+        self.__task_list.append(task)
+        self.__frame = 0
+        return task
+
+    def __count_complete(self) -> int:
+        """Returns the number of completed tasks"""
+        return len(list(filter(
+            lambda task: task.is_resolved(),
+            self.__task_list
+        )))
+
+    async def spin(self) -> None:
+        """
+        Begin the spin task.
+
+        This will run infinitely, until the task is cancelled.
+        """
+        # Move the cursor to the starting position
+        while True:
+            self.__frame += 1
+            self.draw_frame()
+            # Wait for the frame duration
+            await asyncio.sleep(SPIN_FRAME_LENGTH)
+
+    def draw_frame(self):
+        """
+        Draw a frame of the spinners.
+
+        This currently redraws all output, which isn't especially efficient.
+
+        Most of the commented code relies on getting and setting the terminal
+        cursor position manually, which appears to break when the number of
+        lines in the terminal is too small (causing text to be printed multiple
+        times).
+
+        Since it's impossible to jump to a negative cursor position manually,
+        we rely on the save/restore cursor functionality, since at least it
+        only massively breaks if the terminal size is extremely tiny, and works
+        reasonably well otherwise.
+
+        I need to find a library that handles all of the terminal outputting so
+        I can get nice outputs that update in multiple places without causing
+        major headaches and console spamming, but that is a future Maddy
+        problem.
+        """
+        term.restore_cursor()
+        # term_size = os.get_terminal_size()
+        # term.set_position((self.__start_line_num, 0))
+        completed_tasks = self.__count_complete()
+
+        output = [f"{self.__name} ({completed_tasks}/{len(self.__task_list)})"]
+
+        # Draw the spinners
+        for task in self.__task_list:
+            output.extend(task.display(self.__frame))
+
+        for line in output:
+            print_clear(line)
+
+        # # Determine the number of lines used, including wrapping
+        # lines_used = 0
+        # for line in output:
+        #     lines_used += math.ceil(wcswidth(line) / term_size.columns)
+        #
+        # # If we exceeded the number of lines in the terminal
+        # if self.__start_line_num + lines_used > term_size.lines:
+        #     # We must update the cursor position to instead be negative,
+        #     # based on the new scroll position
+        #     self.__start_line_num = term_size.lines - lines_used

markten/__term_tools.py

@@ -0,0 +1,97 @@
+"""
+# MarkTen / term tools
+
+Simple functions to handle terminal output.
+"""
+import sys
+
+
+if sys.platform == "win32":
+    def getch():
+        """
+        Getch on Windows.
+
+        https://stackoverflow.com/a/3523340/6335363
+        """
+        import msvcrt
+        return msvcrt.getch()
+else:
+    def getch():
+        """
+        Getch on unix systems.
+
+        https://stackoverflow.com/a/72825322/6335363
+        """
+        import termios
+        import tty
+        fd = sys.stdin.fileno()
+        orig = termios.tcgetattr(fd)
+
+        try:
+            # or tty.setraw(fd) if you prefer raw mode's behavior.
+            tty.setcbreak(fd)
+            return sys.stdin.read(1)
+        finally:
+            termios.tcsetattr(fd, termios.TCSAFLUSH, orig)
+
+
+def get_position() -> tuple[int, int]:
+    """
+    Returns the position in the terminal, as `(row, col)`.
+
+    https://stackoverflow.com/a/8353312/6335363
+    """
+    print("\033[6n", end='', flush=True)
+    assert getch() == "\033"
+    assert getch() == "["
+
+    row = ''
+    while (ch := getch()) != ';':
+        row += ch
+    col = ''
+    while (ch := getch()) != 'R':
+        col += ch
+
+    return int(row), int(col)
+
+
+def set_position(pos: tuple[int, int]) -> None:
+    """
+    Set the terminal position to the given state.
+
+    https://stackoverflow.com/a/54630943/6335363
+    """
+    r, c = pos
+    print(f"\033[{r};{c}H", end='', flush=True)
+
+
+def save_cursor():
+    """Instruct the terminal to save the current cursor position."""
+    print('\0337', end='', flush=True)
+
+
+def restore_cursor():
+    """Instruct the terminal to restore the saved cursor position."""
+    print('\0338', end='', flush=True)
+
+
+def clear_line():
+    """
+    Clear the current line of output.
+    """
+    print('\033[2K', end='', flush=True)
+
+
+def print_clear(*args: object, **kwargs):
+    """
+    Print text after clearing the current line.
+    """
+    clear_line()
+    print(*args, **kwargs)
+
+
+if __name__ == '__main__':
+    # Simple test program
+    # print("\n" * 100)
+    set_position((-10, 0))
+    print("What about now?\n" * 10)