pygpu-scheduling 0.1.0__tar.gz

pygpu_scheduling-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+runs/
+.env
+.env.*
+.pypirc

pygpu_scheduling-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

pygpu_scheduling-0.1.0/AGENTS.md

@@ -0,0 +1,33 @@
+# 项目约定
+
+PyGPUScheduling 是独立的单机 CPU/NVIDIA GPU 调度库，运行时核心只依赖 Python 标准库。
+
+## 开始工作
+
+- 先读 `README.md`、`docs/api.md` 和 `docs/maintaining.md`。
+- 环境：`uv sync --locked`。
+- 检查：`uv run python scripts/check_project.py`、`uv run pytest`。
+- 构建：`uv build --no-sources`。
+- 安装包验证：按 `docs/maintaining.md` 运行 wheel 和 sdist 冒烟测试。
+
+## 代码边界
+
+- 不在代码中留下注释；文档使用清楚、简洁的中文。
+- 保持高可读、高复用、高维护、低耦合和高内聚。
+- 核心在 `src/task_scheduling`；公共导出在 `__init__.py`。
+- 不引入 Torch、Optuna、模型注册表、训练配置或具体产物协议。
+- 业务规则由外部 `TaskHandler` 和事件订阅者实现。
+- 保持核心运行时依赖为空，进度显示依赖只能作为可选 extra。
+- 任务定义、处理器名称、订阅者名称和事件 ID 是恢复契约。
+- 更新状态文件格式时必须说明旧状态的兼容与迁移方式。
+- 示例放 `examples`，通用测试放 `tests`，维护工具放 `scripts`。
+- 不把业务仓库的模型测试、数据或账号配置复制进来。
+
+## 文档与版本
+
+- README 保留定位、安装和最小示例，API 细节只在 `docs/api.md` 维护。
+- 开发、发布与剩余账号配置只在 `docs/maintaining.md` 维护。
+- 版本唯一来源是 `pyproject.toml`；发布 tag 必须等于 `v<version>`。
+- 开发未发布的变化记录在 `CHANGELOG.md` 的 `Unreleased`。
+- 不自动移动已发布 tag，不把本地路径依赖作为正式发布来源。
+- 当前交接状态及下一步见 `docs/maintaining.md#当前交接状态`。

pygpu_scheduling-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 变更记录
+
+## Unreleased
+
+## 0.1.0 — 2026-11-11
+
+- 从 DMMBaseline 的 `2781c6a` 提取独立调度核心，保持源码行为与导入名。
+- 分发包命名为 `pygpu-scheduling`，采用 MIT 许可证。
+- 支持任务依赖、动态提交、GPU 显存预算、重试、状态恢复和生命周期处理器。
+- 补充独立测试、示例、uv 开发环境及 GitHub Actions 构建与发布流程。
+- 补齐公开仓库的包元数据与 README 链接，精简维护和接入说明。

