modsmith 0.1.0__py3-none-any.whl

modsmith/__init__.py

@@ -0,0 +1,36 @@
+"""Modsmith: a Python toolkit for Minecraft modpacks and game files."""
+
+import logging
+
+from . import (
+    errors,
+    instances,
+    java,
+    launcher,
+    loaders,
+    minecraft,
+    net,
+    packs,
+    platforms,
+    progress,
+)
+from .net._session import __version__
+from .progress import CancelToken, Progress
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "CancelToken",
+    "Progress",
+    "__version__",
+    "errors",
+    "instances",
+    "java",
+    "launcher",
+    "loaders",
+    "minecraft",
+    "net",
+    "packs",
+    "platforms",
+    "progress",
+]

modsmith/_support.py

@@ -0,0 +1,81 @@
+"""Internal helpers for files and names."""
+
+import errno
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import IO, Any
+
+from platformdirs import user_cache_path
+
+
+def default_cache_dir() -> Path:
+    """Return the per-user directory used for caches by default."""
+    return user_cache_path("modsmith", appauthor=False)
+
+
+def slugify(name: str, fallback: str = "instance") -> str:
+    """Turn a display name into a lowercase, hyphenated slug.
+
+    Args:
+        name: The display name.
+        fallback: Returned when ``name`` has no ASCII letters or digits.
+
+    Returns:
+        The slug.
+    """
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") or fallback
+
+
+def copy_replace(source: Path, dest: Path) -> None:
+    """Copy ``source`` over ``dest``, then delete ``source``."""
+    shutil.copy2(source, dest)
+    source.unlink()
+
+
+def replace_file(source: Path, dest: Path) -> None:
+    """Rename over ``dest``, copying when the filesystem refuses the rename.
+
+    Containers such as MSIX can reject renames inside redirected folders with
+    ``EXDEV`` even though both paths share a directory.
+
+    Args:
+        source: The file to move.
+        dest: The file to replace.
+
+    Raises:
+        OSError: The rename failed for another reason, or the copy failed.
+    """
+    try:
+        os.replace(source, dest)
+    except OSError as e:
+        if e.errno != errno.EXDEV:
+            raise
+        copy_replace(source, dest)
+
+
+def write_atomic(path: Path, data: bytes | IO[bytes]) -> None:
+    """Write a file through a temporary sibling, creating parent directories.
+
+    Readers see either the old contents or the new ones, never a partial file.
+
+    Args:
+        path: The file to write.
+        data: The contents, or an open file to copy them from.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_name(path.name + ".tmp")
+    with open(temp, "wb") as file:
+        if isinstance(data, bytes):
+            file.write(data)
+        else:
+            shutil.copyfileobj(data, file)
+    replace_file(temp, path)
+
+
+def write_json(path: Path, data: Any) -> None:
+    """Atomically write indented JSON as UTF-8."""
+    text = json.dumps(data, indent=2, ensure_ascii=False)
+    write_atomic(path, text.encode("utf-8"))

modsmith/errors.py

@@ -0,0 +1,115 @@
+"""Exceptions raised by modsmith. All of them derive from `ModsmithError`."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .packs import PackEntry
+
+__all__ = [
+    "Cancelled",
+    "DownloadError",
+    "InstanceError",
+    "IntegrityError",
+    "JavaError",
+    "LauncherError",
+    "LoaderError",
+    "ModsmithError",
+    "NetworkError",
+    "PackError",
+    "PlatformError",
+    "ProcessorError",
+    "UnresolvedEntriesError",
+    "UnsupportedError",
+]
+
+
+class ModsmithError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class Cancelled(ModsmithError):
+    """A `CancelToken` stopped the operation. It can be run again later."""
+
+
+class NetworkError(ModsmithError):
+    """An HTTP request failed.
+
+    Args:
+        message: What went wrong.
+        status: The HTTP status code.
+
+    Attributes:
+        status: The HTTP status code, or None if no response arrived.
+    """
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class DownloadError(ModsmithError):
+    """One or more downloads failed.
+
+    Args:
+        message: A summary of the failure.
+        failures: A reason for each file that failed.
+
+    Attributes:
+        failures: A reason for each file that failed.
+    """
+
+    def __init__(self, message: str, failures: Sequence[str] = ()) -> None:
+        super().__init__(message)
+        self.failures = list(failures)
+
+
+class IntegrityError(ModsmithError):
+    """A file does not match its expected size or hash."""
+
+
+class UnsupportedError(ModsmithError):
+    """The requested version, loader or format is not supported."""
+
+
+class PackError(ModsmithError):
+    """A modpack archive is invalid."""
+
+
+class PlatformError(ModsmithError):
+    """A platform could not provide the requested data."""
+
+
+class LoaderError(ModsmithError):
+    """A mod loader could not be installed."""
+
+
+class ProcessorError(LoaderError):
+    """A Forge or NeoForge install processor failed."""
+
+
+class JavaError(ModsmithError):
+    """A Java runtime could not be found or installed."""
+
+
+class LauncherError(ModsmithError):
+    """The launcher profile data could not be used."""
+
+
+class InstanceError(ModsmithError):
+    """A game instance could not be read or changed."""
+
+
+class UnresolvedEntriesError(InstanceError):
+    """A pack still has entries with no download.
+
+    Args:
+        entries: The entries that could not be found.
+
+    Attributes:
+        entries: The entries that could not be found.
+    """
+
+    def __init__(self, entries: "Sequence[PackEntry]") -> None:
+        super().__init__(f"{len(entries)} pack entries have no download")
+        self.entries = list(entries)