modsmith 0.1.0__py3-none-any.whl

modsmith/minecraft/_game_dir.py

@@ -0,0 +1,168 @@
+"""The layout of a game directory and its version files."""
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .._support import write_json
+from ..errors import UnsupportedError
+from ._maven import maven_path
+
+
+def default_game_path() -> Path:
+    """Return the official launcher's default game directory for this system.
+
+    On Linux, the Flatpak directory is used if only that one exists.
+    """
+    home = Path.home()
+    if sys.platform == "win32":
+        appdata = os.getenv("APPDATA")
+        return Path(appdata, ".minecraft") if appdata else home / ".minecraft"
+    if sys.platform == "darwin":
+        return home / "Library" / "Application Support" / "minecraft"
+    default = home / ".minecraft"
+    flatpak = home / ".var" / "app" / "com.mojang.Minecraft" / ".minecraft"
+    return flatpak if not default.exists() and flatpak.exists() else default
+
+
+@dataclass(frozen=True)
+class Version:
+    """A parsed version JSON, vanilla or from a mod loader.
+
+    Attributes:
+        id: The version id.
+        inherits_from: The parent version of a loader version, or None.
+        java_component: The Mojang runtime it asks for, or None.
+        java_major: The major Java version it asks for, or None.
+        client_url: Where to download the client jar, or None.
+        client_sha1: The client jar's SHA-1, or None.
+        client_size: The client jar's size in bytes, or None.
+        raw: The original JSON data.
+    """
+
+    id: str
+    inherits_from: str | None = None
+    java_component: str | None = None
+    java_major: int | None = None
+    client_url: str | None = None
+    client_sha1: str | None = None
+    client_size: int | None = None
+    raw: dict[str, Any] = field(
+        default_factory=dict[str, Any], repr=False, compare=False
+    )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Version":
+        """Build a version from decoded JSON.
+
+        Args:
+            data: The version JSON.
+
+        Returns:
+            The parsed version.
+
+        Raises:
+            KeyError: The data has no ``id``.
+        """
+        java: dict[str, Any] = data.get("javaVersion") or {}
+        downloads: dict[str, Any] = data.get("downloads") or {}
+        client: dict[str, Any] = downloads.get("client") or {}
+        return cls(
+            id=data["id"],
+            inherits_from=data.get("inheritsFrom"),
+            java_component=java.get("component"),
+            java_major=java.get("majorVersion"),
+            client_url=client.get("url"),
+            client_sha1=client.get("sha1"),
+            client_size=client.get("size"),
+            raw=data,
+        )
+
+    @classmethod
+    def load(cls, path: Path) -> "Version":
+        """Read a version from a JSON file."""
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))
+
+
+class GameDir:
+    """A ``.minecraft`` directory and the layout of the files inside it.
+
+    Args:
+        path: The directory. It does not have to exist. A relative path is made
+            absolute, so it stays valid if the working directory changes.
+
+    Attributes:
+        path: The absolute path of the directory.
+    """
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).resolve()
+
+    @classmethod
+    def default(cls) -> "GameDir":
+        """Return the official launcher's default directory for this system."""
+        return cls(default_game_path())
+
+    def __repr__(self) -> str:
+        return f"GameDir({str(self.path)!r})"
+
+    @property
+    def versions_dir(self) -> Path:
+        """The directory that holds installed versions."""
+        return self.path / "versions"
+
+    @property
+    def libraries_dir(self) -> Path:
+        """The directory that holds libraries."""
+        return self.path / "libraries"
+
+    def version_json(self, version_id: str) -> Path:
+        """Return the path of a version's JSON file."""
+        return self.versions_dir / version_id / f"{version_id}.json"
+
+    def client_jar(self, version_id: str) -> Path:
+        """Return the path of a version's client jar."""
+        return self.versions_dir / version_id / f"{version_id}.jar"
+
+    def library(self, coord: str) -> Path:
+        """Return the path of the library with a Maven coordinate."""
+        return self.libraries_dir / maven_path(coord)
+
+    def has_version(self, version_id: str) -> bool:
+        """Return whether a version's JSON file exists."""
+        return self.version_json(version_id).is_file()
+
+    def installed_versions(self) -> list[str]:
+        """List the installed version ids, sorted by name."""
+        if not self.versions_dir.is_dir():
+            return []
+        names = sorted(path.name for path in self.versions_dir.iterdir())
+        return [name for name in names if self.has_version(name)]
+
+    def version(self, version_id: str) -> Version:
+        """Read an installed version.
+
+        Args:
+            version_id: The version id.
+
+        Returns:
+            The parsed version.
+
+        Raises:
+            UnsupportedError: The version is not installed.
+        """
+        if not self.has_version(version_id):
+            raise UnsupportedError(f"Version {version_id} is not installed")
+        return Version.load(self.version_json(version_id))
+
+    def write_version(self, version_id: str, data: dict[str, Any]) -> None:
+        """Write a version's JSON file.
+
+        Args:
+            version_id: The version id.
+            data: The version JSON.
+        """
+        write_json(self.version_json(version_id), data)

modsmith/minecraft/_maven.py

@@ -0,0 +1,75 @@
+"""Maven coordinates, used to locate library files."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MavenCoord:
+    """A parsed coordinate such as ``group:artifact:version:classifier@extension``.
+
+    Attributes:
+        group: The group id.
+        artifact: The artifact id.
+        version: The version.
+        classifier: The classifier, or None.
+        extension: The file extension.
+    """
+
+    group: str
+    artifact: str
+    version: str
+    classifier: str | None = None
+    extension: str = "jar"
+
+    @classmethod
+    def parse(cls, coord: str) -> "MavenCoord":
+        """Parse a coordinate.
+
+        Args:
+            coord: The coordinate. The classifier and extension are optional.
+
+        Returns:
+            The parsed coordinate.
+
+        Raises:
+            ValueError: The coordinate is malformed.
+        """
+        body, _, extension = coord.partition("@")
+        parts = body.split(":")
+        if not 3 <= len(parts) <= 4 or "@" in extension:
+            raise ValueError(f"Invalid maven coordinate: {coord}")
+        return cls(
+            group=parts[0],
+            artifact=parts[1],
+            version=parts[2],
+            classifier=parts[3] if len(parts) == 4 else None,
+            extension=extension or "jar",
+        )
+
+    @property
+    def path(self) -> str:
+        """The file's path inside a Maven repository."""
+        name = f"{self.artifact}-{self.version}"
+        if self.classifier:
+            name += f"-{self.classifier}"
+        group = self.group.replace(".", "/")
+        return f"{group}/{self.artifact}/{self.version}/{name}.{self.extension}"
+
+
+def maven_path(coord: str) -> str:
+    """Convert a coordinate to its path inside a Maven repository.
+
+    Args:
+        coord: The coordinate.
+
+    Returns:
+        The relative path, with forward slashes.
+
+    Raises:
+        ValueError: The coordinate is malformed.
+
+    Example:
+        >>> maven_path("net.fabricmc:fabric-loader:0.16.10")
+        'net/fabricmc/fabric-loader/0.16.10/fabric-loader-0.16.10.jar'
+    """
+    return MavenCoord.parse(coord).path

modsmith/minecraft/_remote.py

@@ -0,0 +1,115 @@
+"""Mojang's version manifest and vanilla game downloads."""
+
+from dataclasses import dataclass
+
+from ..errors import UnsupportedError
+from ..net import Resource, Session, download
+from ..net._session import session_scope
+from ..progress import CancelToken, ProgressCallback
+from ._game_dir import GameDir, Version
+
+VERSION_MANIFEST_URL = "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json"
+
+
+@dataclass(frozen=True)
+class VersionInfo:
+    """One entry in Mojang's version manifest.
+
+    Attributes:
+        id: The version id.
+        type: The kind of version, such as ``release`` or ``snapshot``.
+        url: Where to download the version JSON.
+        sha1: The version JSON's SHA-1.
+        release_time: When the version was released, in ISO 8601 format.
+    """
+
+    id: str
+    type: str
+    url: str
+    sha1: str
+    release_time: str
+
+
+def list_versions(
+    session: Session | None = None, *, manifest_url: str = VERSION_MANIFEST_URL
+) -> list[VersionInfo]:
+    """List every Minecraft version Mojang publishes, newest first.
+
+    Args:
+        session: The session to use. A temporary one is created if omitted.
+        manifest_url: Where to read the manifest.
+
+    Returns:
+        The manifest's entries.
+
+    Raises:
+        NetworkError: The manifest could not be fetched.
+    """
+    with session_scope(session) as client:
+        manifest = client.get_json(manifest_url)
+    return [
+        VersionInfo(v["id"], v["type"], v["url"], v["sha1"], v["releaseTime"])
+        for v in manifest["versions"]
+    ]
+
+
+def install_version(
+    game: GameDir,
+    version_id: str,
+    *,
+    session: Session | None = None,
+    progress: ProgressCallback | None = None,
+    cancel: CancelToken | None = None,
+    manifest_url: str = VERSION_MANIFEST_URL,
+) -> Version:
+    """Download a vanilla version's JSON and client jar into ``game``.
+
+    Files that are already valid are kept.
+
+    Args:
+        game: The game directory.
+        version_id: The Minecraft version.
+        session: The session to use. A temporary one is created if omitted.
+        progress: Receives updates while the client jar downloads.
+        cancel: Stops the download.
+        manifest_url: Where to read Mojang's version manifest.
+
+    Returns:
+        The installed version.
+
+    Raises:
+        UnsupportedError: The version is unknown or has no client download.
+        NetworkError: The manifest could not be fetched.
+        DownloadError: A file could not be downloaded.
+        Cancelled: ``cancel`` was triggered.
+    """
+    with session_scope(session) as client:
+        if not game.has_version(version_id):
+            info = next(
+                (
+                    v
+                    for v in list_versions(client, manifest_url=manifest_url)
+                    if v.id == version_id
+                ),
+                None,
+            )
+            if info is None:
+                raise UnsupportedError(f"Unknown Minecraft version: {version_id}")
+            meta = Resource.of(
+                info.url, game.version_json(version_id), {"sha1": info.sha1}
+            )
+            download(meta, session=client, cancel=cancel)
+
+        version = game.version(version_id)
+        if version.client_url is None:
+            raise UnsupportedError(f"Version {version_id} has no client download")
+        jar = Resource.of(
+            version.client_url,
+            game.client_jar(version_id),
+            {"sha1": version.client_sha1} if version.client_sha1 else None,
+            version.client_size,
+        )
+        download(
+            jar, session=client, progress=progress, cancel=cancel, task="minecraft"
+        )
+    return version

