classModrinth

class Modrinth(

user_agent: str | None = None,

*,

session: Session | None = None,

base_url: str = 'https://api.modrinth.com/v2',

)

Modrinth. No API key is needed.

Parameters:

• user_agent (str | None) – Identifies your tool. Modrinth asks every client to set one.

• session (Session | None) – The session to use, instead of creating one. user_agent is then ignored.

• base_url (str) – The API’s base URL.

base_url

The API’s base URL.

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 Modrinth’s catalogue.

Modrinth serves 100 results a page; larger limits read several pages.

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.

• offset (int) – How many results to skip.

• limit (int) – The maximum number of results to return.

Returns:

The results.

Raises:

NetworkError – Modrinth could not be reached.

Return type:

SearchResults

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']) – 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.

Return type:

Project

get_projects(

ids: Iterable[str],

*,

project_type: Literal['mod', 'modpack', 'resourcepack', 'shader'] = 'mod',

) → dict[str, Project]

Look up several projects by id or slug, in as few requests as possible.

Parameters:

• ids (Iterable[str]) – The projects’ ids or slugs.

• project_type (Literal['mod', 'modpack', 'resourcepack', 'shader']) – Not used, because Modrinth’s ids are unique across types.

Returns:

Each project Modrinth knows, keyed by the id or slug asked for. Unknown ones are left out.

Raises:

NetworkError – Modrinth could not be reached.

Return type:

dict[str, Project]

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.

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 – Modrinth could not be reached.

get_release(

release_id: str,

) → Release

Look up a release by id.

Parameters:

release_id (str) – The version’s id.

Returns:

The release.

Raises:

NetworkError – Modrinth could not be reached or does not know the id.

Return type:

Release

authors(

project: Project,

) → tuple[str, ...]

Return the members of a project’s team, the owner first.

Parameters:

project (Project) – The project.

Returns:

Their user names.

Raises:

NetworkError – Modrinth could not be reached or does not know it.

Return type:

tuple[str, …]

changelog(

release: Release,

) → str

Return what changed in a release. Modrinth changelogs are Markdown.

Parameters:

release (Release) – The release.

Returns:

The changelog, or an empty string if there is none.

Raises:

NetworkError – Modrinth could not be reached or does not know it.

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 SHA-1 hashes.

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 Modrinth knows. Other files are left out.

Raises:

• OSError – A file could not be read.

• NetworkError – Modrinth could not be reached.

• Cancelled – cancel was triggered.

Return type:

dict[Path, Release]