modsmith 0.1.0__py3-none-any.whl

modsmith/platforms/_curseforge.py

@@ -0,0 +1,390 @@
+"""The CurseForge platform."""
+
+import dataclasses
+from collections.abc import Iterator
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from ..errors import PlatformError
+from ..net import Session
+from ..packs import Modpack, PackEntry
+from ._base import (
+    Platform,
+    Project,
+    ProjectType,
+    Release,
+    ReleaseFile,
+    ReleaseType,
+    SearchResults,
+    project_ref,
+)
+
+API_URL = "https://api.curseforge.com"
+# Minecraft's id on CurseForge.
+GAME_ID = 432
+# The most ids to send in one request.
+BATCH_SIZE = 500
+PAGE_SIZE = 50
+# CurseForge rejects requests where index + pageSize is larger than this.
+MAX_RESULTS = 10000
+# CurseForge's numeric ids for hash algorithms, release types and categories.
+HASH_ALGORITHMS = {1: "sha1", 2: "md5"}
+RELEASE_TYPES: dict[int, ReleaseType] = {1: "release", 2: "beta", 3: "alpha"}
+PROJECT_CLASSES: dict[str, int] = {
+    "mod": 6,
+    "modpack": 4471,
+    "resourcepack": 12,
+    "shader": 6552,
+}
+CLASS_FOLDERS = {
+    6: "mods",
+    12: "resourcepacks",
+    17: "saves",
+    4546: "config",
+    6552: "shaderpacks",
+    6945: "datapacks",
+}
+LOADER_TYPES = {"forge": 1, "fabric": 4, "quilt": 5, "neoforge": 6}
+
+
+class _Schema(BaseModel):
+    """Base for CurseForge API models, which use camelCase names."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class _Hash(_Schema):
+    """A file hash from the CurseForge API."""
+
+    value: str
+    algo: int
+
+
+class _File(_Schema):
+    """A file from the CurseForge API."""
+
+    id: int
+    mod_id: int
+    display_name: str = ""
+    file_name: str
+    release_type: Literal[1, 2, 3] = 1
+    file_date: str = ""
+    file_length: int | None = None
+    download_url: str | None = None
+    hashes: list[_Hash] = Field(default_factory=list[_Hash])
+    is_server_pack: bool | None = False
+    game_versions: list[str] = Field(default_factory=list[str])
+
+    @property
+    def hash_map(self) -> dict[str, str]:
+        """The digests keyed by algorithm name."""
+        return {
+            HASH_ALGORITHMS[item.algo]: item.value
+            for item in self.hashes
+            if item.algo in HASH_ALGORITHMS
+        }
+
+    def to_release(self, platform: str) -> Release:
+        """Convert this file to a `Release`."""
+        urls = (self.download_url,) if self.download_url else ()
+        return Release(
+            platform=platform,
+            id=str(self.id),
+            project_id=str(self.mod_id),
+            name=self.display_name or self.file_name,
+            release_type=RELEASE_TYPES[self.release_type],
+            published=self.file_date,
+            game_versions=tuple(self.game_versions),
+            files=(ReleaseFile(self.file_name, urls, self.hash_map, self.file_length),),
+        )
+
+
+class _Logo(_Schema):
+    """A project's logo from the CurseForge API."""
+
+    url: str | None = None
+    thumbnail_url: str | None = None
+
+
+class _Links(_Schema):
+    """A project's links from the CurseForge API."""
+
+    website_url: str | None = None
+
+
+class _Mod(_Schema):
+    """A project from the CurseForge API."""
+
+    id: int
+    name: str
+    slug: str
+    summary: str = ""
+    class_id: int | None = None
+    logo: _Logo | None = None
+    links: _Links | None = None
+    allow_mod_distribution: bool | None = None
+    download_count: int = 0
+
+    def to_project(self, platform: str, project_type: str) -> Project:
+        """Convert this mod to a `Project`."""
+        logo = self.logo
+        return Project(
+            platform=platform,
+            id=str(self.id),
+            slug=self.slug,
+            name=self.name,
+            summary=self.summary,
+            project_type=project_type,
+            icon_url=(logo.thumbnail_url or logo.url) if logo else None,
+            url=self.links.website_url if self.links else None,
+            downloads=self.download_count,
+        )
+
+
+class CurseForge(Platform):
+    """CurseForge. Requires an API key from console.curseforge.com.
+
+    Args:
+        api_key: The API key.
+        session: The session to use. If omitted, the platform creates its own.
+        base_url: The API's base URL.
+
+    Attributes:
+        api_key: The API key.
+        base_url: The API's base URL.
+
+    Raises:
+        PlatformError: The API key is empty.
+    """
+
+    name: ClassVar[str] = "curseforge"
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        session: Session | None = None,
+        base_url: str = API_URL,
+    ) -> None:
+        super().__init__(session)
+        if not api_key:
+            raise PlatformError("CurseForge requires an API key")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        """The headers sent with every request."""
+        return {"Accept": "application/json", "x-api-key": self.api_key}
+
+    def _get(self, path: str, **params: Any) -> Any:
+        """Send a GET request to the API."""
+        return self.session.get_json(
+            self.base_url + path, headers=self._headers, params=params
+        )
+
+    def _post(self, path: str, payload: dict[str, Any]) -> Any:
+        """Send a POST request to the API."""
+        return self.session.post_json(
+            self.base_url + path, headers=self._headers, json=payload
+        )
+
+    def _search(self, project_type: str, **params: Any) -> Any:
+        """Search the Minecraft projects of one type."""
+        return self._get(
+            "/v1/mods/search",
+            gameId=GAME_ID,
+            classId=PROJECT_CLASSES[project_type],
+            **params,
+        )
+
+    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 CurseForge'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: CurseForge could not be reached.
+        """
+        data = self._search(
+            project_type,
+            searchFilter=query,
+            gameVersion=game_version,
+            modLoaderType=LOADER_TYPES.get(loader or ""),
+            index=offset,
+            pageSize=limit,
+        )
+        mods = [_Mod.model_validate(item) for item in data["data"]]
+        projects = tuple(mod.to_project(self.name, project_type) for mod in mods)
+        pagination: dict[str, Any] = data.get("pagination") or {}
+        return SearchResults(projects, pagination.get("totalCount", len(mods)), offset)
+
+    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. Slugs are only unique within a type.
+
+        Returns:
+            The project.
+
+        Raises:
+            PlatformError: No project has that slug.
+            NetworkError: CurseForge could not be reached or does not know the id.
+        """
+        text = project_ref(ref)
+        if text.isdigit():
+            mod = _Mod.model_validate(self._get(f"/v1/mods/{text}")["data"])
+            return mod.to_project(self.name, project_type)
+        data = self._search(project_type, slug=text, pageSize=1)
+        if not data["data"]:
+            raise PlatformError(f"No CurseForge {project_type} found for {ref}")
+        return _Mod.model_validate(data["data"][0]).to_project(self.name, project_type)
+
+    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.
+
+        Server packs are left out. CurseForge serves at most 10,000 files per
+        project, so older releases of a larger project are not listed.
+
+        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: CurseForge could not be reached.
+        """
+        seen: set[int] = set()
+        index = 0
+        while index + PAGE_SIZE <= MAX_RESULTS:
+            data = self._get(
+                f"/v1/mods/{project.id}/files",
+                gameVersion=game_version,
+                modLoaderType=LOADER_TYPES.get(loader or ""),
+                index=index,
+                pageSize=PAGE_SIZE,
+            )
+            page = [_File.model_validate(item) for item in data["data"]]
+            index += len(page)
+            for file in page:
+                unwanted = release_only and file.release_type != 1
+                if file.id not in seen and not file.is_server_pack and not unwanted:
+                    seen.add(file.id)
+                    yield file.to_release(self.name)
+            pagination: dict[str, Any] = data.get("pagination") or {}
+            if not page or index >= pagination.get("totalCount", 0):
+                return
+
+    def _files(self, file_ids: list[int]) -> dict[int, _File]:
+        """Fetch files by id, in batches."""
+        files: dict[int, _File] = {}
+        for start in range(0, len(file_ids), BATCH_SIZE):
+            batch = file_ids[start : start + BATCH_SIZE]
+            data = self._post("/v1/mods/files", {"fileIds": batch})
+            for item in data["data"]:
+                file = _File.model_validate(item)
+                files[file.id] = file
+        return files
+
+    def _mods(self, mod_ids: list[int]) -> dict[int, _Mod]:
+        """Fetch mods by id, in batches."""
+        mods: dict[int, _Mod] = {}
+        for start in range(0, len(mod_ids), BATCH_SIZE):
+            batch = mod_ids[start : start + BATCH_SIZE]
+            data = self._post("/v1/mods", {"modIds": batch, "filterPcOnly": False})
+            for item in data["data"]:
+                mod = _Mod.model_validate(item)
+                mods[mod.id] = mod
+        return mods
+
+    def _resolved_entry(
+        self, entry: PackEntry, file: _File, mod: _Mod | None
+    ) -> PackEntry:
+        """Fill in an entry from its file and mod."""
+        # CurseForge can omit the flag, and only an explicit False forbids downloads.
+        allowed = mod is None or mod.allow_mod_distribution is not False
+        url = file.download_url if allowed else None
+        manual_url = None
+        if url is None:
+            website = mod.links.website_url if mod and mod.links else None
+            base = website or f"https://www.curseforge.com/projects/{file.mod_id}"
+            manual_url = f"{base.rstrip('/')}/files/{file.id}"
+        folder = CLASS_FOLDERS.get(mod.class_id or 6 if mod else 6, "mods")
+        return dataclasses.replace(
+            entry,
+            path=f"{folder}/{file.file_name}",
+            urls=(url,) if url else (),
+            hashes=file.hash_map,
+            size=file.file_length,
+            manual_url=manual_url,
+        )
+
+    def resolve(self, pack: Modpack) -> Modpack:
+        """Look up download details for a CurseForge pack.
+
+        A file whose author disallows third-party downloads stays unresolved and
+        carries a ``manual_url``. A file CurseForge no longer lists also stays
+        unresolved, with no ``manual_url``.
+
+        Args:
+            pack: The modpack.
+
+        Returns:
+            The modpack with resolved entries.
+
+        Raises:
+            NetworkError: CurseForge could not be reached.
+        """
+        pending = [
+            entry
+            for entry in pack.entries
+            if entry.ref and entry.ref.platform == self.name and not entry.is_resolved
+        ]
+        ids = [int(entry.ref.file_id) for entry in pending if entry.ref]
+        files = self._files(ids)
+        mods = self._mods(sorted({file.mod_id for file in files.values()}))
+
+        def resolved(entry: PackEntry) -> PackEntry:
+            if entry.ref is None or entry.ref.platform != self.name:
+                return entry
+            file = files.get(int(entry.ref.file_id))
+            if file is None:
+                return entry
+            return self._resolved_entry(entry, file, mods.get(file.mod_id))
+
+        return pack.with_entries(tuple(resolved(entry) for entry in pack.entries))

modsmith/platforms/_modrinth.py

@@ -0,0 +1,261 @@
+"""The Modrinth platform."""
+
+import json
+from collections.abc import Iterator
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, Field
+
+from ..net import Session
+from ..net._session import DEFAULT_USER_AGENT
+from ._base import (
+    Platform,
+    Project,
+    ProjectType,
+    Release,
+    ReleaseFile,
+    SearchResults,
+    project_ref,
+)
+
+API_URL = "https://api.modrinth.com/v2"
+SITE_URL = "https://modrinth.com"
+PAGE_SIZE = 100
+
+
+class _Hit(BaseModel):
+    """One search result from the Modrinth API."""
+
+    project_id: str
+    slug: str
+    title: str
+    description: str = ""
+    project_type: str = "modpack"
+    icon_url: str | None = None
+    downloads: int = 0
+
+
+class _SearchResponse(BaseModel):
+    """The Modrinth API's search response."""
+
+    hits: list[_Hit]
+    total_hits: int = 0
+    offset: int = 0
+
+
+class _Project(BaseModel):
+    """A project from the Modrinth API."""
+
+    id: str
+    slug: str
+    title: str
+    description: str = ""
+    project_type: str = "modpack"
+    icon_url: str | None = None
+    downloads: int = 0
+
+
+class _File(BaseModel):
+    """A version's file from the Modrinth API."""
+
+    filename: str
+    url: str
+    hashes: dict[str, str] = Field(default_factory=dict[str, str])
+    size: int | None = None
+    primary: bool = False
+
+
+class _Version(BaseModel):
+    """A version from the Modrinth API."""
+
+    id: str
+    project_id: str
+    name: str
+    version_type: Literal["release", "beta", "alpha"] = "release"
+    date_published: str = ""
+    game_versions: list[str] = Field(default_factory=list[str])
+    loaders: list[str] = Field(default_factory=list[str])
+    files: list[_File] = Field(default_factory=list[_File])
+
+
+def _project_url(project_type: str, slug: str) -> str:
+    """Return a project's web page."""
+    return f"{SITE_URL}/{project_type}/{slug}"
+
+
+class Modrinth(Platform):
+    """Modrinth. No API key is needed.
+
+    Args:
+        user_agent: Identifies your tool. Modrinth asks every client to set one.
+        session: The session to use, instead of creating one. ``user_agent`` is
+            then ignored.
+        base_url: The API's base URL.
+
+    Attributes:
+        base_url: The API's base URL.
+    """
+
+    name: ClassVar[str] = "modrinth"
+
+    def __init__(
+        self,
+        user_agent: str | None = None,
+        *,
+        session: Session | None = None,
+        base_url: str = API_URL,
+    ) -> None:
+        owned = None if session else Session(user_agent or DEFAULT_USER_AGENT)
+        super().__init__(session or owned)
+        self._owns_session = session is None
+        self.base_url = base_url.rstrip("/")
+
+    def _get(self, path: str, **params: Any) -> Any:
+        """Send a GET request to the API."""
+        return self.session.get_json(self.base_url + path, params=params)
+
+    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 Modrinth'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: Modrinth could not be reached.
+        """
+        facets = [[f"project_type:{project_type}"]]
+        if game_version:
+            facets.append([f"versions:{game_version}"])
+        if loader:
+            facets.append([f"categories:{loader}"])
+        data = _SearchResponse.model_validate(
+            self._get(
+                "/search",
+                query=query,
+                facets=json.dumps(facets),
+                offset=offset,
+                limit=limit,
+            )
+        )
+        projects = tuple(
+            Project(
+                platform=self.name,
+                id=hit.project_id,
+                slug=hit.slug,
+                name=hit.title,
+                summary=hit.description,
+                project_type=hit.project_type,
+                icon_url=hit.icon_url,
+                url=_project_url(hit.project_type, hit.slug),
+                downloads=hit.downloads,
+            )
+            for hit in data.hits
+        )
+        return SearchResults(projects, data.total_hits, data.offset)
+
+    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: Not used, because Modrinth's ids are unique across types.
+
+        Returns:
+            The project.
+
+        Raises:
+            NetworkError: Modrinth could not be reached or does not know the project.
+        """
+        data = _Project.model_validate(self._get(f"/project/{project_ref(ref)}"))
+        return Project(
+            platform=self.name,
+            id=data.id,
+            slug=data.slug,
+            name=data.title,
+            summary=data.description,
+            project_type=data.project_type,
+            icon_url=data.icon_url,
+            url=_project_url(data.project_type, data.slug),
+            downloads=data.downloads,
+        )
+
+    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.
+
+        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: Modrinth could not be reached.
+        """
+        params: dict[str, Any] = {"include_changelog": "false", "limit": PAGE_SIZE}
+        if game_version:
+            params["game_versions"] = json.dumps([game_version])
+        if loader:
+            params["loaders"] = json.dumps([loader])
+        seen: set[str] = set()
+        offset = 0
+        while True:
+            page = self._get(f"/project/{project.id}/version", offset=offset, **params)
+            # Modrinth can return short pages before the end of the list, so
+            # only an empty page ends it, and the offset always moves by a page.
+            if not page:
+                return
+            offset += PAGE_SIZE
+            for item in page:
+                version = _Version.model_validate(item)
+                unwanted = release_only and version.version_type != "release"
+                if version.id not in seen and not unwanted:
+                    seen.add(version.id)
+                    yield self._to_release(version)
+
+    def _to_release(self, version: _Version) -> Release:
+        """Convert a Modrinth version to a `Release`."""
+        return Release(
+            platform=self.name,
+            id=version.id,
+            project_id=version.project_id,
+            name=version.name,
+            release_type=version.version_type,
+            published=version.date_published,
+            game_versions=tuple(version.game_versions),
+            loaders=tuple(version.loaders),
+            files=tuple(
+                ReleaseFile(
+                    file.filename, (file.url,), file.hashes, file.size, file.primary
+                )
+                for file in version.files
+            ),
+        )