feat: add util functions, fix pypi deployment

Add sanity checks.

Author: krerkkiat

CHANGELOG.md

@@ -2,12 +2,19 @@
 
 ## Unreleased
 
+- Add `ensure_lf_line_ending`.
+- Account for the different of `tempfile.TemporaryDirectory` between 3.12 and 3.10.
+- Add `BaseTestCase.assertArchiveFileIsGzip`
+- Add sanity checks to `Repository` wheh working with `.tar.gz` file.
+- Add `Repository.run_executable` where `cwd` is always set to working directory of the repository.
+- Remove extra dependencies `doc` since we cannot list Git repository as a dependency and upload to PyPI.
+
 ## v0.1.1a1
 
 - (docs) Switch to manual API listing.
 - (docs) Pin `sphinx-autodoc2` to our own fork before its [#17](https://github.com/sphinx-extensions2/sphinx-autodoc2/issues/17) is fixed.
 - Add timeout to `run_executable` since some commands may require human's input and get stuck.
-- Add `grading.repository.RepositoryBaseTestCase`.
+- Add `grading_lib.repository.RepositoryBaseTestCase`.
 - Add `Repository.get_all_tag_refs`.
 - Add `Repository.get_tag_refs_at`.
 - Fix `Repository` from an archive file is using the archive's filename instead of the "repo".

README.md

@@ -15,7 +15,7 @@ python -m pip install cs3560-grading-lib
 
 ## Documentation
 
-View the [latest documentation](https://grading-lib.readthedocs.io/en/latest/)
+View the [latest documentation](https://grading-lib.readthedocs.io/en/latest/) or the documentation for the [stable version](https://grading-lib.readthedocs.io/en/stable/).
 
 ## Similar Projects / More Mature Projects
 

docs/README.md

@@ -1,8 +1,10 @@
 # Documentation
 
-Ensure that the package is installed with `.[doc]` extra dependencies. To build
-this documentation, run
-
 ```console
+python -m pip install -r ./requirements.txt
 make html
 ```
+
+## About our sphinx-autodoc2
+
+The sphinx-autodoc2 does not fix [issue #17](https://github.com/sphinx-extensions2/sphinx-autodoc2/issues/17) yet, but PyPI does not allow direct Github repository as a dependencies.

grading_lib/common.py

@@ -1,7 +1,7 @@
 import datetime
-import functools
 import os
 import subprocess
+import sys
 import tempfile
 import time
 import unittest
@@ -98,6 +98,16 @@ def run_executable(
         return CommandResult(False, " ".join(args), e.output.decode())
 
 
+def ensure_lf_line_ending(path: Path | str) -> CommandResult:
+    """Run dos2unix on the file at path.
+
+    Students who are using Windows OS may submit answer.sh that has CRLF as its line
+    ending. The CR will ofen get mixed into shell commands in the file and produces
+    strange result / error.
+    """
+    return run_executable(["dos2unix", str(path)])
+
+
 class MinimalistTestResult(unittest.TextTestResult):
     """TextTestResult without the traceback.
 
@@ -150,12 +160,31 @@ def setUp(self) -> None:
 
         self.temporary_dir = None
         if self.with_temporary_dir:
-            self.temporary_dir = tempfile.TemporaryDirectory(dir=Path("."))
+            if sys.version_info < (3, 12, 0):
+                self.temporary_dir = tempfile.TemporaryDirectory(dir=Path("."))
+            else:
+                self.temporary_dir = tempfile.TemporaryDirectory(
+                    dir=Path("."), delete=False
+                )
             self.temporary_dir_path = Path(self.temporary_dir.name)
 
     def tearDown(self) -> None:
         if not self.is_debug_mode and self.temporary_dir is not None:
             self.temporary_dir.cleanup()
+        elif self.is_debug_mode and self.temporary_dir is not None:
+            print(
+                f"[info]: The temporary directory at '{self.temporary_dir_path}' is not deleted since the DEBUG is set to True."
+            )
+
+    def assertArchiveFileIsGzip(self, path: Path):
+        cmd_result = run_executable(["gunzip", "-t", str(path)])
+        self.assertTrue(
+            "not in gzip format" not in cmd_result.output,
+            msg="Hint: Did you forget to use '-z' flag when creating the archive?",
+        )
+        self.assertCommandSuccessful(
+            cmd_result,
+        )
 
     def assertFileExists(
         self, path: Path, msg_template: str = FILE_NOT_EXIST_TEXT_TEMPLATE

grading_lib/repository.py

@@ -1,5 +1,6 @@
 import shutil
 import subprocess
+import sys
 import tempfile
 import uuid
 from pathlib import Path
@@ -9,7 +10,7 @@
 from git.repo.fun import is_git_dir
 from git.util import IterableList
 
-from .common import BaseTestCase
+from .common import BaseTestCase, CommandResult, run_executable
 
 
 class Repository:
@@ -30,7 +31,10 @@ def __init__(self, path: str | Path, *args, **kwargs):
             path = Path(path)
 
         if "".join(path.suffixes) == ".tar.gz":
-            self.temp_dir = tempfile.TemporaryDirectory(delete=False)
+            if sys.version_info < (3, 12, 0):
+                self.temp_dir = tempfile.TemporaryDirectory()
+            else:
+                self.temp_dir = tempfile.TemporaryDirectory(delete=False)
             temp_dir_path = Path(self.temp_dir.name)
             shutil.copy(path, temp_dir_path / path.name)
             subprocess.run(
@@ -40,6 +44,15 @@ def __init__(self, path: str | Path, *args, **kwargs):
             # We are not trying to find out what the root folder in the archive file is.
             # We do not create an archive file that does not have the root folder because
             # whens student extract the archive file, files will be everywhere.
+            if not (temp_dir_path / "repo").exists():
+                raise FileNotFoundError(
+                    f"Expect the archive to have folder 'repo', but this 'repo' folder cannot be found after extracting '{path.name}'"
+                )
+            if not (temp_dir_path / "repo" / ".git").exists():
+                raise FileNotFoundError(
+                    f"Expect the 'repo' to be a Git repository (it must have .git folder), but '.git' is missing from the 'repo' extracted from '{path.name}'"
+                )
+
             self.repo = Repo(temp_dir_path / "repo", *args, **kwargs)
         else:
             if is_git_dir(path):
@@ -87,6 +100,12 @@ def to_gzip_archive(self, path: Path) -> None:
             ]
         )
 
+    def run_executable(self, args: list[str], timeout: float = 15.0) -> CommandResult:
+        """
+        Run a command using repostiory's working directory as cwd.
+        """
+        return run_executable(args, cwd=self.repo.working_tree_dir, timeout=timeout)
+
     def create_and_add_random_file(
         self, name: str | None = None, content: str | None = None
     ) -> str:
@@ -139,6 +158,13 @@ def get_tag_refs_at(self, commit_hash: str) -> list[Tag]:
                 matched_tag_refs.append(tag_ref)
         return matched_tag_refs
 
+    def visualize(self) -> str:
+        """
+        Run 'git log --oneline --all --graph --decorate' and returns the output.
+        """
+        res = self.repo.git.log("--graph", "--all", "--decorate", "--oneline")
+        return res
+
 
 class RepositoryBaseTestCase(BaseTestCase):
     def assertHasTagWithNameAt(self, repo: Repository, name: str, commit_hash: str):
@@ -148,8 +174,9 @@ def assertHasTagWithNameAt(self, repo: Repository, name: str, commit_hash: str):
             if tag_ref.path == tag_path:
                 return
 
+        tags_text = "\n".join(tag_ref.path for tag_ref in tag_refs)
         raise self.failureException(
-            f"Expect to see a tag '{name}' at commit '{commit_hash}', but found none."
+            f"Expect to see a tag '{name}' at commit '{commit_hash}', but found none. Tags at commit {commit_hash}:\n{tags_text}"
         )
 
     def assertHasTagWithNameAndMessageAt(
@@ -166,6 +193,14 @@ def assertHasTagWithNameAndMessageAt(
             ):
                 return
 
+        tags_texts = []
+        for tag_ref in tag_refs:
+            if tag_ref.tag is None:
+                text = f"{tag_ref.path}"
+            else:
+                text = f"{tag_ref.path}: {tag_ref.tag.message}"
+            tags_texts.append(text)
+        tags_text = "\n".join(tags_texts)
         raise self.failureException(
-            f"Expect to see a tag '{name}' with message '{message}' at commit '{commit_hash}', but found none."
+            f"Expect to see a tag '{name}' with message '{message}' at commit '{commit_hash}', but found none. Tags at commit {commit_hash}:\n{tags_text}"
         )

pyproject.toml

@@ -26,7 +26,6 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest", "pytest-cov", "mypy", "ruff", "tox"]
-doc = ["sphinx", "myst-parser", "sphinx-book-theme", "sphinx-autodoc2@git+https://github.com/krerkkiat/sphinx-autodoc2.git@krerkkiat/fix-17"]
 
 [project.urls]
 Documentation = "https://grading-lib.readthedocs.io/en/latest/"