modsmith 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
modsmith/progress.py ADDED
@@ -0,0 +1,78 @@
1
+ """Progress reporting and cancellation shared by long-running operations."""
2
+
3
+ import threading
4
+ from collections.abc import Callable
5
+ from dataclasses import dataclass
6
+
7
+ from .errors import Cancelled
8
+
9
+ __all__ = ["CancelToken", "Progress", "ProgressCallback", "report"]
10
+
11
+
12
+ @dataclass(frozen=True, slots=True)
13
+ class Progress:
14
+ """One update from a long-running operation.
15
+
16
+ Attributes:
17
+ task: The current stage, such as ``download`` or ``libraries``.
18
+ current: The units finished so far.
19
+ total: The units expected, or None if unknown.
20
+ unit: What is counted, such as ``byte``, ``file`` or ``step``.
21
+ """
22
+
23
+ task: str
24
+ current: int
25
+ total: int | None = None
26
+ unit: str = "item"
27
+
28
+
29
+ ProgressCallback = Callable[[Progress], None]
30
+
31
+
32
+ class CancelToken:
33
+ """Thread-safe flag that stops a long-running operation.
34
+
35
+ Pass it as ``cancel=`` and call `cancel` from another thread. The operation
36
+ raises `Cancelled` the next time it checks the token.
37
+ """
38
+
39
+ def __init__(self) -> None:
40
+ self._event = threading.Event()
41
+
42
+ def cancel(self) -> None:
43
+ """Request cancellation. This cannot be undone."""
44
+ self._event.set()
45
+
46
+ @property
47
+ def cancelled(self) -> bool:
48
+ """Whether cancellation has been requested."""
49
+ return self._event.is_set()
50
+
51
+ def check(self) -> None:
52
+ """Stop here if cancellation has been requested.
53
+
54
+ Raises:
55
+ Cancelled: Cancellation has been requested.
56
+ """
57
+ if self.cancelled:
58
+ raise Cancelled("Operation cancelled")
59
+
60
+
61
+ def report(
62
+ callback: ProgressCallback | None,
63
+ task: str,
64
+ current: int,
65
+ total: int | None = None,
66
+ unit: str = "item",
67
+ ) -> None:
68
+ """Send a `Progress` update if a callback was given.
69
+
70
+ Args:
71
+ callback: The callback, or None to do nothing.
72
+ task: The current stage.
73
+ current: The units finished so far.
74
+ total: The units expected, or None if unknown.
75
+ unit: What is counted.
76
+ """
77
+ if callback is not None:
78
+ callback(Progress(task, current, total, unit))
modsmith/py.typed ADDED
File without changes
@@ -0,0 +1,285 @@
1
+ Metadata-Version: 2.5
2
+ Name: modsmith
3
+ Version: 0.1.0
4
+ Summary: A Python toolkit for Minecraft modpacks, mod loaders and game instances.
5
+ Project-URL: Homepage, https://github.com/PaPa-jun/ModSmith
6
+ Project-URL: Documentation, https://papa-jun.github.io/ModSmith/
7
+ Project-URL: Issues, https://github.com/PaPa-jun/ModSmith/issues
8
+ Project-URL: Changelog, https://github.com/PaPa-jun/ModSmith/blob/main/CHANGELOG.md
9
+ Author-email: MeNeither <pengyufeng2003@outlook.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: curseforge,fabric,forge,minecraft,modpack,modrinth
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Games/Entertainment
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.12
25
+ Requires-Dist: platformdirs>=4.3
26
+ Requires-Dist: pydantic>=2.9
27
+ Requires-Dist: requests>=2.34.2
28
+ Description-Content-Type: text/markdown
29
+
30
+ <p align="center">
31
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/banner.svg" alt="Modsmith" width="100%">
32
+ </p>
33
+
34
+ <p align="center">
35
+ <strong>A Python toolkit for Minecraft modpacks, mod loaders and game instances.</strong>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="https://github.com/PaPa-jun/ModSmith/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/PaPa-jun/ModSmith/ci.yml?branch=main&style=flat-square&label=CI&logo=github" alt="CI"></a>
40
+ <a href="https://pypi.org/project/modsmith/"><img src="https://img.shields.io/pypi/v/modsmith?style=flat-square&color=3c8527" alt="PyPI"></a>
41
+ <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.12+"></a>
42
+ <a href="https://microsoft.github.io/pyright/"><img src="https://img.shields.io/badge/types-pyright%20strict-2F74C0?style=flat-square" alt="Pyright strict"></a>
43
+ <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/badge/code%20style-ruff-D7FF64?style=flat-square&logo=ruff&logoColor=black" alt="Ruff"></a>
44
+ <img src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" alt="Alpha">
45
+ <a href="https://github.com/PaPa-jun/ModSmith/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license"></a>
46
+ </p>
47
+
48
+ <p align="center">
49
+ <a href="https://papa-jun.github.io/ModSmith/">Documentation</a> · <strong>English</strong> · <a href="https://github.com/PaPa-jun/ModSmith/blob/main/README_ZH.md">简体中文</a>
50
+ </p>
51
+
52
+ ---
53
+
54
+ Modsmith is a library, not a launcher. Its small modules work together or alone, so you can build your own modpack installer, updater, CLI or GUI.
55
+
56
+ <table>
57
+ <tr>
58
+ <td width="33%" valign="top">
59
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/search.svg" alt="" width="24" height="24">
60
+ <p><strong>Two platforms, one API</strong></p>
61
+ Search and download from Modrinth and CurseForge the same way.
62
+ </td>
63
+ <td width="33%" valign="top">
64
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/package.svg" alt="" width="24" height="24">
65
+ <p><strong>Modpacks, even offline</strong></p>
66
+ Open Modrinth and CurseForge packs without a network connection.
67
+ </td>
68
+ <td width="33%" valign="top">
69
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/layers.svg" alt="" width="24" height="24">
70
+ <p><strong>Four mod loaders</strong></p>
71
+ Install Forge, NeoForge, Fabric and Quilt with one call.
72
+ </td>
73
+ </tr>
74
+ <tr>
75
+ <td valign="top">
76
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/refresh.svg" alt="" width="24" height="24">
77
+ <p><strong>Safe updates</strong></p>
78
+ Update a modpack and keep the changes players made.
79
+ </td>
80
+ <td valign="top">
81
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/cup.svg" alt="" width="24" height="24">
82
+ <p><strong>The right Java</strong></p>
83
+ Find the Java that a game version needs, or download it.
84
+ </td>
85
+ <td valign="top">
86
+ <img src="https://raw.githubusercontent.com/PaPa-jun/ModSmith/main/docs/assets/pixel/shield.svg" alt="" width="24" height="24">
87
+ <p><strong>Reliable downloads</strong></p>
88
+ Files are verified, and interrupted downloads pick up where they stopped.
89
+ </td>
90
+ </tr>
91
+ </table>
92
+
93
+ ## Installation
94
+
95
+ Modsmith needs Python 3.12 or newer. Install it from PyPI:
96
+
97
+ ```bash
98
+ pip install modsmith
99
+ ```
100
+
101
+ Or with [uv](https://docs.astral.sh/uv/):
102
+
103
+ ```bash
104
+ uv add modsmith
105
+ ```
106
+
107
+ ## Quick start
108
+
109
+ Download a modpack from Modrinth, install its loader, create an instance and add it to the official launcher:
110
+
111
+ ```python
112
+ import modsmith as ms
113
+
114
+ with ms.platforms.Modrinth("my-tool/1.0") as modrinth:
115
+ project = modrinth.get_project("fabulously-optimized")
116
+ release = next(modrinth.iter_releases(project, game_version="1.21.1"))
117
+ pack = ms.packs.load(modrinth.fetch(release, ".cache"))
118
+
119
+ game = ms.minecraft.GameDir.default()
120
+ version_id = pack.loader.install(game)
121
+
122
+ instance = ms.instances.Instance.open("instances/fabulously-optimized")
123
+ instance.sync(pack)
124
+
125
+ ms.launcher.Launcher(game).add_profile(pack.name, version_id, instance.path)
126
+ ```
127
+
128
+ Open the official launcher once before you run this, and keep it closed while it runs. To update, run `instance.sync(pack)` again with a newer pack.
129
+
130
+ ## Recipes
131
+
132
+ Every module also works alone.
133
+
134
+ <details>
135
+ <summary><b>Search for projects</b></summary>
136
+
137
+ ```python
138
+ with ms.platforms.Modrinth("my-tool/1.0") as modrinth:
139
+ results = modrinth.search("sodium", project_type="mod", loader="fabric", limit=5)
140
+
141
+ for project in results.projects:
142
+ print(project.name, project.url, project.downloads)
143
+ ```
144
+
145
+ </details>
146
+
147
+ <details>
148
+ <summary><b>Install a CurseForge modpack</b></summary>
149
+
150
+ CurseForge needs an [API key](https://console.curseforge.com/). Some mods can only be downloaded by hand. They stay in `pack.unresolved`, and `sync` can pick them up from a folder.
151
+
152
+ ```python
153
+ import os
154
+ from pathlib import Path
155
+
156
+ with ms.platforms.CurseForge(os.environ["CURSEFORGE_API_KEY"]) as curseforge:
157
+ pack = curseforge.resolve(ms.packs.load("pack.zip"))
158
+
159
+ for entry in pack.unresolved:
160
+ print(entry.manual_url)
161
+
162
+ instance.sync(pack, adopt_from=[Path.home() / "Downloads"])
163
+ ```
164
+
165
+ </details>
166
+
167
+ <details>
168
+ <summary><b>Preview an update</b></summary>
169
+
170
+ ```python
171
+ changes = instance.diff(pack) # changes nothing
172
+
173
+ print("New:", changes.added)
174
+ print("Updated:", changes.updated)
175
+ print("Removed:", changes.removed)
176
+ print("Changed by the player:", changes.conflicts)
177
+ ```
178
+
179
+ </details>
180
+
181
+ <details>
182
+ <summary><b>Install only a mod loader</b></summary>
183
+
184
+ ```python
185
+ game = ms.minecraft.GameDir.default()
186
+
187
+ ms.loaders.Fabric("0.16.10", "1.21.1").install(game)
188
+ ms.loaders.NeoForge("21.1.233", "1.21.1").install(game)
189
+ ```
190
+
191
+ </details>
192
+
193
+ <details>
194
+ <summary><b>Find a Java runtime</b></summary>
195
+
196
+ ```python
197
+ ms.minecraft.install_version(game, "1.21.1")
198
+
199
+ component = ms.java.required_for(game.version("1.21.1"), game)
200
+ runtime = ms.java.find(component, game=game) or ms.java.download(component)
201
+ print(runtime.executable)
202
+ ```
203
+
204
+ </details>
205
+
206
+ <details>
207
+ <summary><b>Show progress and cancel</b></summary>
208
+
209
+ Long-running calls accept `progress=` and `cancel=`, so they are easy to connect to a GUI.
210
+
211
+ ```python
212
+ token = ms.CancelToken() # call token.cancel() from any thread
213
+
214
+
215
+ def show(event: ms.Progress) -> None:
216
+ print(f"{event.task}: {event.current}/{event.total} {event.unit}")
217
+
218
+
219
+ instance.sync(pack, progress=show, cancel=token)
220
+ ```
221
+
222
+ </details>
223
+
224
+ <details>
225
+ <summary><b>Handle errors</b></summary>
226
+
227
+ Every error derives from `ModsmithError`.
228
+
229
+ ```python
230
+ from modsmith.errors import ModsmithError
231
+
232
+ try:
233
+ instance.sync(pack)
234
+ except ModsmithError as error:
235
+ print(f"Sync failed: {error}")
236
+ ```
237
+
238
+ </details>
239
+
240
+ ## How it fits together
241
+
242
+ Platforms, pack formats and mod loaders are independent, and you can add your own.
243
+
244
+ | Module | Provides |
245
+ | :--- | :--- |
246
+ | `modsmith.platforms` | `Modrinth`, `CurseForge` and the `Platform` base class |
247
+ | `modsmith.packs` | `load()`, `Modpack`, and the mrpack and CurseForge formats |
248
+ | `modsmith.loaders` | `Forge`, `NeoForge`, `Fabric`, `Quilt` and the `Loader` base class |
249
+ | `modsmith.instances` | `Instance`, with `diff()` and `sync()` |
250
+ | `modsmith.minecraft` | `GameDir`, `Version` and vanilla version downloads |
251
+ | `modsmith.java` | Runtime lookup and Mojang runtime downloads |
252
+ | `modsmith.launcher` | Official launcher profiles |
253
+ | `modsmith.net` | `Session`, `Resource` and `download()` |
254
+ | `modsmith.errors` | `ModsmithError` and its subclasses |
255
+
256
+ ## Compatibility
257
+
258
+ | | Supported |
259
+ | :--- | :--- |
260
+ | Python | 3.12 and later |
261
+ | Operating systems | Windows, macOS and Linux |
262
+ | Platforms | Modrinth and CurseForge |
263
+ | Modpack formats | `.mrpack` and CurseForge `.zip` |
264
+ | Launcher | Official Minecraft Launcher, including the Microsoft Store version |
265
+
266
+ | Loader | Minecraft versions |
267
+ | :--- | :--- |
268
+ | Forge | 1.13.2 and later |
269
+ | NeoForge | 1.20.1 and later |
270
+ | Fabric | 1.14 and later |
271
+ | Quilt | 1.14.4 and later |
272
+
273
+ ## Scope and status
274
+
275
+ Modsmith works alongside the official launcher. It does not sign in to accounts or start the game.
276
+
277
+ The project is in alpha, so the API may change. No automated test starts the game yet. A command-line tool and a desktop app are planned.
278
+
279
+ ## Contributing
280
+
281
+ Contributions are welcome. See [CONTRIBUTING.md](https://github.com/PaPa-jun/ModSmith/blob/main/CONTRIBUTING.md) to get started.
282
+
283
+ ## License
284
+
285
+ Modsmith is released under the [MIT License](https://github.com/PaPa-jun/ModSmith/blob/main/LICENSE). It is not affiliated with Mojang, Microsoft, Modrinth or CurseForge.
@@ -0,0 +1,33 @@
1
+ modsmith/__init__.py,sha256=6x_AOlpwtXzexsEIKdnYbeOybKU4umm9w0-Ul6hDLBs,597
2
+ modsmith/_support.py,sha256=pVF159jnaGgKz_riH-xqEt0DhBW1g5dJzNl5f84m-t0,2302
3
+ modsmith/errors.py,sha256=rwgUm1sYb6tB4vtPrUMnst9DAlyE44FKEKhALLkezM4,2759
4
+ modsmith/instances.py,sha256=HTZC48htB-fGt8uQxg87vEXFxQBmLjC644e91I7_Q3s,19023
5
+ modsmith/java.py,sha256=5PP97iZPQBxw_AZOe59lhX0NGnc2w192x2XY2tci1EU,10192
6
+ modsmith/launcher.py,sha256=MzQOJ43VjLGFh2COi6kLCtxBsBvJSuL0GmQteZTvKKg,8119
7
+ modsmith/progress.py,sha256=mQc2T9O1HcfD8EdeJDbzvz1bGeHMzo1CBfxDYx0vvSc,2104
8
+ modsmith/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
9
+ modsmith/loaders/__init__.py,sha256=_N226KJOj_yWgowGp2-z5MyJoa8ltc4lIl5KPjKPdNk,553
10
+ modsmith/loaders/_base.py,sha256=mEdwJHryR1Ifx6mgmckTQexT-_MPKOSaZEw8g8hyUmk,4698
11
+ modsmith/loaders/_fabric.py,sha256=gHsvbUZEMKzlJR98j38K8CqiUqVbnQesj4tZgP-EbQY,5538
12
+ modsmith/loaders/_forge.py,sha256=YTXhZwnEQNBi8-u7T_MkGZFnOGp0dgP29tQVmi5EPWY,12159
13
+ modsmith/loaders/_install_profile.py,sha256=3jiAbAi3nX_jK5_KhPEl92Woh6_IDelcsr8cUGB_-EA,11380
14
+ modsmith/loaders/_processors.py,sha256=UAy_x58E7FLFWar76PD4ezjdc0aCymycWDqju0AujuU,7319
15
+ modsmith/minecraft/__init__.py,sha256=_tCR6cNDDSHQ5m36lYl9JPSLJwqu6ep-PP5ghcTYEy8,358
16
+ modsmith/minecraft/_game_dir.py,sha256=nFpPJIPHRfu6Q_QcY8KNjCa3tJXfJNj5Wf1wLLGmNUY,5584
17
+ modsmith/minecraft/_maven.py,sha256=ax5GncoSEBSCoBZI-wLZRHanqsRH1bvs6P2yXveJgpI,2096
18
+ modsmith/minecraft/_remote.py,sha256=ROzV1_OfAnzgNSaM2-LZSoSCYCTqKr6JkhrVlAV5bNY,3673
19
+ modsmith/net/__init__.py,sha256=1pt9QbWTTZyqsK9SH2sP3hKrGwLIZZiraVsTfDHB99k,219
20
+ modsmith/net/_download.py,sha256=TJBTOz4dZoiO_9S8ExmWe8M7Rtt7Ty0qRiYwZQneBPQ,8864
21
+ modsmith/net/_resource.py,sha256=h4KZCfvtvMl4SPxsu8rIE-U297bmEm0mLgPmXW1TFEQ,3285
22
+ modsmith/net/_session.py,sha256=xfv-TfLZwKs6wRpGhApQjzUpH96Jk_pPUDNJxbRc7YU,7852
23
+ modsmith/packs/__init__.py,sha256=nsXB84dPnJB6u3hz55Eh78R-xlFunRKRN3wO_hNqYjA,417
24
+ modsmith/packs/_formats.py,sha256=3ZiNwMLskF8HFc9PTOpf6x8RugFw8DAPGz7H7owkDqA,7964
25
+ modsmith/packs/_model.py,sha256=zsyifQ_Q3r-wvfP258_rg6h1aXr68aOFRQfZQohPBIg,8210
26
+ modsmith/platforms/__init__.py,sha256=5vGLgFgkJ0wWbjG6gZE4ibjwhYDx4owMHaxDfQlp6AY,454
27
+ modsmith/platforms/_base.py,sha256=P2FJu3zgwNDYKpO5m5bRjiKfqGT_L2J2kRVfMdcHXMg,8927
28
+ modsmith/platforms/_curseforge.py,sha256=wtU-mmCH5EH109cmlMKJPXyphji607M1joJdaEcHhTA,12865
29
+ modsmith/platforms/_modrinth.py,sha256=CIBo3-W3Qr5CRf3dPGcPVZ2_U6AiubxqW5Q8pd965cI,7765
30
+ modsmith-0.1.0.dist-info/METADATA,sha256=hydY36tWlAnVMLtUzSOfVUFEBFzHbBjXD-nGCFs2PDg,10074
31
+ modsmith-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
32
+ modsmith-0.1.0.dist-info/licenses/LICENSE,sha256=qHokVf-Kk3sukgcwuGaKF6RLeOfqj0dK6r_gJ96AKIE,1066
33
+ modsmith-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MeNeither
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.