Modsmith Python library v0.3.6 modsmith-python

classInstance#

class Instance(
path: Path | str,
)#

A game directory whose contents come from a modpack and added projects.

Parameters:

path (Path | str) – The directory. It is created by the first sync, or by create.

path#

The directory.

classmethod create(
path: Path | str,
*,
minecraft: str,
loader: str | None = None,
loader_version: str | None = None,
) → Instance#

Start an instance that does not come from a pack.

Only the versions are recorded. Install the game and the loader with modsmith.minecraft and modsmith.loaders, then add projects with plan and add.

Parameters:

  • path (Path | str) – The directory.

  • minecraft (str) – The Minecraft version.

  • loader (str | None) – The mod loader’s name, or None for vanilla.

  • loader_version (str | None) – The mod loader’s version.

Returns:

The instance.

Raises:
Return type:

Instance

property state: InstanceState | None#

What the instance holds, or None if it is not an instance yet.

Raises:

InstanceError – The state file is corrupt.

property additions: tuple[Addition, ...]#

The projects installed on their own. Empty if this is not an instance.

Raises:

InstanceError – The state file is corrupt.

contents() → tuple[ContentFile, ...]#

List the mods, resource packs and shader packs in the instance.

Returns:

Each one, with where it came from and whether it is enabled. Use modsmith.metadata.read for its name and version.

Raises:

InstanceError – The state file is corrupt.

Return type:

tuple[ContentFile, …]

diff(
pack: Modpack,
*,
side: Literal['client', 'server'] = 'client',
include_optional: bool = False,
) → Changes#

Compare this directory with a pack. Changes nothing.

Parameters:

  • pack (Modpack) – The modpack.

  • side (Literal['client', 'server']) – The side to install.

  • include_optional (bool) – Include the pack’s optional files.

Returns:

What a sync would do.

Raises:

InstanceError – The state file is corrupt.

Return type:

Changes

sync(
pack: Modpack,
*,
side: Literal['client', 'server'] = 'client',
include_optional: bool = False,
overwrite: bool = False,
adopt_from: Iterable[Path | str] = (),
session: Session | None = None,
max_workers: int = 8,
progress: Callable[[Progress], None] | None = None,
cancel: CancelToken | None = None,
) → Changes#

Make this directory match a pack and return what changed.

Install and update are the same call. New files are downloaded to a staging directory first, so the instance is only touched once everything is ready. An interrupted sync can simply be run again, and it reuses what was already downloaded. A file whose size and modification time have not changed since the last sync is assumed to have the same contents.

Additions stay, unless the pack now provides the same project or file. Disabled files stay disabled, and are updated under their disabled name.

Parameters:

  • pack (Modpack) – The modpack.

  • side (Literal['client', 'server']) – The side to install.

  • include_optional (bool) – Include the pack’s optional files.

  • overwrite (bool) – Replace the player’s changes instead of keeping them.

  • adopt_from (Iterable[Path | str]) – Folders to search for entries that cannot be downloaded. Files are found by name and verified.

  • session (Session | None) – The session to use. A temporary one is created if omitted.

  • max_workers (int) – How many files to download at once.

  • progress (Callable[[Progress], None] | None) – Receives updates for each stage.

  • cancel (CancelToken | None) – Stops the sync. It has no effect once files are being moved into the instance.

Returns:

What changed.

Raises:

  • LockedError – Another change is using this instance.

  • UnresolvedEntriesError – Entries are still missing. Nothing has been changed.

  • InstanceError – The state file is corrupt, or a file could not be replaced, usually because the game is running. Everything is put back as it was.

  • PackError – The pack’s files are unsafe.

  • DownloadError – A file could not be downloaded.

  • Cancelled – cancel was triggered.

Return type:

Changes

plan(
platform: Platform,
items: Iterable[str | Project | Release],
*,
project_type: Literal['mod', 'modpack', 'resourcepack', 'shader'] = 'mod',
include_optional: bool = False,
release_only: bool = True,
cancel: CancelToken | None = None,
) → Plan#

Work out what adding projects would install. Changes nothing.

For a project, its newest release for the instance’s game version and loader is chosen. A release is used as given. Dependencies are found with modsmith.platforms.resolve_dependencies, and anything the pack or an earlier addition already provides counts as installed.

