camunda-python

一个面向 Python 3 的开源 BPMN / DMN 流程引擎。

提供 BPMN 2.0 流程模型解析、流转执行、DMN 决策表求值、SQLAlchemy 持久化、多实例 作业执行与可选的 REST API。适合需要把工作流嵌入 Python 服务、又不想拉一整套 Java 生态的团队。

特性一览

• BPMN 2.0 流程建模：基于 lxml 的自研解析器，支持用户任务 / 服务任务 / 排他与 并行网关 / 内嵌子流程 / 多实例 / 边界与中断 / 消息与信号事件。
• DMN 决策引擎：独立可用，支持六种 hitPolicy（UNIQUE / FIRST / ANY / PRIORITY / RULE ORDER / COLLECT[+SUM/MIN/MAX/COUNT]）与 FEEL 表达式子集 （数值算术 / 比较 / 区间 / 列表 / not(...) / null），并可通过 BPMN businessRuleTask 集成进流程。
• 持久化：SQLAlchemy 2.0，兼容 SQLite / PostgreSQL / MySQL。崩溃后 ProcessEngine.from_database() 一行恢复。
• 作业执行器：Timer Start / Timer Catch / asyncBefore / asyncAfter / 失败重试； JobExecutor 后台线程自动推进。
• 多节点抢锁：跨进程 / 多 JobExecutor 通过 DB CAS lease 保证同一作业不被重复执行， 长作业支持续约。
• REST API：FastAPI 兼容 Camunda 7 engine-rest 常用端点（部署 / 流程定义 / 流程实例 / 任务 / 历史 / 决策），9 个列表端点支持 firstResult + maxResults 分页。

快速开始

pip install camunda-python             # 核心（BPMN / DMN / 持久化 / JobExecutor）
pip install camunda-python[api]        # 可选：REST API（fastapi + uvicorn）

最小可运行示例（拷贝即跑，无需任何本地文件；examples/loan-approval.bpmn 为本示例的完整版）：

from camunda.parser import parse_bpmn_xml
from camunda.engine import ProcessEngine

xml = """<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:camunda="http://camunda.org/schema/1.0/bpmn"
                  id="d1" targetNamespace="http://example.com/loan">
  <bpmn:process id="loan-approval" name="贷款审批流程" isExecutable="true">
    <bpmn:startEvent id="start" name="提交申请"/>
    <bpmn:serviceTask id="check-credit" camunda:delegateExpression="${checkCredit}"/>
    <bpmn:exclusiveGateway id="amount-gateway" default="flow-auto-pass"/>
    <bpmn:userTask id="manual-review" name="人工审批"/>
    <bpmn:exclusiveGateway id="decision-gateway" default="flow-reject"/>
    <bpmn:endEvent id="end-approved" name="已批准"/>
    <bpmn:endEvent id="end-rejected" name="已拒绝"/>
    <bpmn:sequenceFlow id="flow-start" sourceRef="start" targetRef="check-credit"/>
    <bpmn:sequenceFlow id="flow-check" sourceRef="check-credit" targetRef="amount-gateway"/>
    <bpmn:sequenceFlow id="flow-manual" sourceRef="amount-gateway" targetRef="manual-review">
      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${amount &gt;= 10000}</bpmn:conditionExpression>
    </bpmn:sequenceFlow>
    <bpmn:sequenceFlow id="flow-auto-pass" sourceRef="amount-gateway" targetRef="end-approved"/>
    <bpmn:sequenceFlow id="flow-review" sourceRef="manual-review" targetRef="decision-gateway"/>
    <bpmn:sequenceFlow id="flow-approve" sourceRef="decision-gateway" targetRef="end-approved">
      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${approved == true}</bpmn:conditionExpression>
    </bpmn:sequenceFlow>
    <bpmn:sequenceFlow id="flow-reject" sourceRef="decision-gateway" targetRef="end-rejected"/>
  </bpmn:process>
</bpmn:definitions>"""

engine = ProcessEngine()
engine.register_delegate("checkCredit", lambda v: v.update(credit_ok=True))  # serviceTask 实现
engine.deploy(parse_bpmn_xml(xml))

pi = engine.start_process_instance_by_key("loan-approval", {"amount": 20000})  # 大额 -> 人工审批
task = engine.create_task_query(process_instance_id=pi.id)[0]                   # [人工审批]
engine.complete_task(task.id, {"approved": True})                               # -> COMPLETED

启动 REST 服务：

uvicorn camunda.api.app:create_app --factory --port 8080
# 交互式 API 文档：http://127.0.0.1:8080/docs

文档导航

文档与示例存放在 GitHub 仓库（PyPI 页面不内嵌），点击上方链接或在仓库根目录查看。

示例

仓库自带可直接 python examples/xxx.py 运行的可执行示例：

测试与开发

git clone https://github.com/movingheart/camunda-python.git
cd camunda-python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api]"

pytest                       # 跑测试套件
pytest -k test_dmn            # 只跑某个子模块
pytest --cov=camunda          # 带覆盖率

CI 在 GitHub Actions 上跑 Python 3.12 / 3.13，每次 push 触发。

与 Camunda 7 的差异

设计目标是语义对齐——核心流程元素、状态机、持久化表结构与 Camunda 7 保持一致， 方便已有 Camunda 7 经验的人快速理解。但以下几点有意取舍：

• 不做：Cockpit / Tasklist Web 控制台、身份与权限、外部任务（external task）。
• 轻量差异：FEEL 仅支持子集（无函数调用 / 日期时间 / 路径表达式）； DMN 仅支持 decisionTable 形态；DMN 部署不落库（崩溃恢复后需重新 deploy_dmn）。
• 多进程抢锁：用应用层 CAS（UPDATE ... WHERE LOCK_EXP_TIME_ < now）替代 SELECT FOR UPDATE，跨 SQLite / PostgreSQL / MySQL 三个方言一致。
• 持久化策略：命令边界 delete + insert 全量重写（与 Camunda 7 逐行 update 不同）， 对中小流程足够快，恢复语义更直白。

完整差异表见 docs/ARCHITECTURE.md §设计取舍。

许可

Apache-2.0。详见 LICENSE。

变更记录见 CHANGELOG.md。