git-autograder v3

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt -U --no-cache-dir
+      - name: Run unit tests
+        run: |
+          python -m pytest -s -vv

README.md

@@ -12,33 +12,16 @@ pip install git-autograder
 
 `GitAutograderRepo` initializes and reads the submission repository. It contains critical information for autograding such as the start commit (denoted by `git-mastery-start-<first commit short hash>`) and user's commits.
 
-For basic usage, you can either initialize the `GitAutograderRepo` by declaring it as a variable:
+For basic usage:
 
 ```py
-from git_autograder.repo import GitAutograderRepo
-
-def grade():
-  repo = GitAutograderRepo()
-  ...
-```
-
-Or by decorating the grading function with `@autograder()` where the `GitAutograderRepo` initialization is handled by the decorator:
-
-```py
-from git_autograder.autograder import autograder
+from git_autograder import autograder, GitAutograderOutput, GitAutograderRepo
 
 @autograder()
-def grade(repo: GitAutograderRepo):
+def grade(repo: GitAutograderRepo) -> GitAutograderOuput:
   ...
 ```
 
-`GitAutograderDiffHelper` is a wrapper around the `git diff` between commits:
-
-```py
-from git_autograder.diff import GitAutograderDiffHelper
-
-GitAutograderDiffHelper(commit_a, commit_b)
-```
 
 ## Unit tests
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "git-autograder"
-version = "2.5.0"
+version = "3.0.0"
 authors = [{ name = "Jiahao, Woo", email = "[email protected]" }]
 description = "Library for autograding Git repositories"
 readme = "README.md"
@@ -26,3 +26,6 @@ Issues = "https://github.com/git-mastery/git-autograder/issues"
 [tool.pytest.ini_options]
 addopts = ["--import-mode=importlib"]
 pythonpath = ["src"]
+
+[tool.mypy]
+mypy_path = "src"

src/git_autograder/__init__.py

@@ -0,0 +1,27 @@
+__all__ = [
+    "autograder",
+    "setup_autograder",
+    "set_env",
+    "assert_output",
+    "GitAutograderTestLoader",
+    "GitAutograderRepo",
+    "GitAutograderStatus",
+    "GitAutograderOutput",
+    "GitAutograderBranch",
+    "GitAutograderRemote",
+    "GitAutograderCommit",
+]
+
+from .status import GitAutograderStatus
+from .output import GitAutograderOutput
+from .repo import GitAutograderRepo
+from .commit import GitAutograderCommit
+from .branch import GitAutograderBranch
+from .remote import GitAutograderRemote
+from .decorators import autograder
+from .test_utils import (
+    setup_autograder,
+    set_env,
+    assert_output,
+    GitAutograderTestLoader,
+)

src/git_autograder/answers/__init__.py

@@ -0,0 +1,4 @@
+__all__ = ["GitAutograderAnswersRecord", "GitAutograderAnswers"]
+
+from .answers_record import GitAutograderAnswersRecord
+from .answers import GitAutograderAnswers

src/git_autograder/answers/answers.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from git_autograder.answers.answers_record import GitAutograderAnswersRecord
+from git_autograder.answers.rules.answer_rule import AnswerRule
+from git_autograder.exception import (
+    GitAutograderInvalidStateException,
+    GitAutograderWrongAnswerException,
+)
+
+
+@dataclass
+class GitAutograderAnswers:
+    MISSING_QUESTION = "Missing question {question} in answers file."
+
+    questions: List[str]
+    answers: List[str]
+
+    @property
+    def qna(self) -> List[GitAutograderAnswersRecord]:
+        return list(
+            map(
+                lambda a: GitAutograderAnswersRecord.from_tuple(a),
+                zip(self.questions, self.answers),
+            )
+        )
+
+    def __getitem__(self, key: int) -> GitAutograderAnswersRecord:
+        question = self.questions[key]
+        answer = self.answers[key]
+        return GitAutograderAnswersRecord.from_tuple((question, answer))
+
+    def __len__(self) -> int:
+        return len(self.questions)
+
+    def question_or_none(self, question: str) -> Optional[GitAutograderAnswersRecord]:
+        """
+        Retrieves the record given a question.
+
+        :returns: GitAutograderAnswersRecord if present, else None.
+        :rtype: Optional[GitAutograderAnswersRecord]
+        :raises GitAutograderInvalidStateException: if question is not present.
+        """
+        for i, q in enumerate(self.questions):
+            if question == q:
+                return GitAutograderAnswersRecord.from_tuple((q, self.answers[i]))
+        return None
+
+    def question(self, question: str) -> GitAutograderAnswersRecord:
+        """
+        Retrieves the record given a question.
+
+        :returns: GitAutograderAnswersRecord if present.
+        :rtype: GitAutograderAnswersRecord
+        :raises GitAutograderInvalidStateException: if question is not present.
+        """
+        record = self.question_or_none(question)
+        if record is None:
+            raise GitAutograderInvalidStateException(
+                self.MISSING_QUESTION.format(question=question)
+            )
+        return record
+
+    def validate_question(
+        self, question: str, rules: List[AnswerRule]
+    ) -> "GitAutograderAnswers":
+        """
+        Validates that a given GitAutograderAnswersRecord passes a set of rules.
+
+        :raises GitAutograderWrongAnswerException: when a rule is violated.
+        """
+        q = self.question(question)
+
+        for rule in rules:
+            try:
+                rule.apply(q)
+            except Exception as e:
+                raise GitAutograderWrongAnswerException([str(e)])
+
+        return self

