classPlatform#

class Platform( session: Session | None = None, )#

A catalogue of projects. Subclass it to support another platform.

Use it as a context manager, or call close when you are done.

Parameters:: session (Session | None) – The session to use. If omitted, the platform creates its own and closes it in close.

name#

The platform’s name.

Type:: ClassVar[str]

session#: The session in use.

close() → None#

Close the session, if the platform created it.

abstractmethod search( query: str, *, project_type: Literal['mod', 'modpack', 'resourcepack', 'shader'] = 'modpack', game_version: str | None = None, loader: str | None = None, sort: Literal['relevance', 'downloads', 'popularity', 'newest', 'updated'] = 'relevance', offset: int = 0, limit: int = 20, ) → SearchResults#

Search the platform’s catalogue.

Parameters:

query (str) – The search text.
project_type (Literal['mod', 'modpack', 'resourcepack', 'shader']) – The kind of project to find.
game_version (str | None) – Only match this Minecraft version.
loader (str | None) – Only match this mod loader.
sort (Literal['relevance', 'downloads', 'popularity', 'newest', 'updated']) – How to order the results. popularity means follows on Modrinth and favourites on CurseForge.
offset (int) – How many results to skip.
limit (int) – The maximum number of results to return. The built-in platforms read as many pages as it takes.

Returns:

The results.

Raises:

NetworkError – The platform could not be reached.

Return type:

SearchResults

abstractmethod get_project( ref: str | int, *, project_type: Literal['mod', 'modpack', 'resourcepack', 'shader'] = 'modpack', ) → Project#

Look up a project by id, slug or URL.

Parameters:

ref (str | int) – The project’s id, slug or web address.
project_type (Literal['mod', 'modpack', 'resourcepack', 'shader']) – The kind of project.

Returns:

The project.

Raises:

NetworkError – The platform failed or does not know the project.

Return type:

Project

abstractmethod iter_releases( 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.

Parameters:

project (Project) – The project.
game_version (str | None) – Only list this Minecraft version.
loader (str | None) – Only list this mod loader.
release_only (bool) – Leave out alpha and beta releases.

Yields:

Each release, once.

Raises:

NetworkError – The platform could not be reached.

get_projects( ids: Iterable[str], *, project_type: Literal['mod', 'modpack', 'resourcepack', 'shader'] = 'mod', ) → dict[str, Project]#

Look up several projects by id at once.

The built-in platforms do this in as few requests as they can. By default, each project is looked up on its own.

Parameters:

ids (Iterable[str]) – The projects’ ids.
project_type (Literal['mod', 'modpack', 'resourcepack', 'shader']) – The kind of project, for platforms whose lookups need one.

Returns:

Each project the platform knows, keyed by the id it was asked for. Unknown ids are left out.

Raises:

NetworkError – The platform could not be reached.

Return type:

dict[str, Project]

get_release( release_id: str, ) → Release#

Look up a release by id.

Parameters:

release_id (str) – The release’s id on this platform.

Returns:

The release.

Raises:

UnsupportedError – This platform cannot look up releases. That is the default.
PlatformError – The platform does not know the release.
NetworkError – The platform could not be reached.

Return type:

Release

authors( project: Project, ) → tuple[str, ...]#

Return the names of the people behind a project, the owner first.

Project lookups do not always say who made a project. Modrinth’s give no author, so this asks the platform separately. Call it where the authors are shown, not for every project.

Parameters:: project (Project) – The project, from this platform.
Returns:: The names, empty if the platform names nobody. By default, the project’s own author.
Raises:: NetworkError – The platform could not be reached.
Return type:: tuple[str, …]

changelog( release: Release, ) → str#

Return what changed in a release, as plain text.

Parameters:

release (Release) – The release, from this platform.

Returns:

The changelog, or an empty string if the author wrote none.

Raises:

UnsupportedError – This platform cannot fetch changelogs. That is the default.
NetworkError – The platform could not be reached.

Return type:

str

identify( paths: Iterable[Path | str], *, progress: Callable[[Progress], None] | None = None, cancel: CancelToken | None = None, ) → dict[Path, Release]#

Find the releases that files came from, by their contents.

Parameters:

paths (Iterable[Path | str]) – The files.
progress (Callable[[Progress], None] | None) – Receives an update as each file is read.
cancel (CancelToken | None) – Stops reading files.

Returns:

The release of each file the platform knows. Other files are left out. By default, nothing is known.

Raises:

OSError – A file could not be read.
NetworkError – The platform could not be reached.
Cancelled – cancel was triggered.

Return type:

dict[Path, Release]

latest_release( project: Project, *, game_version: str | None = None, loader: str | None = None, release_only: bool = False, ) → Release | None#

Return a project’s newest release for a game version and loader.

It reads only as many pages as it needs. For the Quilt loader, a Fabric release is used when there is no Quilt one, because Quilt loads Fabric mods.

Parameters:

project (Project) – The project.
game_version (str | None) – Only consider this Minecraft version.
loader (str | None) – Only consider this mod loader. None accepts any loader.
release_only (bool) – Leave out alpha and beta releases.

Returns:

The release, or None if there is none.

Raises:

NetworkError – The platform could not be reached.

Return type:

Release | None

list_releases( 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.

Parameters:

project (Project) – The project.
game_version (str | None) – Only list this Minecraft version.
loader (str | None) – Only list this mod loader.
release_only (bool) – Leave out alpha and beta releases.

Returns:

The releases.

Raises:

NetworkError – The platform could not be reached.

Return type:

list[Release]

resolve( pack: Modpack, ) → Modpack#

Fill in downloads for entries this platform can identify.

Parameters:: pack (Modpack) – The modpack.
Returns:: The modpack with resolved entries. By default, it is returned unchanged.
Return type:: Modpack

fetch( release: Release, into: Path, *, progress: Callable[[Progress], None] | None = None, cancel: CancelToken | None = None, ) → Path#

Download a release’s primary file into a directory.

Parameters:

release (Release) – The release.
into (Path) – The directory. It is created if needed.
progress (Callable[[Progress], None] | None) – Receives download updates.
cancel (CancelToken | None) – Stops the download.

Returns:

The downloaded file.

Raises:

PlatformError – The file has no download link.
DownloadError – The download failed.
Cancelled – cancel was triggered.

Return type:

Path