hyperdownloader-core 1.0.4__tar.gz

hyperdownloader_core-1.0.4/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: hyperdownloader-core
+Version: 1.0.4
+Summary: 高性能多线程下载引擎 — 完全解耦，不依赖任何 GUI 框架
+Author: HyperDownloader Team
+License: MIT
+Project-URL: Homepage, https://github.com/cyqmq/hyperDL
+Project-URL: Repository, https://github.com/cyqmq/hyperDL
+Project-URL: Bug Tracker, https://github.com/cyqmq/hyperDL/issues
+Keywords: download,downloader,multi-thread,http,concurrent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: socks
+Requires-Dist: PySocks>=1.7.1; extra == "socks"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# HyperDownloader Core
+
+> **高性能多线程下载引擎** — 完全解耦，不依赖任何 GUI 框架。
+
+## 设计目标
+
+`HyperDownloader Core` 是一个纯 Python 的多线程下载引擎，核心设计哲学是**完全解耦**：
+
+- ✅ **零 GUI 依赖** — 核心库不含任何 GUI 代码，只通过回调传递纯数据
+- ✅ **可插拔集成** — 任何 GUI 框架（Tkinter、PyQt、WxPython、Web 等）均可通过 `ProgressCallback` 驱动
+- ✅ **面向接口** — 所有 UI 交互通过 `DownloadProgress` 数据类和回调函数实现
+- ✅ **开箱即用** — `DownloadProgress` 已包含进度百分比、速度、ETA、分片状态等所有 UI 所需字段
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────┐
+│               HyperDownloader (Facade)           │
+│             核心引擎入口，用户直接交互               │
+├─────────────────────────────────────────────────┤
+│               DownloadScheduler                   │
+│       任务调度器（并发控制 / 排队 / 策略）           │
+├────────────────────┬────────────────────────────┤
+│   TaskDownloader   │   TaskDownloader            │
+│   (单任务下载器)    │   (单任务下载器)              │
+├────────┬──────────┼────────┬───────────────────┤
+│ Seg-0  │ Seg-1    │ Seg-0  │ Seg-1  │ Seg-2    │
+│ (线程) │ (线程)   │ (线程)  │ (线程) │ (线程)   │
+└────────┴──────────┴────────┴───────────────────┘
+         ↑ 回调传纯数据，不依赖任何 GUI
+    ┌──────────────────────────────────┐
+    │   任何 GUI / CLI / 其他项目      │
+    └──────────────────────────────────┘
+```
+
+## 快速开始
+
+### 安装
+
+```bash
+pip install hyperdownloader-core
+```
+
+或直接使用源码：
+
+```bash
+git clone https://github.com/cyqmq/hyperDL.git
+cd hyperDL
+pip install -r requirements.txt
+```
+
+### 基础用法
+
+```python
+from hyperdownloader import HyperDownloader, DownloadTask
+
+# 1. 创建引擎
+dl = HyperDownloader(max_concurrent=5)
+
+# 2. 定义进度回调（纯控制台输出，可替换为任何 UI 更新）
+def on_progress(progress):
+    print(f"\r{progress.progress:.1f}% - {progress.speed/1024:.1f} KB/s", end="")
+
+# 3. 创建下载任务
+task = DownloadTask(
+    url="https://example.com/large-file.zip",
+    save_dir="./downloads",
+    on_progress=on_progress,
+)
+
+# 4. 开始下载
+task_id = dl.download(task)
+
+# 5. 等待完成
+dl.wait_all()
+dl.stop()
+```
+
+### 集成到 GUI 项目（示例：Tkinter）
+
+```python
+# 完全相同的 API，只是把回调接入 Tkinter
+def on_progress(progress):
+    # progress 是纯数据对象，可驱动任何 UI
+    progress_bar["value"] = progress.progress
+    speed_label.config(text=f"{progress.speed/1024:.1f} KB/s")
+    status_label.config(text=progress.status.name)
+
+task = DownloadTask(url="...", save_dir="...", on_progress=on_progress)
+```
+
+## 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🚀 **多线程分片下载** | 支持 HTTP Range 请求，文件自动切分并发下载 |
+| ⏸️ **暂停 / 恢复** | 支持断点续传，临时文件可自动恢复 |
+| 🔄 **自动重试** | 指数退避重试策略，可配置重试次数 |
+| 📊 **速度限制** | 全局速率限制（令牌桶算法） |
+| 📋 **任务调度** | FIFO / LIFO / 优先级 三种策略 |
+| 🔌 **完全解耦** | 纯数据回调，不依赖任何 GUI 框架 |
+| 🌐 **代理支持** | HTTP / HTTPS / SOCKS5 |
+| 🧪 **可测试** | 完整单元测试覆盖 |
+
+## 深入使用
+
+### 配置项
+
+```python
+from hyperdownloader import DownloadConfig, Headers, ProxyConfig
+
+config = DownloadConfig(
+    max_segments=8,           # 最大分片数（线程数）
+    max_retries=5,            # 最大重试次数
+    retry_delay=1.0,          # 重试基秒（指数退避）
+    timeout=60.0,             # 超时时间
+    speed_limit=500_000,      # 限速 500 KB/s
+    resume=True,              # 启用断点续传
+    headers=Headers(
+        user_agent="MyApp/1.0",
+        referer="https://example.com",
+    ),
+    proxy=ProxyConfig(
+        http="http://127.0.0.1:8080",
+        https="http://127.0.0.1:8080",
+    ),
+)
+```
+
+### 调度策略
+
+```python
+from hyperdownloader import HyperDownloader, SchedulerPolicy
+
+# FIFO（先进先出，默认）
+dl = HyperDownloader(policy=SchedulerPolicy.FIFO)
+
+# LIFO（后进先出）
+dl = HyperDownloader(policy=SchedulerPolicy.LIFO)
+
+# 按优先级（高优先级任务先下载）
+dl = HyperDownloader(policy=SchedulerPolicy.PRIORITY)
+
+# 带优先级的任务
+from hyperdownloader import DownloadTask
+urgent = DownloadTask(url="...", save_dir="...", priority=10)
+normal = DownloadTask(url="...", save_dir="...", priority=0)
+```
+
+### 任务管理
+
+```python
+# 暂停
+dl.pause(task_id)
+
+# 恢复
+dl.resume(task_id)
+
+# 取消
+dl.cancel(task_id)
+
+# 查询状态
+active = dl.active_tasks       # list[DownloadTask]
+pending = dl.pending_tasks     # list[DownloadTask]
+results = dl.completed_results # list[DownloadResult]
+```
+
+## 项目结构
+
+```
+hyperdownloader-core/
+├── hyperdownloader/        # 核心库
+│   ├── __init__.py         # 包入口，导出公开 API
+│   ├── enums.py            # 枚举定义
+│   ├── models.py           # 数据模型（纯 dataclass）
+│   ├── utils.py            # 工具函数
+│   ├── segment.py          # 分片下载器
+│   ├── downloader.py       # 单任务下载器
+│   ├── scheduler.py        # 任务调度器
+│   └── core.py             # 引擎 Facade
+├── examples/               # 使用示例
+│   ├── simple_download.py  # 单文件下载
+│   └── batch_download.py   # 批量下载 + 暂停/恢复
+├── tests/                  # 单元测试
+├── pyproject.toml          # 项目配置
+└── README.md
+```
+
+## 运行测试
+
+```bash
+pytest tests/ -v
+```
+
+## 许可证
+
+MIT

hyperdownloader_core-1.0.4/README.md

@@ -0,0 +1,197 @@
+# HyperDownloader Core
+
+> **高性能多线程下载引擎** — 完全解耦，不依赖任何 GUI 框架。
+
+## 设计目标
+
+`HyperDownloader Core` 是一个纯 Python 的多线程下载引擎，核心设计哲学是**完全解耦**：
+
+- ✅ **零 GUI 依赖** — 核心库不含任何 GUI 代码，只通过回调传递纯数据
+- ✅ **可插拔集成** — 任何 GUI 框架（Tkinter、PyQt、WxPython、Web 等）均可通过 `ProgressCallback` 驱动
+- ✅ **面向接口** — 所有 UI 交互通过 `DownloadProgress` 数据类和回调函数实现
+- ✅ **开箱即用** — `DownloadProgress` 已包含进度百分比、速度、ETA、分片状态等所有 UI 所需字段
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────┐
+│               HyperDownloader (Facade)           │
+│             核心引擎入口，用户直接交互               │
+├─────────────────────────────────────────────────┤
+│               DownloadScheduler                   │
+│       任务调度器（并发控制 / 排队 / 策略）           │
+├────────────────────┬────────────────────────────┤
+│   TaskDownloader   │   TaskDownloader            │
+│   (单任务下载器)    │   (单任务下载器)              │
+├────────┬──────────┼────────┬───────────────────┤
+│ Seg-0  │ Seg-1    │ Seg-0  │ Seg-1  │ Seg-2    │
+│ (线程) │ (线程)   │ (线程)  │ (线程) │ (线程)   │
+└────────┴──────────┴────────┴───────────────────┘
+         ↑ 回调传纯数据，不依赖任何 GUI
+    ┌──────────────────────────────────┐
+    │   任何 GUI / CLI / 其他项目      │
+    └──────────────────────────────────┘
+```
+
+## 快速开始
+
+### 安装
+
+```bash
+pip install hyperdownloader-core
+```
+
+或直接使用源码：
+
+```bash
+git clone https://github.com/cyqmq/hyperDL.git
+cd hyperDL
+pip install -r requirements.txt
+```
+
+### 基础用法
+
+```python
+from hyperdownloader import HyperDownloader, DownloadTask
+
+# 1. 创建引擎
+dl = HyperDownloader(max_concurrent=5)
+
+# 2. 定义进度回调（纯控制台输出，可替换为任何 UI 更新）
+def on_progress(progress):
+    print(f"\r{progress.progress:.1f}% - {progress.speed/1024:.1f} KB/s", end="")
+
+# 3. 创建下载任务
+task = DownloadTask(
+    url="https://example.com/large-file.zip",
+    save_dir="./downloads",
+    on_progress=on_progress,
+)
+
+# 4. 开始下载
+task_id = dl.download(task)
+
+# 5. 等待完成
+dl.wait_all()
+dl.stop()
+```
+
+### 集成到 GUI 项目（示例：Tkinter）
+
+```python
+# 完全相同的 API，只是把回调接入 Tkinter
+def on_progress(progress):
+    # progress 是纯数据对象，可驱动任何 UI
+    progress_bar["value"] = progress.progress
+    speed_label.config(text=f"{progress.speed/1024:.1f} KB/s")
+    status_label.config(text=progress.status.name)
+
+task = DownloadTask(url="...", save_dir="...", on_progress=on_progress)
+```
+
+## 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🚀 **多线程分片下载** | 支持 HTTP Range 请求，文件自动切分并发下载 |
+| ⏸️ **暂停 / 恢复** | 支持断点续传，临时文件可自动恢复 |
+| 🔄 **自动重试** | 指数退避重试策略，可配置重试次数 |
+| 📊 **速度限制** | 全局速率限制（令牌桶算法） |
+| 📋 **任务调度** | FIFO / LIFO / 优先级 三种策略 |
+| 🔌 **完全解耦** | 纯数据回调，不依赖任何 GUI 框架 |
+| 🌐 **代理支持** | HTTP / HTTPS / SOCKS5 |
+| 🧪 **可测试** | 完整单元测试覆盖 |
+
+## 深入使用
+
+### 配置项
+
+```python
+from hyperdownloader import DownloadConfig, Headers, ProxyConfig
+
+config = DownloadConfig(
+    max_segments=8,           # 最大分片数（线程数）
+    max_retries=5,            # 最大重试次数
+    retry_delay=1.0,          # 重试基秒（指数退避）
+    timeout=60.0,             # 超时时间
+    speed_limit=500_000,      # 限速 500 KB/s
+    resume=True,              # 启用断点续传
+    headers=Headers(
+        user_agent="MyApp/1.0",
+        referer="https://example.com",
+    ),
+    proxy=ProxyConfig(
+        http="http://127.0.0.1:8080",
+        https="http://127.0.0.1:8080",
+    ),
+)
+```
+
+### 调度策略
+
+```python
+from hyperdownloader import HyperDownloader, SchedulerPolicy
+
+# FIFO（先进先出，默认）
+dl = HyperDownloader(policy=SchedulerPolicy.FIFO)
+
+# LIFO（后进先出）
+dl = HyperDownloader(policy=SchedulerPolicy.LIFO)
+
+# 按优先级（高优先级任务先下载）
+dl = HyperDownloader(policy=SchedulerPolicy.PRIORITY)
+
+# 带优先级的任务
+from hyperdownloader import DownloadTask
+urgent = DownloadTask(url="...", save_dir="...", priority=10)
+normal = DownloadTask(url="...", save_dir="...", priority=0)
+```
+
+### 任务管理
+
+```python
+# 暂停
+dl.pause(task_id)
+
+# 恢复
+dl.resume(task_id)
+
+# 取消
+dl.cancel(task_id)
+
+# 查询状态
+active = dl.active_tasks       # list[DownloadTask]
+pending = dl.pending_tasks     # list[DownloadTask]
+results = dl.completed_results # list[DownloadResult]
+```
+
+## 项目结构
+
+```
+hyperdownloader-core/
+├── hyperdownloader/        # 核心库
+│   ├── __init__.py         # 包入口，导出公开 API
+│   ├── enums.py            # 枚举定义
+│   ├── models.py           # 数据模型（纯 dataclass）
+│   ├── utils.py            # 工具函数
+│   ├── segment.py          # 分片下载器
+│   ├── downloader.py       # 单任务下载器
+│   ├── scheduler.py        # 任务调度器
+│   └── core.py             # 引擎 Facade
+├── examples/               # 使用示例
+│   ├── simple_download.py  # 单文件下载
+│   └── batch_download.py   # 批量下载 + 暂停/恢复
+├── tests/                  # 单元测试
+├── pyproject.toml          # 项目配置
+└── README.md
+```
+
+## 运行测试
+
+```bash
+pytest tests/ -v
+```
+
+## 许可证
+
+MIT