src/git_autograder/answers/answers_parser.py

@@ -0,0 +1,64 @@
+import os
+from io import TextIOWrapper
+from typing import List
+
+from git_autograder.answers.answers import GitAutograderAnswers
+
+
+class GitAutograderAnswersParser:
+    def __init__(self, path: str | os.PathLike[str]) -> None:
+        if not os.path.isfile(path):
+            raise Exception("Missing answers.txt file from repository.")
+
+        with open(path, "r") as file:
+            self.answers: GitAutograderAnswers = self.__parse(file)
+
+    def __parse(self, file: TextIOWrapper) -> GitAutograderAnswers:
+        questions: List[str] = []
+        answers: List[str] = []
+        acc_lines: List[str] = []
+        flag = 0  # 0 -> looking for question, 1 -> looking for answer
+        for line in file.readlines():
+            line = line.strip()
+            if line.lower().startswith("q:") or line.lower().startswith("a:"):
+                if flag == 0:
+                    # If we were waiting for a question and found it, the previous would have been an answer
+                    if len(acc_lines) != 0:
+                        answers.append(self.__preserve_whitespace_join(acc_lines))
+                else:
+                    # If we were waiting for an answer and found it, the previous would have been a question
+                    if len(acc_lines) != 0:
+                        questions.append(self.__preserve_whitespace_join(acc_lines))
+                acc_lines = [line[2:].strip()]
+                # Once a question/answer is found, we switch the flag around to wait for the next thing
+                flag = 1 - flag
+            else:
+                acc_lines.append(line)
+
+        if len(acc_lines) != 0:
+            if flag == 0:
+                answers.append(self.__preserve_whitespace_join(acc_lines))
+            else:
+                questions.append(self.__preserve_whitespace_join(acc_lines))
+
+        if len(questions) != len(answers):
+            raise Exception(
+                "Invalid answers format: missing question(s) or answer(s) or both"
+            )
+
+        return GitAutograderAnswers(questions=questions, answers=answers)
+
+    def __preserve_whitespace_join(
+        self, lines: List[str], delimiter: str = "\n"
+    ) -> str:
+        res = []
+        blank_count = 0
+        for line in lines:
+            if line == "":
+                blank_count += 1
+                if blank_count > 1:
+                    res.append(line)
+            else:
+                blank_count = 0
+                res.append(line)
+        return delimiter.join(res).strip()

src/git_autograder/answers/answers_record.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from typing import List, Tuple
+
+
+@dataclass
+class GitAutograderAnswersRecord:
+    question: str
+    answer: str
+
+    def as_tuple(self) -> Tuple[str, str]:
+        return self.question, self.answer
+
+    @staticmethod
+    def from_tuple(tuple_value: Tuple[str, str]) -> "GitAutograderAnswersRecord":
+        return GitAutograderAnswersRecord(
+            question=tuple_value[0], answer=tuple_value[1]
+        )
+
+    def answer_as_list(self) -> List[str]:
+        points: List[str] = []
+        acc = ""
+        for line in self.answer.split("\n"):
+            if line.startswith("-"):
+                if acc.strip() != "":
+                    points.append(acc.strip()[::])
+                acc = line[1:].strip() + "\n"
+            else:
+                acc += line + "\n"
+        if acc.strip() != "":
+            points.append(acc.strip()[::])
+        return points