pygpu_scheduling-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyGPUScheduling contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygpu_scheduling-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: pygpu-scheduling
+Version: 0.1.0
+Summary: Reusable local CPU and NVIDIA GPU task scheduling with dependency graphs and recovery hooks
+Project-URL: Source, https://github.com/AllanJinYosoro/PyGPUScheduling
+Project-URL: Issues, https://github.com/AllanJinYosoro/PyGPUScheduling/issues
+Project-URL: Changelog, https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/CHANGELOG.md
+Author: PyGPUScheduling contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gpu,nvidia,scheduler,subprocess,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.66; extra == 'progress'
+Description-Content-Type: text/markdown
+
+# PyGPUScheduling
+
+单机 CPU 与 NVIDIA GPU 任务调度库。业务注册任务、依赖和生命周期处理器，调度器管理资源准入、子进程、重试及恢复。运行时仅依赖 Python 标准库，交互式进度条可选安装 `tqdm`。
+
+分发包名为 `pygpu-scheduling`，Python 导入名为 `task_scheduling`。发布状态见[维护指南](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md#当前交接状态)。
+
+## 环境与安装
+
+需要 Python 3.11 或更新版本及 POSIX 系统。GPU 功能通过 `nvidia-smi` 工作，需要 NVIDIA 驱动；调度库不要求安装 CUDA Toolkit、Torch 或 Optuna。每个 GPU 任务使用一张卡，CPU 任务不查询 GPU。
+
+在本仓库开发：
+
+```bash
+uv sync --locked
+uv run pytest
+uv run python examples/basic.py
+```
+
+需要交互式进度条时：
+
+```bash
+uv sync --locked --extra progress
+```
+
+在其他项目中安装：
+
+```bash
+uv add "pygpu-scheduling>=0.1.0,<0.2.0"
+```
+
+GitHub 固定 tag 接入及本地联调方式见[维护指南](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md#业务仓库接入)。
+
+## 注册任务
+
+```python
+import sys
+
+from task_scheduling import Scheduler, Scheduling, TaskSpec
+
+scheduler = Scheduler("runs/example", Scheduling(max_parallel_tasks=2))
+scheduler.submit_many([
+    TaskSpec("prepare", "command", payload={"args": [sys.executable, "prepare.py"]}),
+    TaskSpec("train", "command", dependencies=("prepare",),
+             payload={"args": [sys.executable, "train.py"]}),
+])
+records = scheduler.run()
+```
+
+`command` 是按退出码判定结果的内置处理器。`run()` 返回全部任务记录，调用方检查 `complete`、`failed`、`blocked` 等状态并决定业务退出码。
+
+GPU 任务通过 `resources=ResourceRequest("cuda", 4096)` 声明 4096 MiB 预算。预算用于启动准入，不是显存硬限制。调度器不解释模型、训练轮数、业务参数或产物文件。
+
+## 功能与边界
+
+- 静态依赖图与动态追加任务，拒绝缺失依赖、重复定义和依赖环。
+- 按优先级、显存预算和提交顺序选择任务，支持共享或独占 GPU。
+- 启动前预留显存，结合实际进程占用更新预算，保留每卡安全余量。
+- 子进程日志、超时、有限重试、GPU 冷却和故障隔离。
+- 注册 `prepare`、`assess`、`commit`、`recover`，由业务提供校验及产物流程。
+- 持久化任务状态，完成事件按至少一次语义重放。
+
+当前提供单机本地子进程执行，不包含多机、抢占或单任务多卡调度。预算账本属于单个调度实例；跨实例不会合并预算。更完整的约束见[API 与恢复协议](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/api.md)。
+
+## 文档与示例
+
+- [API、调度策略和恢复协议](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/api.md)
+- [开发与发布](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md)
+- [变更记录](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/CHANGELOG.md)
+- [依赖顺序示例](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/examples/basic.py)
+- [业务产物处理示例](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/examples/artifacts.py)
+
+采用 [MIT 许可证](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/LICENSE)。

pygpu_scheduling-0.1.0/README.md

@@ -0,0 +1,72 @@
+# PyGPUScheduling
+
+单机 CPU 与 NVIDIA GPU 任务调度库。业务注册任务、依赖和生命周期处理器，调度器管理资源准入、子进程、重试及恢复。运行时仅依赖 Python 标准库，交互式进度条可选安装 `tqdm`。
+
+分发包名为 `pygpu-scheduling`，Python 导入名为 `task_scheduling`。发布状态见[维护指南](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md#当前交接状态)。
+
+## 环境与安装
+
+需要 Python 3.11 或更新版本及 POSIX 系统。GPU 功能通过 `nvidia-smi` 工作，需要 NVIDIA 驱动；调度库不要求安装 CUDA Toolkit、Torch 或 Optuna。每个 GPU 任务使用一张卡，CPU 任务不查询 GPU。
+
+在本仓库开发：
+
+```bash
+uv sync --locked
+uv run pytest
+uv run python examples/basic.py
+```
+
+需要交互式进度条时：
+
+```bash
+uv sync --locked --extra progress
+```
+
+在其他项目中安装：
+
+```bash
+uv add "pygpu-scheduling>=0.1.0,<0.2.0"
+```
+
+GitHub 固定 tag 接入及本地联调方式见[维护指南](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md#业务仓库接入)。
+
+## 注册任务
+
+```python
+import sys
+
+from task_scheduling import Scheduler, Scheduling, TaskSpec
+
+scheduler = Scheduler("runs/example", Scheduling(max_parallel_tasks=2))
+scheduler.submit_many([
+    TaskSpec("prepare", "command", payload={"args": [sys.executable, "prepare.py"]}),
+    TaskSpec("train", "command", dependencies=("prepare",),
+             payload={"args": [sys.executable, "train.py"]}),
+])
+records = scheduler.run()
+```
+
+`command` 是按退出码判定结果的内置处理器。`run()` 返回全部任务记录，调用方检查 `complete`、`failed`、`blocked` 等状态并决定业务退出码。
+
+GPU 任务通过 `resources=ResourceRequest("cuda", 4096)` 声明 4096 MiB 预算。预算用于启动准入，不是显存硬限制。调度器不解释模型、训练轮数、业务参数或产物文件。
+
+## 功能与边界
+
+- 静态依赖图与动态追加任务，拒绝缺失依赖、重复定义和依赖环。
+- 按优先级、显存预算和提交顺序选择任务，支持共享或独占 GPU。
+- 启动前预留显存，结合实际进程占用更新预算，保留每卡安全余量。
+- 子进程日志、超时、有限重试、GPU 冷却和故障隔离。
+- 注册 `prepare`、`assess`、`commit`、`recover`，由业务提供校验及产物流程。
+- 持久化任务状态，完成事件按至少一次语义重放。
+
+当前提供单机本地子进程执行，不包含多机、抢占或单任务多卡调度。预算账本属于单个调度实例；跨实例不会合并预算。更完整的约束见[API 与恢复协议](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/api.md)。
+
+## 文档与示例
+
+- [API、调度策略和恢复协议](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/api.md)
+- [开发与发布](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/docs/maintaining.md)
+- [变更记录](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/CHANGELOG.md)
+- [依赖顺序示例](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/examples/basic.py)
+- [业务产物处理示例](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/examples/artifacts.py)
+
+采用 [MIT 许可证](https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/LICENSE)。

pygpu_scheduling-0.1.0/docs/api.md

@@ -0,0 +1,106 @@
+# API 与恢复协议
+
+## 职责
+
+调用方声明任务、依赖、资源需求、业务参数和处理器。调度器只负责依赖约束、资源准入、执行状态及事件，不解释业务参数中的内容。
+
+子进程是执行边界；生命周期方法在调度进程内执行，应保持简短。训练、转换文件等耗时操作应由 `prepare` 返回的命令完成。
+
+## 公共对象
+
+| 对象 | 用途 |
+| --- | --- |
+| `Scheduler` | 注册处理器、提交任务、订阅事件、运行与恢复 |
+| `Scheduling` | GPU 筛选、并发、重试、查询间隔等全局策略 |
+| `TaskSpec` | 稳定 ID、处理器、显示名、JSON 参数、依赖、优先级和资源需求 |
+| `ResourceRequest` | `cpu` 或 `cuda`，以及单进程显存预算 |
+| `Command` | 命令参数列表、工作目录和环境变量 |
+| `TaskContext` | 任务、根目录、当前状态、历史尝试以及最近一次的目录与 GPU |
+| `Assessment` | 成功与否、能否重试、失败种类和信息 |
+| `Recovery` | 外部校验后的恢复状态和 JSON 结果 |
+| `TaskEvent` | 稳定事件 ID、任务、终态、历史尝试和业务发布结果 |
+| `TaskRecord` | 任务快照、执行状态、尝试、结果和事件确认记录 |
+| `LocalRuntime` | 本地子进程运行与可注入的 GPU 查询、停止操作 |
+
+`TaskSpec` 的 `id`、`handler` 和 `name` 必须是非空字符串，`payload` 必须是可序列化的 JSON 对象。`dependencies` 是任务 ID 序列，`priority` 是整数。资源默认 `ResourceRequest("cpu", 0)`，GPU 任务应显式给出预算。
+
+`Command.args` 是非空字符串序列；不经过 shell。`cwd` 省略时沿用调度进程的工作目录，`env` 用于覆盖继承的环境变量。核心最终设置 `CUDA_VISIBLE_DEVICES`，GPU 子进程只看到分配到的卡，CPU 子进程看不到 GPU。
+
+## 注册、依赖和顺序
+
+```python
+from task_scheduling import CommandHandler, Scheduler
+
+scheduler = Scheduler("runs/workflow")
+scheduler.register_handler("custom", CommandHandler())
+scheduler.subscribe("workflow", on_finished)
+scheduler.submit_many(tasks)
+records = scheduler.run()
+```
+
+同一批任务可向前引用依赖；依赖必须存在且不能形成环。批量校验失败时不提交这一批任务。相同 ID 和业务定义可重复提交；改变处理器、参数或依赖会报错。显示名、优先级和资源可以在任务未执行时调整，执行中的任务不能更换定义。
+
+同层任务按优先级降序、显存预算降序及提交顺序选择。显存不足时继续尝试后续可放入的小任务。依赖全部 `complete` 后任务才会启动，前置任务最终 `failed` 或 `blocked` 时，下游成为 `blocked`。严格先后关系使用依赖表达。
+
+## 生命周期处理器
+
+自定义处理器实现 `TaskHandler` 协议，也可继承 `CommandHandler` 覆盖部分方法：
+
+| 方法 | 契约 |
+| --- | --- |
+| `prepare(context)` | 检查输入、准备尝试目录，返回 `Command` |
+| `assess(context, outcome)` | 检查退出码与业务产物，返回 `Assessment` |
+| `commit(context)` | 幂等发布产物，返回可序列化的 JSON 对象 |
+| `recover(context)` | 检查旧产物及旧状态，决定恢复或重新执行 |
+
+`context.attempts` 是历史快照，可能为空。`context.directory` 返回最近一次尝试目录，没有尝试时返回调度根目录；`context.gpu` 返回 GPU UUID 或 `None`。
+
+设备丢失和超时由核心直接判定为可重试失败；普通退出会交给 `assess`，内置处理器以退出码 0 为成功。处理器自身抛错会停止调度并保留现场，不会当成业务失败自动消耗重试预算。
+
+业务产物完整示例见 [`examples/artifacts.py`](../examples/artifacts.py)。
+
+## 状态与恢复
+
+成功流程为 `pending → running → committing → complete`。核心先保存 `committing`，再调用业务发布方法。失败根据 `Assessment.retryable` 和剩余预算回到 `pending` 或进入 `failed`，中断尝试记录为 `interrupted`，不消耗失败重试次数。
+
+`recover` 可返回：
+
+- `Recovery("complete", result)`：业务确认已经完成，复用结果。
+- `Recovery("committing")`：计算已结束，继续调用幂等 `commit`。
+- `Recovery("failed")`：业务确认永久失败。
+- `None`：按已保存的失败次数及可重试标记重新排队。
+
+已有 `complete` 或 `committing` 状态无法恢复时应抛错，不能静默覆盖已发布结果。业务自己定义数据身份、文件校验及发布流程。内置命令处理器仅依靠保存的成功状态恢复，不检查业务文件。
+
+`scheduler.json` 当前格式版本为 1，保存任务定义、尝试与事件确认信息；`scheduler.lock` 防止同一运行目录被重复调度。每次尝试目录包含 `worker.log`，以及 worker 选择上报的 `progress.json`。保留完整运行目录，并在恢复时重新注册同名处理器和订阅者。Python 函数、对象和闭包不写入状态文件。
+
+`with Scheduler(...) as scheduler` 可显式控制锁持有范围；`reconcile()` 在持锁会话中恢复任务。`import_records()` 用于调用方迁入已有通用记录，只允许在尚无状态的新调度器中导入。状态包含绝对尝试路径，当前不承诺运行目录搬迁后仍可恢复。
+
+## 完成事件与动态任务
+
+`subscribe(name, listener)` 接收 `complete`、`failed`、`blocked` 终态事件。订阅回调可继续提交任务；新任务必须使用稳定 ID。
+
+事件按至少一次语义交付：回调成功返回后才保存确认信息，期间中断会重复投递相同事件 ID。调用方按事件 ID 幂等更新业务状态。`observe(callback)` 提供通用状态快照，适合导出报告，不具有终态事件的确认语义。
+
+## 策略默认值
+
+| 字段 | 默认值及含义 |
+| --- | --- |
+| `allowed_gpus` | `None`，使用所有可见 GPU；可用索引或 `GPU-` UUID 前缀限制 |
+| `min_free_memory_mib` | 4096，底层 `eligible` 可用性查询的默认门槛；任务自身使用显式资源预算 |
+| `memory_margin_mib` | 0，每卡预留的安全余量 |
+| `max_parallel_tasks` | 3，同时运行的 worker 总数 |
+| `require_idle` | `False`，允许共享 GPU；`True` 要求空闲卡并使用独占锁 |
+| `max_retries` | 3，可重试失败后的额外尝试次数 |
+| `poll_interval_seconds` | 10，GPU 查询间隔 |
+| `gpu_cooldown_seconds` | 60，GPU 普通失败后的冷却时间 |
+| `task_timeout_seconds` | 0，关闭单次任务超时 |
+| `wait_seconds` | 3600，无运行任务时等待 GPU 的时限 |
+
+GPU 筛选同时遵守父进程 `CUDA_VISIBLE_DEVICES`。多卡可选时优先避开上次失败的卡，再选择剩余可调度容量最小的卡。查询失败时暂停启动新的 GPU 任务；设备连续两次查询消失后停止对应 worker 并隔离该卡。
+
+可调度容量为实际空闲显存减去安全余量，再减去每个本实例运行任务尚未实际占用的预算。启动前预留完整预算，按 PID 查询实际显存以避免重复扣减。进程显存未知时保留完整预留。预算是准入策略，不是显存硬限制；多实例不共享预算，外部进程后续增长不受此预算约束。
+
+## 进度
+
+核心设置 `TASK_PROGRESS_FILE`。worker 可向对应路径原子写入 JSON，字段为 `current`、`total`、`phase`、`unit`。没有上报时显示初始化状态。TTY 且安装 `tqdm` 时使用交互式显示，其余情况输出状态和心跳日志。

pygpu_scheduling-0.1.0/docs/maintaining.md

@@ -0,0 +1,85 @@
+# 开发与发布
+
+## 开发验证
+
+```bash
+uv sync --locked
+uv run python scripts/check_project.py
+uv run pytest
+uv run python examples/basic.py
+uv run python examples/artifacts.py
+uv build --no-sources
+uv run --isolated --no-project --with dist/*.whl python scripts/smoke_test.py
+uv run --isolated --no-project --with dist/*.tar.gz python scripts/smoke_test.py
+```
+
+`uv.lock` 固定开发及 CI 环境，业务仓库维护自己的锁文件。CI 在 Ubuntu 上测试 Python 3.11–3.14，并单独验证 wheel 和 sdist。`check_project.py` 检查语法、无代码注释、核心导入边界、元数据与文档本地链接；`smoke_test.py` 验证安装包的版本、CPU 依赖顺序、动态任务和恢复。
+
+## 版本与发布
+
+版本唯一来源为 `pyproject.toml`，tag 必须为 `v<version>`。已发布 tag 不移动，同一版本不使用不同内容重新发布。
+
+- `0.1.x` 保持首批接口和状态格式兼容，patch 用于兼容错误修复。
+- 开发阶段的接口调整使用新的 minor，并在变更记录明确说明。
+- 稳定后发布 `1.0.0`，此后遵循语义化版本。
+- 恢复兼容范围包括任务定义、处理器和订阅者名称、事件语义及 `scheduler.json` 格式；格式变化必须说明旧状态的兼容与迁移方式并验证恢复。
+
+仓库为 [AllanJinYosoro/PyGPUScheduling](https://github.com/AllanJinYosoro/PyGPUScheduling)。开发变化写入 `CHANGELOG.md` 的 `Unreleased`。每次发布按顺序执行：
+
+1. 用 `uv version <version>` 更新版本及锁文件，将变化归入带实际日期的版本段。
+2. 完成开发验证，提交并推送 `main`，确认该提交的 [CI](https://github.com/AllanJinYosoro/PyGPUScheduling/actions/workflows/ci.yml) 全部通过。
+3. 检查 tag 与版本一致后创建并推送 tag，以 `0.1.0` 为例：
+
+```bash
+uv run python scripts/check_release.py v0.1.0
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+4. 确认 [发布工作流](https://github.com/AllanJinYosoro/PyGPUScheduling/actions/workflows/release.yml) 成功，再从 PyPI 独立安装对应版本运行 `scripts/smoke_test.py`，核对 PyPI 的版本、文件及仓库链接。更新本页交接状态。
+
+`release.yml` 验证 tag、运行测试、构建并验证分发包，再由独立 publish job 使用 OIDC 上传。只有 publish job 具有 `id-token: write`；无需长期 PyPI token。源码、wheel 与 tag 必须来自同一提交。
+
+## PyPI 账号配置
+
+发布使用以下绑定；迁移仓库或工作流时同步更新两端：
+
+- [GitHub Environments](https://github.com/AllanJinYosoro/PyGPUScheduling/settings/environments)：`pypi`，仅允许 `v*` tag 部署。
+- PyPI Trusted Publisher：绑定字段如下。
+
+| 字段 | 值 |
+| --- | --- |
+| PyPI project name | `pygpu-scheduling` |
+| GitHub owner | `AllanJinYosoro` |
+| Repository | `PyGPUScheduling` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+新项目在 [PyPI Publishing](https://pypi.org/manage/account/publishing/) 添加 Pending Publisher，首次成功上传后自动转为普通绑定。已有项目在项目设置中管理 Trusted Publisher。不把凭证写入仓库。
+
+参考：[PyPI 首次项目与 Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)、[uv 发布指南](https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi)。
+
+## 业务仓库接入
+
+声明版本依赖：
+
+```bash
+uv add "pygpu-scheduling>=0.1.0,<0.2.0"
+uv sync --locked
+```
+
+也可使用已发布的固定 GitHub tag：
+
+```bash
+uv add git+https://github.com/AllanJinYosoro/PyGPUScheduling.git --tag v0.1.0
+```
+
+联调时使用 `uv add --editable ../PyGPUScheduling`，提交业务仓库前恢复远程版本依赖，一同提交 `pyproject.toml` 与 `uv.lock`。迁移旧 `task-scheduling` 依赖时先移除旧分发包，避免两个包同时提供 `task_scheduling` 导入名；业务适配层留在调用方仓库。
+
+## 当前交接状态
+
+- 正在发布 `0.1.0`；初始核心来源记录在 `CHANGELOG.md`。
+- GitHub 初始提交 `da3ad57` 的 Python 3.11–3.14 及安装包 [CI 已通过](https://github.com/AllanJinYosoro/PyGPUScheduling/actions/runs/42968843208)，远程尚无 tag；发布准备改动仍需推送并确认对应 CI。
+- 本地项目检查、版本检查、Python 3.11 下 29 项测试、两个示例、构建及 wheel/sdist 独立安装冒烟测试通过。
+- GitHub 登录和仓库管理权限已核验；账号所有者已确认添加 PyPI Pending Publisher，等待首次 OIDC 上传验证。
+- GPU 实机尚未验证；现有测试覆盖 CPU 子进程和模拟 GPU 行为。下游业务仓库迁移另行处理；本项目不维护独立 Agent 记忆。

pygpu_scheduling-0.1.0/examples/artifacts.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+import sys
+
+from task_scheduling import Assessment, Command, CommandHandler, Recovery, Scheduler, TaskSpec
+
+
+class TextArtifactHandler(CommandHandler):
+    def prepare(self, context):
+        artifact = context.directory / "artifact.txt"
+        content = context.task.payload["content"]
+        script = f"from pathlib import Path; Path({str(artifact)!r}).write_text({content!r})"
+        return Command((sys.executable, "-c", script))
+
+    def assess(self, context, outcome):
+        execution = super().assess(context, outcome)
+        if not execution.success:
+            return execution
+        artifact = context.directory / "artifact.txt"
+        valid = artifact.is_file() and artifact.read_text() == context.task.payload["content"]
+        return Assessment(valid, False, "artifact", "artifact content validation")
+
+    def commit(self, context):
+        output = Path(context.task.payload["output"])
+        if output.exists():
+            if output.read_text() != context.task.payload["content"]:
+                raise ValueError("Published artifact content changed")
+        else:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            (context.directory / "artifact.txt").replace(output)
+        return {"output": str(output)}
+
+    def recover(self, context):
+        output = Path(context.task.payload["output"])
+        if output.exists():
+            if output.read_text() != context.task.payload["content"]:
+                raise ValueError("Published artifact content changed")
+            return Recovery("complete", {"output": str(output)})
+        if context.attempts:
+            artifact = context.directory / "artifact.txt"
+            if artifact.is_file() and artifact.read_text() == context.task.payload["content"]:
+                return Recovery("committing")
+        if context.status in {"complete", "committing"}:
+            raise ValueError("Completed artifact is missing")
+        return None
+
+
+def main():
+    root = Path("runs/artifacts").resolve()
+    scheduler = Scheduler(root / "queue")
+    scheduler.register_handler("text", TextArtifactHandler())
+    scheduler.submit(TaskSpec("publish-text", "text", payload={
+        "content": "Artifact lifecycle completed\n", "output": str(root / "published.txt")
+    }))
+    record, = scheduler.run()
+    print(record.result)
+    return 0 if record.status == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pygpu_scheduling-0.1.0/examples/basic.py

@@ -0,0 +1,20 @@
+import sys
+
+from task_scheduling import Scheduler, Scheduling, TaskSpec
+
+
+def main():
+    scheduler = Scheduler("runs/basic", Scheduling(max_parallel_tasks=2))
+    scheduler.submit_many([
+        TaskSpec("first", "command", payload={"args": [sys.executable, "-c", "print('first completed')"]}),
+        TaskSpec("second", "command", dependencies=("first",),
+                 payload={"args": [sys.executable, "-c", "print('second completed')"]}),
+    ])
+    records = scheduler.run()
+    for record in records:
+        print(f"{record.spec.id}: {record.status}")
+    return 0 if all(record.status == "complete" for record in records) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pygpu_scheduling-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "pygpu-scheduling"
+version = "0.1.0"
+description = "Reusable local CPU and NVIDIA GPU task scheduling with dependency graphs and recovery hooks"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "PyGPUScheduling contributors" }]
+keywords = ["gpu", "scheduler", "subprocess", "workflow", "nvidia"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/AllanJinYosoro/PyGPUScheduling"
+Issues = "https://github.com/AllanJinYosoro/PyGPUScheduling/issues"
+Changelog = "https://github.com/AllanJinYosoro/PyGPUScheduling/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+progress = ["tqdm>=4.66"]
+
+[dependency-groups]
+dev = ["pytest>=8,<10"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/task_scheduling"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/scripts", "/docs", "/README.md", "/AGENTS.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml", "/uv.lock", "/.python-version"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

pygpu_scheduling-0.1.0/scripts/check_project.py

@@ -0,0 +1,62 @@
+import ast
+import io
+from pathlib import Path
+import re
+import tokenize
+import tomllib
+
+
+ROOT = Path(__file__).resolve().parents[1]
+FORBIDDEN_IMPORTS = {"video_baselines", "torch", "optuna", "numpy", "yaml"}
+
+
+def check_python():
+    paths = [path for directory in ("src", "tests", "examples", "scripts")
+             for path in (ROOT / directory).rglob("*.py")]
+    for path in paths:
+        source = path.read_text()
+        tree = ast.parse(source, filename=str(path))
+        comments = [token for token in tokenize.generate_tokens(io.StringIO(source).readline)
+                    if token.type == tokenize.COMMENT]
+        if comments:
+            raise ValueError(f"Code comments are not allowed: {path.relative_to(ROOT)}")
+        if path.is_relative_to(ROOT / "src"):
+            imports = [node.module for node in ast.walk(tree)
+                       if isinstance(node, ast.ImportFrom) and node.module]
+            imports += [alias.name for node in ast.walk(tree)
+                        if isinstance(node, ast.Import) for alias in node.names]
+            if any(name.split(".")[0] in FORBIDDEN_IMPORTS for name in imports):
+                raise ValueError(f"Business dependency in core: {path.relative_to(ROOT)}")
+    return len(paths)
+
+
+def check_links():
+    documents = [ROOT / "README.md", ROOT / "AGENTS.md", ROOT / "CHANGELOG.md", *(ROOT / "docs").glob("*.md")]
+    for document in documents:
+        for target in re.findall(r"\[[^\]]*\]\(([^)]+)\)", document.read_text()):
+            if "://" in target or target.startswith("#"):
+                continue
+            relative = target.split("#", 1)[0]
+            if relative and not (document.parent / relative).exists():
+                raise ValueError(f"Broken link in {document.relative_to(ROOT)}: {target}")
+
+
+def check_metadata():
+    project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]
+    if project["name"] != "pygpu-scheduling" or project["dependencies"]:
+        raise ValueError("Distribution name or core runtime dependencies changed")
+    if project["license"] != "MIT" or not (ROOT / "LICENSE").is_file():
+        raise ValueError("MIT license metadata or license file is missing")
+    if not re.fullmatch(r"\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?", project["version"]):
+        raise ValueError("Version must have a release-compatible three-part format")
+
+
+def main():
+    count = check_python()
+    check_links()
+    check_metadata()
+    print(f"Project checks passed: {count} Python files, import boundaries, metadata and documentation links")
+
+
+if __name__ == "__main__":
+    main()

pygpu_scheduling-0.1.0/scripts/check_release.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+import sys
+import tomllib
+
+
+def main():
+    if len(sys.argv) != 2:
+        raise SystemExit("Usage: python scripts/check_release.py v<version>")
+    root = Path(__file__).resolve().parents[1]
+    version = tomllib.loads((root / "pyproject.toml").read_text())["project"]["version"]
+    expected = f"v{version}"
+    if sys.argv[1] != expected:
+        raise SystemExit(f"Release tag must be {expected}, got {sys.argv[1]}")
+    print(f"Release tag matches package version: {expected}")
+
+
+if __name__ == "__main__":
+    main()