ask-ta 0.2.3__py3-none-any.whl

ask_ta/__init__.py

@@ -0,0 +1,31 @@
+"""Ask TA: a study assistant for the Foundations of Data Science course at UZH.
+
+Exposes the public package metadata used by the app and its HTTP surface:
+
+- :data:`__app_name__`: package name (from installed metadata).
+- :data:`__version__`: package version (from installed metadata).
+- :data:`__commit_sha__`: short git commit SHA, derived from the local
+  version segment of the package version string.
+
+``hatch-vcs`` embeds the commit SHA in the PEP 440 local-version segment of
+the version string on every build (editable, sdist, wheel). For example,
+``"0.1.dev75+g304d82007.d20260417"`` contains ``g304d82007`` where
+``304d82007`` is the short SHA. Tagged releases at the tag's exact commit
+have no local segment and resolve to ``unknown``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import metadata
+
+__all__ = ["__app_name__", "__commit_sha__", "__version__"]
+
+_meta = metadata(__name__)
+__app_name__: str = _meta["Name"]
+__version__: str = _meta["Version"]
+
+__commit_sha__: str = "unknown"
+if "+" in __version__:
+    _local = __version__.split("+", 1)[1]
+    if _local.startswith("g"):
+        __commit_sha__ = _local.split(".", 1)[0][1:]

ask_ta/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
+
+__commit_id__ = commit_id = None

ask_ta/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Infrastructure adapters: concrete implementations of domain ports."""
+
+from __future__ import annotations

ask_ta/adapters/bundle/__init__.py

@@ -0,0 +1,5 @@
+"""Filesystem adapters behind the :mod:`ask_ta.domain.bundle` ports: readers
+for archives and directories (`archive`) and the versioned bundle store
+(`store`). Composition wires them to the installer in ``main.py``."""
+
+from __future__ import annotations

ask_ta/adapters/bundle/archive.py