src/git_autograder/answers/rules/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "AnswerRule",
+    "HasExactValueRule",
+    "NotEmptyRule",
+    "HasExactListRule",
+    "ContainsListRule",
+]
+
+from .answer_rule import AnswerRule
+from .has_exact_value_rule import HasExactValueRule
+from .not_empty_rule import NotEmptyRule
+from .has_exact_list_rule import HasExactListRule
+from .contains_list_rule import ContainsListRule

src/git_autograder/answers/rules/answer_rule.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+from git_autograder.answers.answers_record import GitAutograderAnswersRecord
+
+
+class AnswerRule(ABC):
+    @abstractmethod
+    def apply(self, answer: GitAutograderAnswersRecord) -> None: ...

src/git_autograder/answers/rules/contains_list_rule.py

@@ -0,0 +1,30 @@
+from typing import List
+
+from git_autograder.answers.answers_record import GitAutograderAnswersRecord
+from git_autograder.answers.rules.answer_rule import AnswerRule
+
+
+class ContainsListRule(AnswerRule):
+    INVALID_ITEM = "Answer for {question} contains an invalid item."
+    ALL_INVALID = "Answer for {question} does not contain any valid items."
+
+    def __init__(
+        self, values: List[str], subset: bool = True, is_case_sensitive: bool = False
+    ) -> None:
+        self.values = values
+        self.subset = subset
+        self.is_case_sensitive = is_case_sensitive
+
+    def apply(self, answer: GitAutograderAnswersRecord) -> None:
+        expected = set(
+            [v.lower() for v in self.values] if self.is_case_sensitive else self.values
+        )
+        given = (
+            [v.lower() for v in answer.answer_as_list()]
+            if self.is_case_sensitive
+            else answer.answer_as_list()
+        )
+        if self.subset and not all([v in expected for v in given]):
+            raise Exception(self.INVALID_ITEM.format(question=answer.question))
+        elif not any([v in expected for v in given]):
+            raise Exception(self.ALL_INVALID.format(question=answer.question))

src/git_autograder/answers/rules/contains_value_rule.py

@@ -0,0 +1,16 @@
+from git_autograder.answers.answers_record import GitAutograderAnswersRecord
+from git_autograder.answers.rules.answer_rule import AnswerRule
+
+
+class ContainsValueRule(AnswerRule):
+    MISSING_ANSWER = "Answer for {question} does not contain the right answer."
+
+    def __init__(self, value: str, is_case_sensitive: bool = False) -> None:
+        self.value = value
+        self.is_case_sensitive = is_case_sensitive
+
+    def apply(self, answer: GitAutograderAnswersRecord) -> None:
+        expected = self.value.lower() if self.is_case_sensitive else self.value
+        given = answer.answer.lower() if self.is_case_sensitive else answer.answer
+        if given not in expected:
+            raise Exception(self.MISSING_ANSWER.format(question=answer.question))

src/git_autograder/answers/rules/has_exact_list_rule.py

@@ -0,0 +1,32 @@
+from typing import List
+
+from git_autograder.answers.answers_record import GitAutograderAnswersRecord
+from git_autograder.answers.rules.answer_rule import AnswerRule
+
+
+class HasExactListRule(AnswerRule):
+    INCORRECT_ORDERED = "Answer for {question} does not contian all of the right answers. Ensure that they follow the order specified."
+    INCORRECT_UNORDERED = (
+        "Answer for {question} does not contain all of the right answers."
+    )
+
+    def __init__(
+        self, values: List[str], ordered: bool = False, is_case_sensitive: bool = False
+    ) -> None:
+        self.values = values
+        self.ordered = ordered
+        self.is_case_sensitive = is_case_sensitive
+
+    def apply(self, answer: GitAutograderAnswersRecord) -> None:
+        expected = (
+            [v.lower() for v in self.values] if self.is_case_sensitive else self.values
+        )
+        given = (
+            [v.lower() for v in answer.answer_as_list()]
+            if self.is_case_sensitive
+            else answer.answer_as_list()
+        )
+        if self.ordered and expected != given:
+            raise Exception(self.INCORRECT_ORDERED.format(question=answer.question))
+        elif set(expected).intersection(set(given)) != len(expected):
+            raise Exception(self.INCORRECT_UNORDERED.format(question=answer.question))