Metadata-Version: 2.4
Name: powerjob-client-python
Version: 5.1.2.0
Summary: Python port of PowerJob OpenAPI client 5.1.2
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# PowerJob Client Python

这是 `tech.powerjob:powerjob-client:5.1.2` 的 Python 同步客户端移植版，用于调用 PowerJob Server 的 `/openApi` 接口。它移植的是 **OpenAPI 管理客户端**，不是接收和执行任务的 Worker SDK。

已覆盖 Java 客户端的 Job、Instance、Workflow、Workflow Instance API，并实现：

- AppName + 密码 MD5 鉴权
- access token 自动刷新
- 多 Server 地址故障切换
- HTTP/HTTPS、自定义请求头和超时
- `snake_case` 方法及 Java `camelCase` 兼容别名
- 请求 dataclass、枚举和结构化 `Result`

## 安装

```bash
python -m pip install .
```

开发和测试：

```bash
python -m pip install -e ".[test]"
pytest
```

## 快速开始

```python
from powerjob_client import PowerJobClient

with PowerJobClient("127.0.0.1:7700", "my-app", "powerjob-password") as client:
    jobs = client.fetch_all_job()
    if jobs.success:
        print(jobs.data)

    instance_id = client.run_job(10086, instance_params='{"source":"python"}').unwrap()
    print(instance_id)
```

集群和 HTTPS 配置：

```python
from powerjob_client import ClientConfig, PowerJobClient

config = ClientConfig(
    app_name="my-app",
    password="secret",
    address_list=["powerjob-1:7700", "powerjob-2:7700"],
    protocol="https",
    connection_timeout=3,
    read_timeout=10,
    default_headers={"X-Tenant": "demo"},
    verify_ssl=True,
    trust_env=False,
)
client = PowerJobClient(config)
```

> 为忠实兼容 Java 5.1.2 客户端，HTTPS 的 `verify_ssl` 默认是 `False`。生产环境建议显式设为 `True` 并使用有效证书。

客户端默认不读取 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等环境配置，避免访问内网 PowerJob Server 时意外走本机代理。如确实需要继承环境代理，请配置 `trust_env=True`。

## 新建或更新 Job

```python
from powerjob_client import (
    ExecuteType,
    PowerJobClient,
    ProcessorType,
    SaveJobInfoRequest,
    TimeExpressionType,
)

request = SaveJobInfoRequest(
    job_name="python-created-job",
    job_description="created through PowerJob OpenAPI",
    processor_info="com.example.DemoProcessor",
    execute_type=ExecuteType.STANDALONE,
    processor_type=ProcessorType.BUILT_IN,
    time_expression_type=TimeExpressionType.CRON,
    time_expression="0 0 * * * ?",
)

with PowerJobClient("127.0.0.1:7700", "my-app", "secret") as client:
    job_id = client.save_job(request).unwrap()
```

也可直接传字典。字典允许 Python `snake_case` 键，发送时会转换成 PowerJob 的 `camelCase`：

```python
client.query_job({"job_name_like": "demo", "status_in": [1]})
```

## API 对照

| Java | Python |
|---|---|
| `exportJob` / `saveJob` / `copyJob` | `export_job` / `save_job` / `copy_job` |
| `fetchJob` / `fetchAllJob` / `queryJob` | `fetch_job` / `fetch_all_job` / `query_job` |
| `disableJob` / `enableJob` / `deleteJob` | `disable_job` / `enable_job` / `delete_job` |
| `runJob` | `run_job` |
| `stopInstance` / `cancelInstance` / `retryInstance` | `stop_instance` / `cancel_instance` / `retry_instance` |
| `fetchInstanceStatus` / `fetchInstanceInfo` | `fetch_instance_status` / `fetch_instance_info` |
| `queryInstanceInfo` | `query_instance_info` |
| `saveWorkflow` / `copyWorkflow` | `save_workflow` / `copy_workflow` |
| `saveWorkflowNode` / `fetchWorkflow` | `save_workflow_node` / `fetch_workflow` |
| `disableWorkflow` / `enableWorkflow` / `deleteWorkflow` | `disable_workflow` / `enable_workflow` / `delete_workflow` |
| `runWorkflow` | `run_workflow` |
| `stopWorkflowInstance` / `retryWorkflowInstance` | `stop_workflow_instance` / `retry_workflow_instance` |
| `markWorkflowNodeAsSuccess` | `mark_workflow_node_as_success` |
| `fetchWorkflowInstanceInfo` | `fetch_workflow_instance_info` |

所有 Java 风格方法名也可直接调用。响应统一为 `Result(success, data, message, code)`；`data` 保留 Server 原始 JSON 对象，避免版本升级时因新增字段反序列化失败。

## 与 Java 版的有意差异

- Python 不区分 Java 的 `ResultDTO` 和 `PowerResultDTO`，统一为 `Result`，并保留可选 `code`。
- Python 字典响应保持原始形态，不强制转换为大量 DTO 类。
- Java 的 `writeTimeout` 在 `requests` 中没有完全对应的独立设置；连接与读取超时分别由 `connection_timeout`、`read_timeout` 控制。
- 动态地址发现使用无参 `address_provider: Callable[[], Sequence[str]]`。

## 版本范围

实现以 PowerJob 官方仓库标签 `v5.1.2` 中的 `powerjob-client` 和 `powerjob-common` 为依据。若 Server 版本较旧，`runJob2`、分页查询或鉴权响应头可能不可用。
