Metadata-Version: 2.4
Name: curseforge-mod-downloader
Version: 1.0.0
Summary: Simple Python library to download Minecraft mods from CurseForge
Author: Bincez
License: MIT
Project-URL: Homepage, https://github.com/easyclaw/curseforge-mod-downloader
Keywords: curseforge,minecraft,mods,downloader
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# curseforge-mod-downloader

Simple Python library to download Minecraft mods from CurseForge.

## Installation

```bash
pip install curseforge-mod-downloader
```

## Usage

### As a library

```python
import cfm_downloader as cfm

# Basic download
result = cfm.download("jei", "1.20.1")
print(result.path)       # /path/to/jei-1.20.1-forge-15.20.0.112.jar
print(result.mod_name)   # Just Enough Items (JEI)
print(result.size)       # 1385600

# Download with URL
result = cfm.download("https://www.curseforge.com/minecraft/mc-mods/create", "1.20.1")

# Filter by release type
result = cfm.download("jei", "1.20.1", release_type="beta")

# Custom output directory
result = cfm.download("jei", "1.20.1", output_dir="./mods")

# Progress callback
def on_progress(downloaded, total):
    print(f"{downloaded}/{total} ({downloaded*100/total:.1f}%)")

result = cfm.download("jei", "1.20.1", progress_callback=on_progress)

# Get available versions
versions = cfm.search_versions("jei")
print(versions)  # ['1.12.2', '1.16.5', '1.18.2', '1.19.2', '1.20.1', ...]

# Get mod info
info = cfm.mod_info("jei")
print(info["title"])    # Just Enough Items (JEI)
print(info["summary"])  # ...
```

### As a CLI tool

```bash
cfm-download jei 1.20.1
cfm-download https://www.curseforge.com/minecraft/mc-mods/create 1.20.1 --output ./mods
cfm-download jei 1.20.1 --type beta
```

## API Reference

### `cfm.download(mod, version, release_type=None, output_dir=None, progress_callback=None)`

Download a mod from CurseForge.

- **mod** — CurseForge URL, mod slug, or project ID
- **version** — Minecraft version (e.g. `"1.20.1"`)
- **release_type** — Optional: `"release"`, `"beta"`, or `"alpha"`
- **output_dir** — Directory to save the file (default: current directory)
- **progress_callback** — Optional `callable(downloaded_bytes, total_bytes)`

Returns `DownloadResult` with attributes: `path`, `file_name`, `file_id`, `mod_name`, `mc_version`, `release_type`, `size`.

### `cfm.search_versions(mod)`

Returns a list of available Minecraft versions for the mod.

### `cfm.mod_info(mod)`

Returns a dict with mod metadata (title, id, summary, versions, etc).

### `cfm.CurseForgeError`

Exception raised on any download/API error.

## License

MIT