modsmith/net/__init__.py

@@ -0,0 +1,7 @@
+"""HTTP access and verified, resumable downloads."""
+
+from ._download import download
+from ._resource import Resource, file_hash
+from ._session import Session
+
+__all__ = ["Resource", "Session", "download", "file_hash"]

modsmith/net/_download.py

@@ -0,0 +1,243 @@
+"""Parallel downloads with verification and resume."""
+
+import logging
+import re
+import threading
+from collections.abc import Callable, Iterable
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+import requests
+
+from .._support import replace_file
+from ..errors import Cancelled, DownloadError, IntegrityError, NetworkError
+from ..progress import CancelToken, ProgressCallback, report
+from ._resource import Resource, matches, strongest_hash
+from ._session import Session, is_retryable
+
+logger = logging.getLogger(__name__)
+CHUNK_SIZE = 65536
+OnBytes = Callable[[int], None]
+
+
+class _Meter:
+    """Tracks how many bytes of one file count toward the overall progress."""
+
+    def __init__(self, on_bytes: OnBytes) -> None:
+        self.on_bytes = on_bytes
+        self.counted = 0
+
+    def add(self, count: int) -> None:
+        """Count more bytes. A negative count takes bytes back."""
+        if count:
+            self.counted += count
+            self.on_bytes(count)
+
+    def reset(self, count: int) -> None:
+        """Set the count, for a file that was skipped, resumed or restarted."""
+        self.add(count - self.counted)
+
+
+def _verify(resource: Resource, part: Path) -> None:
+    """Check a finished ``.part`` file, raising `IntegrityError` if it is wrong."""
+    if resource.size is not None and part.stat().st_size != resource.size:
+        raise IntegrityError(f"Size mismatch for {resource.path.name}")
+    if not matches(part, resource.hashes):
+        raise IntegrityError(f"Hash mismatch for {resource.path.name}")
+
+
+def _range_start(response: requests.Response) -> int | None:
+    """Return where a partial response starts, if it says."""
+    match = re.match(r"bytes (\d+)-", response.headers.get("Content-Range", ""))
+    return int(match[1]) if match else None
+
+
+def _validator(response: requests.Response) -> str | None:
+    """Return a value that identifies this version of a file for ``If-Range``."""
+    etag = response.headers.get("ETag")
+    # ``If-Range`` only works with strong validators.
+    if etag and not etag.startswith("W/"):
+        return etag
+    return response.headers.get("Last-Modified")
+
+
+def _stream(
+    url: str,
+    resource: Resource,
+    part: Path,
+    session: Session,
+    meter: _Meter,
+    cancel: CancelToken | None,
+    validators: dict[str, str],
+) -> None:
+    """Fetch one URL into ``part``, continuing from what is already there.
+
+    ``validators`` remembers which version of the file each URL served, so a
+    resume cannot join two versions.
+    """
+    offset = part.stat().st_size if part.exists() else 0
+    if resource.size is not None and offset >= resource.size:
+        part.touch()  # an empty file has nothing to stream
+        meter.reset(offset)
+        return
+    headers: dict[str, str] = {}
+    if offset:
+        headers["Range"] = f"bytes={offset}-"
+        if url in validators:
+            headers["If-Range"] = validators[url]
+    with session.stream(url, headers, accept=(416,)) as response:
+        if response.status_code == 416:
+            raise IntegrityError(f"Stale partial file for {url}")
+        # A 200 means the server sent the whole file, either because it ignored
+        # the range or because the file changed.
+        resuming = offset > 0 and response.status_code == 206
+        if resuming and _range_start(response) not in (None, offset):
+            raise IntegrityError(f"Wrong range from {url}")
+        validator = _validator(response)
+        if validator:
+            validators[url] = validator
+        meter.reset(offset if resuming else 0)
+        with open(part, "ab" if resuming else "wb") as file:
+            for chunk in response.iter_content(CHUNK_SIZE):
+                if cancel is not None:
+                    cancel.check()
+                file.write(chunk)
+                meter.add(len(chunk))
+
+
+def _fetch(
+    resource: Resource,
+    session: Session,
+    on_bytes: OnBytes,
+    cancel: CancelToken | None,
+) -> None:
+    """Download one resource, trying each URL in turn.
+
+    `Session.stream` has already retried a failure to connect, so that moves on
+    to the next URL. Only a broken transfer or a bad file is retried here.
+
+    Raises:
+        DownloadError: Every URL failed.
+        Cancelled: ``cancel`` was triggered.
+    """
+    meter = _Meter(on_bytes)
+    if resource.is_present():
+        meter.reset(resource.size or 0)
+        return
+    if not resource.urls:
+        raise DownloadError(f"{resource.path.name} has no download URL")
+    resource.path.parent.mkdir(parents=True, exist_ok=True)
+    part = resource.path.with_name(resource.path.name + ".part")
+    # Without a hash, nothing could prove a leftover file is the same version.
+    if strongest_hash(resource.hashes) is None:
+        part.unlink(missing_ok=True)
+
+    validators: dict[str, str] = {}
+    last: Exception | None = None
+    for url in resource.urls:
+        for attempt in range(session.attempts):
+            if attempt:
+                session.wait(attempt - 1)
+            if cancel is not None:
+                cancel.check()
+            try:
+                _stream(url, resource, part, session, meter, cancel, validators)
+                _verify(resource, part)
+            except IntegrityError as e:
+                part.unlink(missing_ok=True)
+                last = e
+                continue
+            except NetworkError as e:
+                last = e
+                break
+            except requests.RequestException as e:
+                last = e
+                if not is_retryable(e):
+                    break
+                continue
+            replace_file(part, resource.path)
+            return
+        logger.warning("Download from %s failed: %s", url, last)
+    raise DownloadError(f"Failed to download {resource.path.name}: {last}") from last
+
+
+def download(
+    resources: Resource | Iterable[Resource],
+    *,
+    session: Session | None = None,
+    max_workers: int = 8,
+    progress: ProgressCallback | None = None,
+    cancel: CancelToken | None = None,
+    task: str = "download",
+) -> None:
+    """Download resources in parallel, skipping files that are already valid.
+
+    Interrupted files resume from their ``.part`` file. All files are attempted
+    even if some fail. Resources with the same path are downloaded once.
+
+    Args:
+        resources: One resource, or several.
+        session: The session to use. A temporary one is created if omitted.
+        max_workers: How many files to download at once.
+        progress: Called with byte counts if every size is known, otherwise with
+            file counts. It may be called from worker threads, one at a time.
+        cancel: Stops the downloads and keeps partial files for later.
+        task: The task name reported to ``progress``.
+
+    Raises:
+        DownloadError: A file failed. `DownloadError.failures` lists every failure.
+        Cancelled: ``cancel`` was triggered.
+    """
+    items = [resources] if isinstance(resources, Resource) else list(resources)
+    unique = list({resource.path: resource for resource in items}.values())
+    if session is None:
+        with Session() as owned:
+            return download(
+                unique,
+                session=owned,
+                max_workers=max_workers,
+                progress=progress,
+                cancel=cancel,
+                task=task,
+            )
+
+    sizes = [resource.size for resource in unique]
+    by_bytes = bool(unique) and all(size is not None for size in sizes)
+    total_bytes = sum(size or 0 for size in sizes)
+    lock = threading.Lock()
+    transferred = 0
+
+    def on_bytes(count: int) -> None:
+        nonlocal transferred
+        if not by_bytes:
+            return
+        with lock:
+            transferred += count
+            done = min(max(transferred, 0), total_bytes)
+            report(progress, task, done, total_bytes, "byte")
+
+    failures: list[str] = []
+    finished = 0
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures: dict[Future[None], Resource] = {
+            executor.submit(_fetch, resource, session, on_bytes, cancel): resource
+            for resource in unique
+        }
+        for future in as_completed(futures):
+            error = future.exception()
+            if isinstance(error, Cancelled):
+                for other in futures:
+                    other.cancel()
+                raise error
+            if isinstance(error, DownloadError):
+                failures.append(str(error))
+            elif error is not None:
+                raise error
+            finished += 1
+            if not by_bytes:
+                with lock:
+                    report(progress, task, finished, len(unique), "file")
+    if failures:
+        raise DownloadError(
+            f"{len(failures)} of {len(unique)} downloads failed", failures
+        )