@@ -0,0 +1,296 @@
+"""Bundle-source readers: magic-byte sniffing, tar streaming, directory walk.
+
+Implements the domain's :class:`~ask_ta.domain.bundle.ArchiveOpener` and
+:class:`~ask_ta.domain.bundle.ArchiveReader` ports. Magic bytes decide the
+format and the extension is ignored. A gzip file (``1f 8b``) is gunzipped and
+untarred, and a bare ``ustar`` tar is tolerated, since Safari's "Open safe
+files" gunzips downloads. A directory is walked, which covers a Safari
+auto-expanded download and a CLI folder import. A zip is rejected with a
+remedy telling the student to re-download the original archive instead of
+re-compressing the folder.
+
+Byte caps are enforced as the bytes stream in, so a header that
+under-declares a member's size aborts mid-file. Each tar member also passes
+``tarfile.data_filter`` where the interpreter provides it
+(3.10.12+/3.11.4+/3.12+), on top of the domain's pure vetting ladder, which
+does the main checking.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import tarfile
+import zlib
+from contextlib import contextmanager, suppress
+from typing import IO, TYPE_CHECKING, Final, Literal
+
+from ask_ta.adapters.bundle.store import disk_space_errors
+from ask_ta.domain.bundle import ArchiveEntry, MemberKind, display_member_name
+from ask_ta.domain.errors import (
+    ArchiveUnreadableError,
+    BundleUnavailableError,
+    UnsafeArchiveError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from pathlib import Path
+
+__all__ = [
+    "directory_content_sha256",
+    "file_sha256",
+    "open_bundle_source",
+    "require_pdf_magic",
+]
+
+_GZIP_MAGIC: Final = b"\x1f\x8b"
+_ZIP_MAGICS: Final = (b"PK\x03\x04", b"PK\x05\x06", b"PK\x07\x08")
+_USTAR_MAGIC: Final = b"ustar"
+_USTAR_OFFSET: Final = 257
+_PDF_MAGIC: Final = b"%PDF-"
+
+_STREAM_CHUNK_BYTES: Final = 2**20
+
+_ZIP_REMEDY: Final = (
+    "The imported file is a zip archive, but the course bundle is distributed "
+    "as a .tar.gz. Re-download the original file from your course page; "
+    "don't re-compress it."
+)
+
+#: Failures a corrupt gzip/tar stream can surface mid-read. ``OSError``
+#: covers ``tarfile.ReadError``-wrapped I/O and ``gzip.BadGzipFile``;
+#: ``zlib.error`` escapes raw from a corrupted deflate body.
+_STREAM_ERRORS: Final = (tarfile.TarError, EOFError, OSError, zlib.error)
+
+
+def _copy_stream(source: IO[bytes], dest: Path, *, max_bytes: int, member: str) -> int:
+    """Stream *source* to *dest* in 1 MiB chunks, enforcing *max_bytes* on the
+    bytes read; remove the partial file on any failure.
+
+    A write that runs out of room is reported as a storage fault, since the
+    archive itself is intact. Cleanup failures are swallowed so they cannot
+    replace that diagnosis with their own.
+    """
+    try:
+        with disk_space_errors():
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            with source, dest.open("wb") as out:
+                return _pump(source, out, max_bytes=max_bytes, member=member)
+    except BaseException:
+        with suppress(OSError):
+            dest.unlink(missing_ok=True)
+        raise
+
+
+def _pump(source: IO[bytes], out: IO[bytes], *, max_bytes: int, member: str) -> int:
+    written = 0
+    while True:
+        try:
+            chunk = source.read(_STREAM_CHUNK_BYTES)
+        except _STREAM_ERRORS as exc:
+            raise ArchiveUnreadableError(
+                f"Archive member {display_member_name(member)!r} could not be read: the stream is corrupt."
+            ) from exc
+        if not chunk:
+            return written
+        written += len(chunk)
+        if written > max_bytes:
+            raise UnsafeArchiveError(
+                f"Archive member {display_member_name(member)!r} exceeded the byte cap "
+                f"({max_bytes} bytes) while extracting."
+            )
+        out.write(chunk)
+
+
+class _TarArchiveReader:
+    """ArchiveReader over an open :class:`tarfile.TarFile`."""
+
+    def __init__(self, tar: tarfile.TarFile) -> None:
+        self._tar = tar
+
+    def entries(self) -> Sequence[ArchiveEntry]:
+        try:
+            members = self._tar.getmembers()
+        except _STREAM_ERRORS as exc:
+            raise ArchiveUnreadableError(
+                f"The archive's member index could not be read: {exc}."
+            ) from exc
+        return [
+            ArchiveEntry(name=member.name, size=member.size, kind=_member_kind(member))
+            for member in members
+        ]
+
+    def extract_file(self, name: str, dest: Path, *, max_bytes: int) -> int:
+        try:
+            member = self._tar.getmember(name)
+        except KeyError as exc:
+            raise ArchiveUnreadableError(
+                f"Archive member {display_member_name(name)!r} vanished between listing and extraction."
+            ) from exc
+
+        try:
+            tarfile.data_filter(member, str(dest.parent))
+        except AttributeError:
+            # Pre-3.10.12/3.11.4 interpreters lack the PEP 706 filter; the
+            # domain's vetting ladder does the checking either way.
+            pass
+        except tarfile.FilterError as exc:
+            raise UnsafeArchiveError(
+                f"Archive member {display_member_name(name)!r} was rejected by the tar data filter."
+            ) from exc
+
+        try:
+            stream = self._tar.extractfile(member)
+        except _STREAM_ERRORS as exc:
+            raise ArchiveUnreadableError(
+                f"Archive member {display_member_name(name)!r} could not be opened for extraction."
+            ) from exc
+        if stream is None:
+            raise ArchiveUnreadableError(
+                f"Archive member {display_member_name(name)!r} has no extractable content."
+            )
+        return _copy_stream(stream, dest, max_bytes=max_bytes, member=name)
+
+
+def _member_kind(member: tarfile.TarInfo) -> MemberKind:
+    if member.isreg():
+        return "file"
+    if member.isdir():
+        return "dir"
+    if member.issym() or member.islnk():
+        return "link"
+    return "other"
+
+
+class _DirectoryBundleReader:
+    """ArchiveReader over a plain directory (CLI folder import, Safari
+    auto-expanded downloads). Entry names are root-relative POSIX paths."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def entries(self) -> Sequence[ArchiveEntry]:
+        listed: list[ArchiveEntry] = []
+        try:
+            paths = sorted(self._root.rglob("*"))
+            for path in paths:
+                name = path.relative_to(self._root).as_posix()
+                # is_symlink first: is_file()/is_dir() follow symlinks.
+                if path.is_symlink():
+                    listed.append(ArchiveEntry(name=name, size=0, kind="link"))
+                elif path.is_dir():
+                    listed.append(ArchiveEntry(name=name, size=0, kind="dir"))
+                elif path.is_file():
+                    listed.append(ArchiveEntry(name=name, size=path.stat().st_size, kind="file"))
+                else:
+                    listed.append(ArchiveEntry(name=name, size=0, kind="other"))
+        except OSError as exc:
+            raise ArchiveUnreadableError(f"The bundle folder could not be listed: {exc}.") from exc
+        return listed
+
+    def extract_file(self, name: str, dest: Path, *, max_bytes: int) -> int:
+        try:
+            stream = (self._root / name).open("rb")
+        except OSError as exc:
+            raise ArchiveUnreadableError(
+                f"Bundle folder member {display_member_name(name)!r} could not be read: {exc}."
+            ) from exc
+        return _copy_stream(stream, dest, max_bytes=max_bytes, member=name)
+
+
+def _sniff_tar_mode(source: Path) -> Literal["r:gz", "r:"]:
+    """Return ``"r:gz"`` or ``"r:"`` by magic bytes; raise for zip and unknown bytes."""
+    try:
+        with source.open("rb") as handle:
+            head = handle.read(_USTAR_OFFSET + len(_USTAR_MAGIC))
+    except OSError as exc:
+        raise ArchiveUnreadableError(f"The imported file could not be read: {exc}.") from exc
+
+    if head.startswith(_GZIP_MAGIC):
+        return "r:gz"
+    if any(head.startswith(magic) for magic in _ZIP_MAGICS):
+        raise ArchiveUnreadableError(_ZIP_REMEDY)
+    if head[_USTAR_OFFSET : _USTAR_OFFSET + len(_USTAR_MAGIC)] == _USTAR_MAGIC:
+        return "r:"
+    raise ArchiveUnreadableError(
+        "The imported file is not a course bundle archive (expected a .tar.gz). "
+        "Re-download it from your course page."
+    )
+
+
+@contextmanager
+def open_bundle_source(source: Path) -> Iterator[_TarArchiveReader | _DirectoryBundleReader]:
+    """Open *source* (archive file or directory) as an ``ArchiveReader``.
+
+    Satisfies the :class:`~ask_ta.domain.bundle.ArchiveOpener` port.
+    """
+    if source.is_dir():
+        yield _DirectoryBundleReader(source)
+        return
+
+    mode = _sniff_tar_mode(source)
+    try:
+        tar = tarfile.open(source, mode=mode)  # noqa: SIM115 - closed in finally
+    except _STREAM_ERRORS as exc:
+        raise ArchiveUnreadableError(
+            f"The imported file could not be opened as a tar archive: {exc}."
+        ) from exc
+    try:
+        yield _TarArchiveReader(tar)
+    finally:
+        tar.close()
+
+
+def directory_content_sha256(root: Path, relpaths: Sequence[str]) -> str:
+    """Deterministic content identity for a folder import.
+
+    sha256 over each file's relpath + NUL + bytes + NUL, in sorted relpath
+    order, so the digest does not depend on listing order or on the archive
+    container that once wrapped the files. This is the folder counterpart of
+    the archive sha256 in the version id.
+    """
+    digest = hashlib.sha256()
+    for relpath in sorted(relpaths):
+        digest.update(relpath.encode("utf-8"))
+        digest.update(b"\x00")
+        with (root / relpath).open("rb") as handle:
+            while chunk := handle.read(_STREAM_CHUNK_BYTES):
+                digest.update(chunk)
+        digest.update(b"\x00")
+    return digest.hexdigest()
+
+
+def file_sha256(path: Path) -> str:
+    """Streamed sha256 of *path*, the archive identity a CLI import supplies.
+
+    The HTTP route gets this for free from the spool; a CLI import reads a file
+    the student already has, and streaming keeps a 65 MB archive out of memory.
+    """
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(_STREAM_CHUNK_BYTES):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def require_pdf_magic(path: Path) -> None:
+    """Probe-stage check that ``notes.pdf`` is present and PDF-shaped.
+
+    Only the magic bytes are read: parsing an imported PDF with PyMuPDF here
+    would enlarge the CVE surface, and the runtime opens it lazily per request
+    anyway. Raises the probe family's :class:`BundleUnavailableError` so the
+    composed probe can call this directly.
+    """
+    try:
+        with path.open("rb") as handle:
+            head = handle.read(len(_PDF_MAGIC))
+    except OSError as exc:
+        raise BundleUnavailableError(
+            f"Bundle notes.pdf at {path} could not be read: {exc}.",
+            missing_files=[path.name],
+        ) from exc
+    if head != _PDF_MAGIC:
+        raise BundleUnavailableError(
+            f"Bundle notes.pdf at {path} is not a PDF (bad magic bytes).",
+            missing_files=[path.name],
+        )