modsmith 0.1.0__py3-none-any.whl

modsmith/packs/_model.py

@@ -0,0 +1,247 @@
+"""The modpack model, which does not depend on any format or platform."""
+
+import dataclasses
+import zipfile
+from collections.abc import Collection, Iterator, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import IO, Literal
+
+from .._support import write_atomic
+from ..errors import PackError
+from ..loaders import Loader, create
+from ..net import Resource
+
+# Which half of the game a file is for, and how much that side needs it.
+Side = Literal["client", "server"]
+Support = Literal["required", "optional", "unsupported"]
+
+
+def safe_relative(name: str) -> str:
+    """Reject archive paths that could escape the target directory.
+
+    Args:
+        name: The path inside a modpack.
+
+    Returns:
+        The normalized path, with forward slashes.
+
+    Raises:
+        PackError: The path is absolute or could leave the directory.
+    """
+    path = PurePosixPath(name)
+    if path.is_absolute() or ".." in path.parts or ":" in name or "\\" in name:
+        raise PackError(f"Unsafe path in modpack: {name}")
+    return path.as_posix()
+
+
+@dataclass(frozen=True)
+class FileRef:
+    """A file identified by a platform, not yet given a download.
+
+    Attributes:
+        platform: The platform's name.
+        project_id: The project's id on that platform.
+        file_id: The file's id on that platform.
+    """
+
+    platform: str
+    project_id: str
+    file_id: str
+
+
+@dataclass(frozen=True)
+class PackEntry:
+    """A file a pack needs. It is resolved once `path` and `urls` are known.
+
+    Attributes:
+        path: Where the file goes in the instance, or None if not yet known.
+        urls: Download locations, tried in order.
+        hashes: Expected digests keyed by algorithm name.
+        size: The expected size in bytes, or None if unknown.
+        client: Whether the client needs it.
+        server: Whether the server needs it.
+        ref: The platform file it refers to, or None.
+        manual_url: The page where a player can download it by hand, or None.
+    """
+
+    path: str | None = None
+    urls: tuple[str, ...] = ()
+    hashes: Mapping[str, str] = field(default_factory=dict[str, str], hash=False)
+    size: int | None = None
+    client: Support = "required"
+    server: Support = "required"
+    ref: FileRef | None = None
+    manual_url: str | None = None
+
+    @property
+    def is_resolved(self) -> bool:
+        """Whether the entry has a path and a download."""
+        return self.path is not None and bool(self.urls)
+
+    def support(self, side: Side) -> Support:
+        """Return how ``side`` treats this entry."""
+        return self.client if side == "client" else self.server
+
+    def wanted(self, side: Side, include_optional: bool = False) -> bool:
+        """Return whether ``side`` should install this entry.
+
+        Args:
+            side: The side.
+            include_optional: Also accept optional entries.
+
+        Returns:
+            True if the entry should be installed.
+        """
+        support = self.support(side)
+        return support == "required" or (include_optional and support == "optional")
+
+    def resource(self, root: Path) -> Resource:
+        """Describe this entry's download.
+
+        Args:
+            root: The instance directory.
+
+        Returns:
+            The resource.
+
+        Raises:
+            PackError: The entry has no path yet.
+        """
+        if self.path is None:
+            raise PackError("Entry has no target path")
+        return Resource(self.urls, root / self.path, dict(self.hashes), self.size)
+
+
+@dataclass(frozen=True)
+class Modpack:
+    """A parsed modpack archive, independent of its format and platform.
+
+    Attributes:
+        format: The archive format's name, such as ``mrpack``.
+        name: The pack's name.
+        version: The pack's version.
+        minecraft: The Minecraft version it needs.
+        loader_kind: The mod loader's name.
+        loader_version: The mod loader's version.
+        entries: The files it needs.
+        archive: The archive it was read from.
+        override_roots: Archive folders with extra files, keyed by ``common``,
+            ``client`` or ``server``.
+        memory_mb: The recommended memory, or None if not declared.
+    """
+
+    format: str
+    name: str
+    version: str
+    minecraft: str
+    loader_kind: str
+    loader_version: str
+    entries: tuple[PackEntry, ...]
+    archive: Path
+    override_roots: Mapping[str, str] = field(
+        default_factory=dict[str, str], hash=False
+    )
+    memory_mb: int | None = None
+
+    @property
+    def loader(self) -> Loader:
+        """The pack's mod loader.
+
+        Raises:
+            UnsupportedError: The loader is not supported.
+        """
+        return create(self.loader_kind, self.loader_version, self.minecraft)
+
+    @property
+    def unresolved(self) -> tuple[PackEntry, ...]:
+        """The entries that have no download yet."""
+        return tuple(entry for entry in self.entries if not entry.is_resolved)
+
+    def with_entries(self, entries: tuple[PackEntry, ...]) -> "Modpack":
+        """Return a copy of this pack with different entries."""
+        return dataclasses.replace(self, entries=entries)
+
+    def override_members(self, side: Side = "client") -> dict[str, zipfile.ZipInfo]:
+        """Return the pack's override files without reading their contents.
+
+        Args:
+            side: The side to read.
+
+        Returns:
+            Each file's archive entry, keyed by its path relative to the
+            instance. A side-specific file replaces a common one.
+
+        Raises:
+            PackError: A file's path is unsafe.
+        """
+        roots = [self.override_roots.get("common"), self.override_roots.get(side)]
+        members: dict[str, zipfile.ZipInfo] = {}
+        with zipfile.ZipFile(self.archive) as archive:
+            for root in roots:
+                if not root:
+                    continue
+                prefix = root.strip("/") + "/"
+                for info in archive.infolist():
+                    if info.is_dir() or not info.filename.startswith(prefix):
+                        continue
+                    relative = safe_relative(info.filename.removeprefix(prefix))
+                    members[relative] = info
+        return members
+
+    def iter_override_files(
+        self, side: Side = "client", only: Collection[str] | None = None
+    ) -> Iterator[tuple[str, IO[bytes]]]:
+        """Yield override files as open streams, so large files stay out of memory.
+
+        Args:
+            side: The side to read.
+            only: The relative paths to read. Defaults to every file.
+
+        Yields:
+            Each file's path relative to the instance, and a stream of its
+            contents. The stream closes when the iteration moves on.
+
+        Raises:
+            PackError: A file's path is unsafe.
+        """
+        members = self.override_members(side)
+        with zipfile.ZipFile(self.archive) as archive:
+            for relative, info in members.items():
+                if only is None or relative in only:
+                    with archive.open(info) as file:
+                        yield relative, file
+
+    def iter_overrides(self, side: Side = "client") -> Iterator[tuple[str, bytes]]:
+        """Yield the pack's override files with their contents.
+
+        Args:
+            side: The side to read.
+
+        Yields:
+            Each file's path relative to the instance, and its contents.
+
+        Raises:
+            PackError: A file's path is unsafe.
+        """
+        for relative, file in self.iter_override_files(side):
+            yield relative, file.read()
+
+    def extract_overrides(self, dest: Path, side: Side = "client") -> list[str]:
+        """Write the override files into ``dest`` and return their paths.
+
+        Args:
+            dest: The instance directory.
+            side: The side to read.
+
+        Returns:
+            The relative paths that were written.
+
+        Raises:
+            PackError: A file's path is unsafe.
+        """
+        written: list[str] = []
+        for relative, file in self.iter_override_files(side):
+            write_atomic(dest / relative, file)
+            written.append(relative)
+        return written

