Metadata-Version: 2.4
Name: xes-assets
Version: 1.1.0
Summary: Zero-dependency downloader for the XES Python course asset files (RAR + ZIP): importing the library fetches them, with size and SHA-256 verification.
Author: xes-assets
License: MIT
Project-URL: Homepage, https://pypi.org/project/xes-assets/
Project-URL: Source, https://livefile.xesimg.com/programme/python_assets/
Keywords: xes,xesimg,assets,downloader,python-assets,no-dependencies,zero-dependency,sha256
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# xes-assets

零依赖下载器 / Zero-dependency downloader for the XES Python course asset files:

- `https://livefile.xesimg.com/programme/python_assets/3f51c62b04d3aacc27b0d53f294ecc3b.rar`
- `https://livefile.xesimg.com/programme/python_assets/a3635617bd88675041ba69f8398df5a0.zip`

只用 Python 标准库（`urllib`、`hashlib`、`zipfile`），**没有任何第三方依赖**。
Uses nothing but the Python standard library — **no third-party dependency at all**.

## 安装 + 导库即下载 / Install & import-to-download

```bash
pip install xes-assets
```

```python
import xes_assets          # 导入即自动下载两个文件到当前工作目录
print(xes_assets.AUTODOWNLOADED)   # [Path(...rar), Path(...zip)]
```

`import xes_assets` 会立刻把两个文件下载到**当前工作目录**（含断点续传、大小 + SHA-256 校验）；
已存在且校验通过的文件直接跳过。

| 环境变量 | 作用 |
| --- | --- |
| `XES_ASSETS_DEST` | 下载目录（默认当前工作目录） |
| `XES_ASSETS_AUTODOWNLOAD=0` | 导入时**不**下载（退回手动调用 API） |
| `XES_ASSETS_QUIET=1` | 不显示进度条 |

```python
# 指定目录导入
import os; os.environ["XES_ASSETS_DEST"] = r"D:\xes"
import xes_assets
```

导入失败（断网等）会抛 `XesAssetError` 并提示设置 `XES_ASSETS_AUTODOWNLOAD=0`。

## 命令行 / CLI

CLI **不会**触发导入时下载，只做你指定的动作：

```bash
xes-assets --list                        # 查看两个文件的信息
xes-assets zip -d D:\xes                 # 下载 ZIP
xes-assets all -d D:\xes -x              # 下载两个并解压
xes-assets rar --verify-only -d D:\xes   # 只校验已下载文件
python -m xes_assets all -d D:\xes       # 等价写法
```

| 参数 | 说明 |
| --- | --- |
| `ASSET`（位置参数） | `rar`、`zip`、`all`、文件名或 URL；省略时等于 `all` |
| `-d, --dest DIR` | 输出目录（默认当前目录） |
| `-x, --extract` | 下载后解压（RAR 需要外部解压工具，见下） |
| `-f, --overwrite` | 覆盖已存在文件 |
| `--no-verify` | 跳过 SHA-256 校验 |
| `-q, --quiet` | 不显示进度 |
| `--verify-only` | 只校验不下载 |
| `--list` | 列出已知文件 |

## Python API

```python
from xes_assets import ASSETS, download, download_all, download_on_import, extract, verify

download("zip", r"D:\xes")            # -> Path，含大小 + SHA-256 校验
download_all(r"D:\xes")               # 两个都下
download_on_import(r"D:\xes")         # 同导入行为，可指定目录
verify("rar", r"D:\xes")              # -> True/False
extract("zip", r"D:\xes")             # 标准库解压，返回目录
extract("rar", r"D:\xes")             # 需外部 7z / UnRAR（见下）
```

单个函数的行为：

- `download(key, dest=".", *, overwrite=False, verify_checksum=True, progress=None, timeout=60, retries=3)`
  先写 `<文件名>.part`，校验大小与 SHA-256 通过后才原子改名为正式文件；断点续传用 HTTP `Range`
  （服务器返回 206 时继续，否则从头开始），网络中断自动重试。
- `download_all(dest=".", *, keys=None, **kwargs)` → `List[Path]`
- `extract(key, dest=None, *, archive=None, overwrite=False)` → 解压目录 `Path`
- `verify(key, path=None, dest=".")` → `bool`
- `asset_path(key, dest=".")` → 预期的本地路径
- `AUTODOWNLOADED` 为本次导入已下载/已确认的路径列表
- `ASSETS` / `ASSET_ORDER` 为元数据常量；`XesAssetError` 为统一异常

## 文件与校验值 / Files

| key | 文件名 | 大小 | SHA-256 |
| --- | --- | --- | --- |
| `rar` | `3f51c62b04d3aacc27b0d53f294ecc3b.rar` | 568,456,521 B | `ea41b34bd193cf0039386c0cfe22f93c2225bb43ef01d69740106a35e05d7c85` |
| `zip` | `a3635617bd88675041ba69f8398df5a0.zip` | 39,463,900 B | `63fdddb6c37849606ae32d08e522bbd2a627be90971005946b6c332a7715ff93` |

校验值在主文件被上游替换前一直有效；上游变更时下载会明确报 `checksum mismatch`
（不会静默留下坏文件）。

## 关于 RAR 解压 / About RAR extraction

**下载**永远只需要标准库。**解压 `.rar`** 时本包会依次查找
`7z` / `7zz` / `7za` / `unrar` / `unar` / `bsdtar`（PATH 中或常见安装路径
`C:\Program Files\7-Zip\7z.exe`、`C:\Program Files\WinRAR\UnRAR.exe`），
找不到就抛 `XesAssetError` 并提示手工解压。ZIP 解压完全由标准库完成。

## Changelog

- **1.1.0** — `import xes_assets` 直接下载（`XES_ASSETS_DEST` / `XES_ASSETS_AUTODOWNLOAD` / `XES_ASSETS_QUIET`），新增 `download_on_import()` 与 `AUTODOWNLOADED`；CLI 不再触发导入下载。
- **1.0.0** — 首个版本：手动下载 API + CLI，断点续传、大小/SHA-256 校验。

## License

MIT