hyperdownloader_core-1.0.4/hyperdownloader/__init__.py

@@ -0,0 +1,47 @@
+"""
+HyperDownloader Core — 高性能多线程下载引擎
+=============================================
+完全解耦，不依赖任何 GUI 框架，可无缝集成到其他 Python 项目中。
+"""
+
+from .enums import DownloadStatus, SegmentStatus, SchedulerPolicy
+from .models import (
+    DownloadTask,
+    DownloadConfig,
+    DownloadProgress,
+    DownloadSegment,
+    DownloadResult,
+    ProxyConfig,
+    Headers,
+)
+from .utils import format_bytes, format_speed, format_time, get_downloads_folder
+from .core import HyperDownloader
+from .config_manager import AppConfig, load_config, save_config
+
+__all__ = [
+    # 枚举
+    "DownloadStatus",
+    "SegmentStatus",
+    "SchedulerPolicy",
+    # 数据模型
+    "DownloadTask",
+    "DownloadConfig",
+    "DownloadProgress",
+    "DownloadSegment",
+    "DownloadResult",
+    "ProxyConfig",
+    "Headers",
+    # 核心入口
+    "HyperDownloader",
+    # 配置管理
+    "AppConfig",
+    "load_config",
+    "save_config",
+    # 工具
+    "get_downloads_folder",
+    "format_bytes",
+    "format_speed",
+    "format_time",
+]
+
+__version__ = "1.0.4"