modsmith/platforms/__init__.py

@@ -0,0 +1,25 @@
+"""Search and fetch from mod platforms. Subclass `Platform` to add another."""
+
+from ._base import (
+    Platform,
+    Project,
+    ProjectType,
+    Release,
+    ReleaseFile,
+    ReleaseType,
+    SearchResults,
+)
+from ._curseforge import CurseForge
+from ._modrinth import Modrinth
+
+__all__ = [
+    "CurseForge",
+    "Modrinth",
+    "Platform",
+    "Project",
+    "ProjectType",
+    "Release",
+    "ReleaseFile",
+    "ReleaseType",
+    "SearchResults",
+]

modsmith/platforms/_base.py

@@ -0,0 +1,312 @@
+"""The data types and interface shared by every platform."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import TracebackType
+from typing import ClassVar, Literal, Self
+
+from ..errors import PlatformError
+from ..net import Resource, Session, download
+from ..packs import Modpack
+from ..progress import CancelToken, ProgressCallback
+
+ProjectType = Literal["mod", "modpack", "resourcepack", "shader"]
+ReleaseType = Literal["release", "beta", "alpha"]
+
+
+@dataclass(frozen=True)
+class Project:
+    """A mod, modpack or other project on a platform.
+
+    Attributes:
+        platform: The platform's name.
+        id: The project's id on that platform.
+        slug: The project's short name.
+        name: The display name.
+        summary: A short description.
+        project_type: The kind of project, such as ``modpack``.
+        icon_url: The icon's URL, or None.
+        url: The project's web page, or None.
+        downloads: The number of downloads.
+    """
+
+    platform: str
+    id: str
+    slug: str
+    name: str
+    summary: str = ""
+    project_type: str = "modpack"
+    icon_url: str | None = None
+    url: str | None = None
+    downloads: int = 0
+
+
+@dataclass(frozen=True)
+class ReleaseFile:
+    """One file of a release.
+
+    Attributes:
+        name: The file name.
+        urls: Download locations. Empty if the file cannot be downloaded directly.
+        hashes: Expected digests keyed by algorithm name.
+        size: The size in bytes, or None if unknown.
+        primary: Whether this is the release's main file.
+    """
+
+    name: str
+    urls: tuple[str, ...] = ()
+    hashes: Mapping[str, str] = field(default_factory=dict[str, str], hash=False)
+    size: int | None = None
+    primary: bool = True
+
+
+@dataclass(frozen=True)
+class Release:
+    """One published version: a CurseForge File or a Modrinth Version.
+
+    Attributes:
+        platform: The platform's name.
+        id: The release's id on that platform.
+        project_id: The project's id on that platform.
+        name: The display name.
+        release_type: One of ``release``, ``beta`` or ``alpha``.
+        published: The publication time, in ISO 8601 format.
+        game_versions: The Minecraft versions it supports.
+        loaders: The mod loaders it supports.
+        files: The files it contains.
+    """
+
+    platform: str
+    id: str
+    project_id: str
+    name: str
+    release_type: ReleaseType = "release"
+    published: str = ""
+    game_versions: tuple[str, ...] = ()
+    loaders: tuple[str, ...] = ()
+    files: tuple[ReleaseFile, ...] = ()
+
+    @property
+    def primary_file(self) -> ReleaseFile:
+        """The file marked as primary, or the first file.
+
+        Raises:
+            PlatformError: The release has no files.
+        """
+        for file in self.files:
+            if file.primary:
+                return file
+        if not self.files:
+            raise PlatformError(f"Release {self.name} has no files")
+        return self.files[0]
+
+
+@dataclass(frozen=True)
+class SearchResults:
+    """One page of search results.
+
+    Attributes:
+        projects: The projects on this page.
+        total: The number of matches across all pages.
+        offset: The position of this page's first project.
+    """
+
+    projects: tuple[Project, ...]
+    total: int
+    offset: int = 0
+
+
+def project_ref(ref: str | int) -> str:
+    """Reduce an id, slug or project URL to the id or slug."""
+    return str(ref).rstrip("/").rsplit("/", 1)[-1]
+
+
+class Platform(ABC):
+    """A catalogue of projects. Subclass it to support another platform.
+
+    Use it as a context manager, or call `close` when you are done.
+
+    Args:
+        session: The session to use. If omitted, the platform creates its own and
+            closes it in `close`.
+
+    Attributes:
+        name: The platform's name.
+        session: The session in use.
+    """
+
+    name: ClassVar[str]
+
+    def __init__(self, session: Session | None = None) -> None:
+        self._owns_session = session is None
+        self.session = session or Session()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the session, if the platform created it."""
+        if self._owns_session:
+            self.session.close()
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        *,
+        project_type: ProjectType = "modpack",
+        game_version: str | None = None,
+        loader: str | None = None,
+        offset: int = 0,
+        limit: int = 20,
+    ) -> SearchResults:
+        """Search the platform's catalogue.
+
+        Args:
+            query: The search text.
+            project_type: The kind of project to find.
+            game_version: Only match this Minecraft version.
+            loader: Only match this mod loader.
+            offset: How many results to skip.
+            limit: The maximum number of results to return.
+
+        Returns:
+            One page of results.
+
+        Raises:
+            NetworkError: The platform could not be reached.
+        """
+
+    @abstractmethod
+    def get_project(
+        self, ref: str | int, *, project_type: ProjectType = "modpack"
+    ) -> Project:
+        """Look up a project by id, slug or URL.
+
+        Args:
+            ref: The project's id, slug or web address.
+            project_type: The kind of project.
+
+        Returns:
+            The project.
+
+        Raises:
+            NetworkError: The platform failed or does not know the project.
+        """
+
+    @abstractmethod
+    def iter_releases(
+        self,
+        project: Project,
+        *,
+        game_version: str | None = None,
+        loader: str | None = None,
+        release_only: bool = False,
+    ) -> Iterator[Release]:
+        """Yield a project's releases, newest first, reading pages as needed.
+
+        Stopping early saves requests, so ``next()`` finds the latest release
+        with a single request. Use it while the platform is still open.
+
+        Args:
+            project: The project.
+            game_version: Only list this Minecraft version.
+            loader: Only list this mod loader.
+            release_only: Leave out alpha and beta releases.
+
+        Yields:
+            Each release, once.
+
+        Raises:
+            NetworkError: The platform could not be reached.
+        """
+
+    def list_releases(
+        self,
+        project: Project,
+        *,
+        game_version: str | None = None,
+        loader: str | None = None,
+        release_only: bool = False,
+    ) -> list[Release]:
+        """List all of a project's releases, newest first.
+
+        This reads every page. Use `iter_releases` if you need only some.
+
+        Args:
+            project: The project.
+            game_version: Only list this Minecraft version.
+            loader: Only list this mod loader.
+            release_only: Leave out alpha and beta releases.
+
+        Returns:
+            The releases.
+
+        Raises:
+            NetworkError: The platform could not be reached.
+        """
+        releases = self.iter_releases(
+            project,
+            game_version=game_version,
+            loader=loader,
+            release_only=release_only,
+        )
+        return sorted(releases, key=lambda item: item.published, reverse=True)
+
+    def resolve(self, pack: Modpack) -> Modpack:
+        """Fill in downloads for entries this platform can identify.
+
+        Args:
+            pack: The modpack.
+
+        Returns:
+            The modpack with resolved entries. By default, it is returned unchanged.
+        """
+        return pack
+
+    def fetch(
+        self,
+        release: Release,
+        into: Path,
+        *,
+        progress: ProgressCallback | None = None,
+        cancel: CancelToken | None = None,
+    ) -> Path:
+        """Download a release's primary file into a directory.
+
+        Args:
+            release: The release.
+            into: The directory. It is created if needed.
+            progress: Receives download updates.
+            cancel: Stops the download.
+
+        Returns:
+            The downloaded file.
+
+        Raises:
+            PlatformError: The file has no download link.
+            DownloadError: The download failed.
+            Cancelled: ``cancel`` was triggered.
+        """
+        file = release.primary_file
+        if not file.urls:
+            raise PlatformError(f"{file.name} has no download link")
+        path = Path(into) / file.name
+        download(
+            Resource(file.urls, path, dict(file.hashes), file.size),
+            session=self.session,
+            progress=progress,
+            cancel=cancel,
+            task="fetch",
+        )
+        return path