markten 0.1.0__tar.gz

markten-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 COMP1010 UNSW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markten-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.1
+Name: markten
+Version: 0.1.0
+Summary: A framework for automating the process of manual marking in bulk
+License: MIT
+Author: Maddy Guthridge
+Author-email: hello@maddyguthridge.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+
+# MarkTen
+
+Assess your students' work with all of the delight and none of the tedium.
+
+## Installing
+
+```bash
+$ pip install markten
+...
+Successfully installed markten-0.1.0
+```
+
+Or to install in an independent environment, you can use `pipx`:
+
+```bash
+$ pipx install markten
+  installed package markten 0.1.0, installed using Python 3.12.6
+  These apps are now globally available
+    - markten
+done! ✨ 🌟 ✨
+```
+
+## How it works
+
+Define your recipe parameters. For example, this recipe takes in git repo names
+from stdin.
+
+```py
+from markten import Recipe, parameters, actions
+
+marker = Recipe("COMP2511 Lab Marking")
+
+marker.parameter("repo", parameters.stdin("Repo name"))
+```
+
+Write simple marking recipes by defining simple functions for each step.
+
+```py
+# Functions can take arbitrary parameters
+def setup(repo: str):
+    """Set up marking environment"""
+    # Clone the given git repo to a temporary directory
+    directory = actions.git.clone(f"git@github.com:COMP1010UNSW/{repo}.git")
+    return {
+        "directory": directory,
+    }
+
+marker.step("Clone repo", setup)
+```
+
+The parameters returned by your previous steps can be used in later steps, just
+by giving the function parameters the same name.
+
+```py
+def open_code(directory: Path):
+    """Open the cloned git repo in VS Code"""
+    return actions.editor.vs_code(directory)
+
+marker.step("View in VS Code", open_code)
+```
+
+Then run the recipe. It'll run for every permutation of your parameters, making
+it easy to mark in bulk.
+
+```py
+marker.run()
+```
+
+For more examples, see the examples directory.
+

markten-0.1.0/README.md

@@ -0,0 +1,69 @@
+# MarkTen
+
+Assess your students' work with all of the delight and none of the tedium.
+
+## Installing
+
+```bash
+$ pip install markten
+...
+Successfully installed markten-0.1.0
+```
+
+Or to install in an independent environment, you can use `pipx`:
+
+```bash
+$ pipx install markten
+  installed package markten 0.1.0, installed using Python 3.12.6
+  These apps are now globally available
+    - markten
+done! ✨ 🌟 ✨
+```
+
+## How it works
+
+Define your recipe parameters. For example, this recipe takes in git repo names
+from stdin.
+
+```py
+from markten import Recipe, parameters, actions
+
+marker = Recipe("COMP2511 Lab Marking")
+
+marker.parameter("repo", parameters.stdin("Repo name"))
+```
+
+Write simple marking recipes by defining simple functions for each step.
+
+```py
+# Functions can take arbitrary parameters
+def setup(repo: str):
+    """Set up marking environment"""
+    # Clone the given git repo to a temporary directory
+    directory = actions.git.clone(f"git@github.com:COMP1010UNSW/{repo}.git")
+    return {
+        "directory": directory,
+    }
+
+marker.step("Clone repo", setup)
+```
+
+The parameters returned by your previous steps can be used in later steps, just
+by giving the function parameters the same name.
+
+```py
+def open_code(directory: Path):
+    """Open the cloned git repo in VS Code"""
+    return actions.editor.vs_code(directory)
+
+marker.step("View in VS Code", open_code)
+```
+
+Then run the recipe. It'll run for every permutation of your parameters, making
+it easy to mark in bulk.
+
+```py
+marker.run()
+```
+
+For more examples, see the examples directory.

markten-0.1.0/markten/__consts.py

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

markten-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-0.1.0/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-0.1.0/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-0.1.0/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)