Parameters:

  • platform (Platform) – The platform to install from.

  • items (Iterable[str | Project | Release]) – Project ids, slugs or URLs, projects, or exact releases.

  • project_type (Literal['mod', 'modpack', 'resourcepack', 'shader']) – The kind of project the items are.

  • include_optional (bool) – Also install optional dependencies.

  • release_only (bool) – Leave out alpha and beta releases.

  • cancel (CancelToken | None) – Stops the search.

Returns:

The plan. Pass it to add.

Raises:
Return type:

Plan

plan_updates(
platform: Platform,
*,
release_only: bool = True,
cancel: CancelToken | None = None,
) → Plan#

Work out which additions from a platform have newer releases.

Pinned additions are left alone. Pass the plan to add to update.

Parameters:

  • platform (Platform) – The platform the additions came from.

  • release_only (bool) – Leave out alpha and beta releases.

  • cancel (CancelToken | None) – Stops the search.

Returns:

The plan. Additions with no release for the instance’s game version and loader are listed in unavailable.

Raises:
Return type:

Plan

add(
plan: Plan,
*,
overwrite: bool = False,
adopt_from: Iterable[Path | str] = (),
session: Session | None = None,
max_workers: int = 8,
progress: Callable[[Progress], None] | None = None,
cancel: CancelToken | None = None,
) → Changes#

Install a plan’s additions, replacing older releases of the same projects.

Files are staged and committed the same way as in sync, so a failed add leaves the instance as it was.

Parameters:

  • plan (Plan) – The plan, from plan or plan_updates.

  • overwrite (bool) – Replace files the player changed instead of keeping them.

  • adopt_from (Iterable[Path | str]) – Folders to search for files that cannot be downloaded, such as CurseForge files whose authors block other tools.

  • session (Session | None) – The session to use. A temporary one is created if omitted.

  • max_workers (int) – How many files to download at once.

  • progress (Callable[[Progress], None] | None) – Receives updates for each stage.

  • cancel (CancelToken | None) – Stops the download. It has no effect once files are being moved into the instance.

Returns:

What changed.

Raises:

  • DependencyError – The plan has conflicts or missing required dependencies. Nothing has been changed.

  • InstanceError – This is not an instance, or a file could not be replaced. Everything is put back as it was.

  • LockedError – Another change is using this instance.

  • UnresolvedEntriesError – A file has no download and was not found.

  • DownloadError – A file could not be downloaded.

  • Cancelled – cancel was triggered.

Return type:

Changes

remove(
*projects: str,
keep_dependencies: bool = False,
dry_run: bool = False,
) → Changes#

Remove additions, and the dependencies nothing else needs.

A file the player changed is kept, and listed in orphaned.

Parameters:

  • *projects (str) – Project ids, slugs or paths of additions.

  • keep_dependencies (bool) – Keep dependencies even if nothing needs them.

  • dry_run (bool) – Only work out what would change, and change nothing.

Returns:

What changed, or with dry_run, what would change.

Raises:

  • InstanceError – A name is not an addition, for example because the pack installed it, or a file could not be removed.

  • LockedError – Another change is using this instance.

Return type:

Changes

pin(
project: str,
pinned: bool = True,
) → Addition#

Keep an addition at its current release, or let it update again.

Parameters:

  • project (str) – The addition’s project id, slug or path.

  • pinned (bool) – True to pin, False to unpin.

Returns:

The changed addition.

Raises:
Return type:

Addition

adopt(
platform: Platform,
*,
progress: Callable[[Progress], None] | None = None,
cancel: CancelToken | None = None,
) → tuple[Addition, ...]#

Take over files the player put in the instance, if a platform knows them.

Untracked files in mods, resourcepacks and shaderpacks are identified by their contents. Those the platform knows become additions, so they can be updated and removed. No file is changed.

Parameters:

  • platform (Platform) – The platform to ask.

  • progress (Callable[[Progress], None] | None) – Receives an update as each file is read.

  • cancel (CancelToken | None) – Stops reading files.

Returns:

The new additions.

Raises:
Return type:

tuple[Addition, …]

enable(
*paths: str,
) → None#

Switch files back on by removing their .disabled suffix.

Parameters:

*paths (str) – Paths relative to the instance, with or without the suffix.

Raises:
disable(
*paths: str,
) → None#

Switch files off by adding the .disabled suffix, so the game skips them.

Syncs and updates keep them disabled.

Parameters:

*paths (str) – Paths relative to the instance, such as mods/sodium.jar.

Raises:
delete() → None#

Delete this instance’s directory. Refuses unmanaged directories.

Raises: