xschedy 0.1.3__tar.gz

xschedy-0.1.3/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Runtime artifacts
+*.db
+logs/
+
+# 审查过程产物（非交付物）：对照项目的取证记录（matrix/*.md）与一次性工具脚本。
+# 内容有参考价值（design 2.3 对比矩阵的原文出处），但不属于要发布/部署的东西。
+.superpowers/
+
+# 打包快照
+*.rar
+
+# 控制面容器 bind 出来的作业目录（日志在 deploy/work/logs）
+deploy/xschedy/
+deploy/xschedy-worker/
+
+# Java 客户端构建产物
+clients/java/target/

xschedy-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zxpshadow
+
+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.

xschedy-0.1.3/PKG-INFO

@@ -0,0 +1,419 @@
+Metadata-Version: 2.5
+Name: xschedy
+Version: 0.1.3
+Summary: 内部系统的异步任务调度器
+Author: zxpshadow
+License-Expression: MIT
+License-File: LICENSE
+Keywords: celery,distributed,heartbeat,scheduler,task-queue,timeout
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: celery==5.7.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: orjson>=3.12.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: redis>=6.2
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Provides-Extra: server
+Requires-Dist: croniter>=2.0; extra == 'server'
+Requires-Dist: cryptography>=42.0; extra == 'server'
+Requires-Dist: fastapi>=0.111; extra == 'server'
+Requires-Dist: httpx>=0.27; extra == 'server'
+Requires-Dist: prometheus-client>=0.20; extra == 'server'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'server'
+Requires-Dist: sqlalchemy>=2.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
+Provides-Extra: worker
+Requires-Dist: httpx>=0.27; extra == 'worker'
+Description-Content-Type: text/markdown
+
+# Xschedy
+
+在 Celery 之上的一组业务封装：用装饰器写任务，用 `xschedy worker` 运行，用 Python SDK 下发与查询。
+
+## 安装
+
+```bash
+pip install xschedy[worker]    # 执行面：worker + 调用方 SDK（含 httpx）
+pip install xschedy[client]    # 只装调用方 SDK（核心 + httpx）
+pip install xschedy            # 仅核心（不含 httpx；不用 SDK / submit_task 时）
+```
+
+## 快速开始
+
+**1. 写任务**（`myproject/tasks.py`）：
+
+```python
+from xschedy.worker import TaskContext, xschedy_heartbeat_task
+
+
+@xschedy_heartbeat_task(name="order_pay")
+def order_pay(self, ctx: TaskContext):
+    return {"paid": True}
+```
+
+**2. 启动 worker**：
+
+```bash
+xschedy worker -Q default --tasks myproject.tasks
+```
+
+**3. 下发并等结果**：
+
+```python
+from xschedy.client import SyncClient
+
+with SyncClient("http://localhost:9100", token="…") as c:
+    sub = c.submit("order_pay", "default", user_data='{"order_id": 1}')
+    view = c.wait(sub.task_id, timeout=120)
+    print(view.status.value, view.result)
+```
+
+## 写业务任务
+
+任务命名 `项目.模块.函数`，用 `@xschedy_heartbeat_task` 注册；worker 启动时用 `--tasks` 加载定义任务的模块（逗号分隔多个）。
+
+```python
+from xschedy.worker import TaskContext, xschedy_heartbeat_task
+
+
+@xschedy_heartbeat_task(
+    name="order_pay",
+    heartbeat_interval=2.0,   # 心跳间隔
+    timeout=600,              # 硬超时（秒）
+    soft_timeout=540,         # 软超时（<= timeout）
+    max_retries=3,            # 重试次数
+    retry_backoff=True,       # 指数退避
+    abortable=True,           # 允许协作式中止
+)
+def order_pay(self, ctx: TaskContext):
+    self.report_progress(current=1, total=3, description="扣款")
+    return {"paid": True}
+```
+
+### 业务函数参数
+
+```python
+def f(self, ctx: TaskContext):
+    ...
+```
+
+- `ctx.user_data`：下发时给的 JSON **字符串原样**（`str | None`），框架不解析——要 dict 就 `json.loads`，要模型就 `model_validate_json`。
+- `self.request.id`：task_id；`self.request.retries`：第几次尝试（0 起）。
+- `self.request.hostname` / `delivery_info` / `headers`：Celery 原生信息。
+
+框架字段都在 `ctx` 上：
+
+```python
+ctx.task_name          # 任务名
+ctx.scheduled_time     # 定时任务的计划触发时刻（手动下发为 None）
+ctx.default_args       # XSCHEDY_DEFAULT_ARGS（透传不合并）
+ctx.periodic_kwargs    # 定时任务 kwargs（透传不合并）
+```
+
+### 进度与中止
+
+```python
+self.report_progress(current, total, description=None, extra=None)  # 自动算 percent + 剩余时间
+self.increment_progress(by=1, description=None, extra=None)         # 不知道 total 时递增
+self.is_aborted()                                                   # 需 abortable=True
+```
+
+- `extra` 是你自定义的**不透明字符串**（要结构化就自己 `json.dumps`），随进度返回给调用方；`description` / `extra` 各自 64KB 封顶，超限按 UTF-8 截断并留痕。
+- `increment_progress` 的 `description` / `extra` 是**覆盖**语义：不传即清空；`total` 不会被抹掉。
+- `is_aborted()` 只在 `abortable=True` 时有效，且在关键点主动调用才有用（阻塞 IO 期间无法响应）。未开启时恒 `False`，并打一次告警。
+
+### 生命周期钩子（零 celery import）
+
+```python
+from xschedy.worker import xschedy_worker_process_init, xschedy_worker_process_shutdown
+
+@xschedy_worker_process_init
+def init_process():
+    global engine
+    engine = create_engine(DB_URL)   # 连接类资源必须建在子进程钩子里
+
+@xschedy_worker_process_shutdown
+def close_process(pid, exitcode):
+    engine.dispose()
+```
+
+| 钩子 | 时机 |
+|---|---|
+| `@xschedy_worker_init` | 主进程启动、fork 之前 |
+| `@xschedy_worker_process_init` | 每个子进程启动 |
+| `@xschedy_worker_process_shutdown` | 子进程退出前 |
+| `@xschedy_worker_shutdown` | 主进程关闭 |
+
+### 日志
+
+直接使用框架的 logger，不要自己初始化 loguru：
+
+```python
+from xschedy.worker import logger
+
+logger.info("order %s paid", order_id)   # 行内自动带 task_id
+```
+
+日志同时写 stderr 与 `<XSCHEDY_WORK_DIR>/logs/`（按天轮转，保留 `XSCHEDY_LOG_SAVE_DAY` 天）。
+
+### 三条必须知道的约束
+
+**① 不要把凭证放进 `user_data`。** 它会明文落库、也会进 worker 日志，框架不做脱敏。需要传递就传引用（例如密钥管理系统里的 key 名）。`user_define` 同理，而且它随每次进度通知重发一遍，只适合放短期票据。
+
+**② 等外部事件不要在 worker 里 `sleep` 轮询。** 用 `self.retry(countdown=N)` 把任务重新入队，释放执行槽：
+
+```python
+if not upstream_ready(job_id):
+    self.retry(countdown=60)
+```
+
+**③ CPU 密集任务要在关键点让出 GIL。** 心跳跑在独立线程里；纯计算不释放 GIL 会让心跳停摆，任务被误判超时。周期性调一次 `self.report_progress(...)`（顺带推送进度）即可：
+
+```python
+for i, chunk in enumerate(chunks):
+    compute(chunk)
+    if i % 100 == 0:
+        self.report_progress(i, len(chunks))
+```
+
+> 心跳一停，幂等键 `xschedy:idem:{key}` 也不再续期，同 key 的下发会在窗口过期后重新建任务。
+> 另外，心跳检测不到「任务自己阻塞在锁/IO 上」——那类停滞由 `xschedy_task_stalled` 指标反映。
+
+## 运行 worker
+
+```bash
+# 普通
+xschedy worker -Q my_queue --tasks myproject.tasks
+
+# 分片：监听 {queue}.shard.N；下发方带 shard_key 时按 md5(key) % N 路由
+xschedy worker -Q my_queue.shard.0,my_queue.shard.1 --tasks myproject.tasks
+```
+
+- **`--tasks` 必须给**。漏了不会报错，只打一条 WARNING，但一个任务都不会注册，下发会得到 `UNKNOWN_TASK`。
+- **同机多 worker 必须给互不相同的 `--name`**：
+
+  ```bash
+  xschedy worker -n worker1 -Q q1 --tasks myproject.tasks
+  xschedy worker -n worker2 -Q q2 --tasks myproject.tasks
+  ```
+
+  名字里**不要带 `@` 或 `.`**：`-n worker1` 正确；`-n w1@host1` 会取 `host1`，与 `-n w2@host1` 撞成同一个 worker；不传则所有进程都是 `celery@<本机hostname>`。
+- 分片没有 worker 监听时，带 `shard_key` 的任务退回普通队列（并打 WARNING）；分片数变化会让几乎所有 key 重新分布，不建议在有顺序性诉求的 key 上频繁扩缩容。
+
+## 调用任务（`xschedy.client`）
+
+`Client` 是异步版，`SyncClient` 是同步版，方法与参数一一对应：
+
+```python
+import asyncio
+from xschedy.client import Client, XschedyError
+
+
+async def main():
+    async with Client("http://localhost:9100", token="…") as c:
+        sub = await c.submit("order_pay", "default", user_data='{"order_id": 1}')
+        view = await c.wait(sub.task_id, timeout=120)
+        print(view.status.value, view.result)
+
+
+asyncio.run(main())
+```
+
+```python
+from xschedy.client import SyncClient
+
+with SyncClient("http://localhost:9100", token="…") as c:
+    view = c.submit_sync("order_pay", "default", user_data='{"order_id": 1}')
+    print(view.status.value, view.result)
+```
+
+`submit` 的其余关键字参数与请求字段同名：`user_data`、`tag`、`priority`、`idempotent_key`、`timeout_s`、`queue_timeout_s`、`max_requeue`、`delay_run_s`、`notify`、`deadline` 等。`submit` 返回 `Submission`（`task_id` / `deduplicated` / `task`）。**`mode` 不走这个自由字段**：同步下发请用 `submit_sync`，传 `mode=` 会直接报错。
+
+常用方法：
+
+| 方法 | 作用 |
+|---|---|
+| `submit` / `submit_sync` | 异步下发 / 阻塞到终态 |
+| `get(task_id)` | 查询最新视图 |
+| `wait(task_id, timeout=…)` | 轮询到终态；超时抛 `WAIT_TIMEOUT`，不 revoke 任务 |
+| `retry` / `revoke(terminate=)` / `abort` / `relaunch` | 同 task_id 重试 / 撤销 / 协作式中止 / 新 id 重发 |
+
+错误统一抛 `XschedyError`，带 `code` / `message` / `status_code` / `task_id`。
+
+重试策略（`retries=N`，默认 0）：
+
+- `get` / `wait` 对连接错误与 429 / 502 / 503 / 504 重试；
+- `submit` **只有带 `idempotent_key` 时**才重试（避免建出两条任务）；
+- `submit_sync` 不自动重试。
+
+### 管理方法（同一个客户端）
+
+```python
+with SyncClient("http://localhost:9100", token="…") as c:
+    c.list_tasks(status="failed", page_size=50)
+    c.inflight_tasks(queue="order")
+    c.attempts(task_id)
+    c.get_raw(task_id)                                # result 的 backend 原样值
+    c.retry_many(["t1", "t2"], dry_run=True)
+    c.delete_many({"tag": "batch-1"}, dry_run=True)
+    c.revoke_many({"tag": "batch-1"}, confirm=True)   # 真撤销要显式 confirm
+    c.abort_many({"tag": "batch-1"}, dry_run=True)
+    c.delete(task_id)
+    c.task_types()
+    c.set_timeout("file.parse", soft=540, hard=600)
+```
+
+批量动作的筛选字段与 `list_tasks` 相同（status/queue/name/tag/worker/dispatch_reason/时间范围），至少给一个条件；`dry_run=True` 只预览，真执行要 `confirm=True`。
+
+### 任务内发子任务
+
+```python
+@xschedy_heartbeat_task(name="rag_parse")
+def rag_parse(self, ctx: TaskContext):
+    ctx.submit_task(
+        "rag_chunk", "rag",
+        user_data=json.dumps({"doc_id": doc_id}),
+        idempotent_key=f"{doc_id}:chunk:v1",
+    )
+```
+
+地址与 token 默认取 `XSCHEDY_API_URL` / `XSCHEDY_API_TOKEN`，也可以 `submit_task(..., base_url=..., token=...)` 单次覆盖。子任务请显式给幂等键，父任务重发时才不会重复下发。
+
+## 结果通知（可选）
+
+下发时带 `notify` 才会推送；不填则一条都不推。
+
+```python
+c.submit(
+    "order_pay", "default",
+    notify={
+        "type": "webhook",                     # webhook | mq | redis
+        "on_success": True,
+        "on_failure": True,
+        "on_timeout": True,                    # 默认 False
+        "config": {"url": "https://example.com/hook"},
+    },
+)
+```
+
+通知体只有两种，靠 `frame_type` 区分，`task` 结构相同：
+
+```json
+{
+  "frame_type": "terminal",
+  "task": {"task_id": "…", "status": "success", "result": {"ok": true}, "error": null, ...},
+  "execution_id": "…",
+  "callback_attempt": 1,
+  "notify_type": "webhook",
+  "progress_at": null
+}
+```
+
+- 终态通知每个任务**只有一条**；`on_success` / `on_failure` 默认开，`on_timeout` 默认关（因超时结束的任务要显式打开）。
+- at-least-once：接收方按 `task.task_id` + `execution_id` + `callback_attempt` 去重。
+- `notify.on_progress=True` 时另推进度帧（`frame_type="progress"`），内容同形；进度是水位，同一个值不会重复推。
+- `type=mq` 只向 exchange + routing_key 投递，**消费方要先建好队列并绑定**，否则消息会被 broker 丢弃。
+- 配置了 `XSCHEDY_SECRET_KEY` 时，`notify.config` 里的凭证会加密存储；日志与响应始终脱敏。
+
+## 对象存储（S3 / MinIO）
+
+```python
+from xschedy.worker import get_s3
+
+s3 = get_s3()
+s3.upload(b"bytes", key="x/y.txt", bucket="data")
+s3.upload_file("./report.pdf", key="reports/2026.pdf", bucket="data", with_hash_tag=True)
+s3.upload_folder("./exports", prefix="exports/2026", bucket="data")
+
+data = s3.download("x/y.txt", bucket="data")                          # 小对象，整份进内存
+path = s3.download_to_file("big.bin", bucket="data")                  # 大文件，流式落盘
+path = s3.download_to_file("big.bin", "./tmp/big.bin", bucket="data") # 指定落点
+url  = s3.presigned_url("x/y.txt", expires=3600, bucket="data")
+s3.exists("x/y.txt", bucket="data")
+s3.get_tags("x/y.txt", bucket="data")
+s3.set_tags("x/y.txt", {"status": "committed"}, bucket="data")
+s3.delete("x/y.txt", bucket="data")
+```
+
+- `bucket` 必填。
+- `download` 适合小对象；大文件用 `download_to_file`（临时文件 + 原子改名，失败不留半截）。省略 `path` 时落到缓存目录。
+- `with_hash_tag=True` 会把整文件摘要写进对象 tag（键 `digest`，值 `sha256:<hex>`）；代价是多读一遍文件。
+
+## 文件缓存（`get_cached_file`）
+
+同一个对象要反复读，或要交给 pandas / ffmpeg 这类按路径读文件的库：
+
+```python
+from xschedy.worker import FileIntegrityError, get_cached_file
+
+path = get_cached_file("data", "orders/2026/11/x.csv")   # -> pathlib.Path
+df = pandas.read_csv(path)
+
+path = get_cached_file("data", "big.bin", digest="9e107d…", verify=True)
+```
+
+- 落点：`<XSCHEDY_WORK_DIR>/cache/<bucket>/<key>`，文件名照搬对象 key。
+- 命中判据是两把 SHA-256 摘要相等：远端对象 tag 的 `digest` 与本地文件摘要；远端没有 tag 时按 size+mtime 命中并告警一次；下载后不符抛 `FileIntegrityError`，半成品不入缓存。
+- 上限 `XSCHEDY_FILE_CACHE_MAX_MB`（默认 10240）与 `XSCHEDY_FILE_CACHE_MAX_FILES`（默认 1000），超限按 LRU 淘汰；关掉 `XSCHEDY_FILE_CACHE_ENABLED` 则每次都下载覆盖。
+- 上传时打 tag（`with_hash_tag=True`）才能做内容校验。
+
+## Redis 直连与原子操作
+
+```python
+from xschedy.worker import (
+    get_redis,
+    redis_incr_with_ttl, redis_incr_with_ttl_once, redis_decr_floor,
+    redis_hset_atomic, redis_sadd_atomic, redis_lpush_atomic,
+    redis_lock, redis_acquire_lock, redis_renew_lock, redis_release_lock,
+)
+
+r = get_redis()                     # 复用 worker 的 Redis 配置
+r.set("k", "v"); r.get("k")         # 原生 redis-py 命令可用
+
+redis_incr_with_ttl(r, "counter", 3600)       # INCR + 每次续期
+redis_incr_with_ttl_once(r, "limit", 86400)   # 仅首次设 TTL
+redis_decr_floor(r, "limit")                  # 带下限 DECR
+
+redis_hset_atomic(r, "h", {"a": 1}, expire=3600)
+redis_sadd_atomic(r, "s", "m1", "m2", expire=3600)
+redis_lpush_atomic(r, "q", "v1", "v2", expire=3600)
+
+with redis_lock(r, "job-lock", ttl=30):
+    ...
+
+token = redis_acquire_lock(r, "job-lock", ttl=30)
+redis_renew_lock(r, "job-lock", token, 30)
+redis_release_lock(r, "job-lock", token)
+```
+
+并发槽与命名资源池由框架自己管，不对业务开放。
+
+## 配置
+
+环境变量统一 `XSCHEDY_` 前缀，**进程启动时读取**，改完要重启：
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `XSCHEDY_BROKER_URL` | `amqp://localhost:5672` | RabbitMQ |
+| `XSCHEDY_RESULT_BACKEND` | `redis://localhost:6379/1` | Redis 结果后端 |
+| `XSCHEDY_WORK_DIR` | `~/.xschedy` | 作业目录（日志、文件缓存） |
+| `XSCHEDY_LOG_LEVEL` / `_PATH` / `_SAVE_DAY` | `INFO` / `<work>/logs` / `7` | 日志 |
+| `XSCHEDY_HEARTBEAT_INTERVAL` | `5.0` | 默认心跳间隔（装饰器可覆盖） |
+| `XSCHEDY_TASK_TIMEOUT_S` | `30.0` | 默认心跳超时（装饰器可覆盖） |
+| `XSCHEDY_API_URL` / `_API_TOKEN` | `http://localhost:9100` / 空 | 任务内 `ctx.submit_task` 的地址与 token |
+| `XSCHEDY_DEFAULT_ARGS` | 空 | 全局默认参数 JSON，透传不合并 |
+| `XSCHEDY_S3_ENDPOINT` / `_ACCESS_KEY` / `_SECRET_KEY` / `_SECURE` / `_REGION` | `localhost:9000` / 空 / 空 / `false` / `us-east-1` | 对象存储 |
+| `XSCHEDY_S3_HASH_TAG` | `digest` | 对象摘要 tag 的键名 |
+| `XSCHEDY_FILE_CACHE_ENABLED` / `_MAX_MB` / `_MAX_FILES` | `true` / `10240` / `1000` | 文件缓存 |
+| `XSCHEDY_TIMEZONE` | `Asia/Shanghai` | 定时任务与时间展示 |
+
+> 变量名必须带 `XSCHEDY_` 前缀；少写前缀会被静默忽略并退回默认值。