Metadata-Version: 2.4
Name: sikron-job
Version: 0.1.0
Summary: Sikron Job runtime SDK (env, progress file, session crypto) — aligns with pkg/job
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# sikron-job（Python SDK）

与仓库 `pkg/job` 契约对齐的薄客户端：**环境变量**、**进度 JSON 文件**、**Runner 会话加解密**。不包含 Go `executor` 的跑批编排。

规范见 [docs/JOB_RUNTIME_SPEC.md](../../docs/JOB_RUNTIME_SPEC.md)。

## 安装

**业务 Job / 示例**（在仓库外或其它目录 `import sikron`）需要安装：

```bash
cd sdk/python
python -m venv .venv
.venv\Scripts\activate   # Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"
```

**框架开发**（只改 `sdk/python/sikron/` 内源码）：包内已用 **相对导入**（`from .env import …`），IDE 打开 `sdk/python` 即可跳转，**不必**先 `pip install` 才能编辑 `job.py` 等文件。跑测试在 `sdk/python` 下执行 `pytest`（`pyproject.toml` 已配置 `pythonpath = ["."]`）。

| 场景 | 是否要 pip install |
|------|-------------------|
| 改 `sikron/job.py` 等框架源码 | 否（相对导入 + IDE 识别包目录） |
| `examples/python-job` 里 `from sikron import …` | 是 |
| `pytest`（在 `sdk/python`） | 否（已配 pythonpath） |

## 用法概要

### 高层封装（推荐，由 Runner 启动）

```python
from sikron import SikronJob

# RunnerContext 仅来自 load_runner_context（bootstrap 内部调用）
with SikronJob.bootstrap() as job:
    job.progress.running(50, message="half")
    x = job.env("MY_VAR", decrypt=True)
```

本地无 Runner 时 **不要** 在框架里开 demo 开关；在示例/测试里 `try: SikronJob.bootstrap()` / `except IncompleteRunnerEnvError` 后手写 `RunnerContext`，再 `SikronJob.from_context(ctx)`。

### 底层 API

```python
from sikron import RunnerContext, load_runner_context, init_runner_session_from_env, get_env
from sikron import ProgressSnapshot, write_progress, ProgressReporter, SikronJob

ctx = load_runner_context()
job = SikronJob.from_context(ctx)
# 或
rep = ProgressReporter(ctx.progress_file, ctx.task_id)
rep.running(10, message="…")
rep.success()
```

示例 Job：`examples/python-job/`。
