camunda-python 0.1.0__py3-none-any.whl

camunda/model/execution.py

@@ -0,0 +1,121 @@
+"""运行时执行模型：Execution 树 / ProcessInstance / ActivityInstance。
+
+对齐 Camunda ACT_RU_EXECUTION 语义：
+- ProcessInstance 是树的根（process_instance_id == 根 execution id 场景下，Camunda
+  的 root execution 与 process instance 是两条记录，这里 M1 合并为一条根 Execution）
+- 并行网关 fork 时创建子 Execution（parent 停驻成为 scope）
+- 每条「活动中的路径」由一条 Execution 携带：activity_id 指向当前所在节点
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:  # 仅类型检查，避免与 task.py 循环（task 不依赖 execution）
+    from camunda.model.task import Task
+
+
+class ExecutionState(str, Enum):
+    ACTIVE = "ACTIVE"            # 正等待：用户任务 / join / scope 停驻
+    ENDED = "ENDED"              # 已走完（endEvent 或实例结束）
+
+
+class ProcessInstanceState(str, Enum):
+    ACTIVE = "ACTIVE"
+    COMPLETED = "COMPLETED"      # 正常走完 endEvent
+    TERMINATED = "TERMINATED"    # 保留字段（M3+ 支持终止）
+
+
+@dataclass
+class Execution:
+    """一条执行路径（token 载体）。id 全局唯一。
+
+    role:
+    - TOKEN : 活动 token，沿流程推进，可停在 userTask / join 等待
+    - SCOPE : 并行 fork 后停驻的父 execution（等待子 TOKEN 完成后再恢复）
+    """
+
+    id: str
+    process_instance_id: str
+    parent_id: Optional[str] = None
+    role: str = "TOKEN"  # TOKEN | SCOPE
+    # None 表示该 execution 当前不在具体活动上（如 fork 后等待、根 scope）
+    activity_id: Optional[str] = None
+    state: ExecutionState = ExecutionState.ACTIVE
+    # 子 execution（并行网关 fork 产生）
+    children: List["Execution"] = field(default_factory=list)
+    # 当前停留活动实例（_open_activity 写入，_close_activity 结算时间后清空）
+    open_activity: Optional["ActivityInstance"] = None
+    # 多实例状态（M4-2c）：None = 非多实例执行。
+    # MI 容器（有 "total" 键）：{sequential, total, active, completed, next_index,
+    #   items, element_variable, completion_condition} —— parallel 容器挂在转 SCOPE
+    #   的宿主 token 上；sequential 容器挂在宿主 token 自身（token 兼作实例载体）。
+    # MI 实例（仅并行 child，{"index": i}）：标识该实例序号（收束回报计数用）。
+    mi: Optional[Dict[str, Any]] = None
+
+    # ---- 便捷 ----
+    @property
+    def is_root(self) -> bool:
+        return self.parent_id is None
+
+    def is_ended(self) -> bool:
+        return self.state == ExecutionState.ENDED
+
+    @property
+    def is_mi_container(self) -> bool:
+        """是否为多实例容器载体（挂 total 键的 MI 状态）。"""
+        return self.mi is not None and "total" in self.mi
+
+
+@dataclass
+class ActivityInstance:
+    """活动实例历史痕迹（M1 内存版，M2 落 ACT_HI_ACTINST）。
+
+    每次「进入某节点」记录一条，start_time 进入、end_time 离开。
+    """
+
+    id: str
+    process_instance_id: str
+    activity_id: str
+    activity_name: Optional[str] = None
+    execution_id: str = ""
+    start_time: Optional[str] = None
+    end_time: Optional[str] = None
+
+
+@dataclass
+class ProcessInstance:
+    """流程实例（对齐 ACT_HI_PROCINST 运行时视图）。"""
+
+    id: str
+    process_definition_key: str
+    business_key: Optional[str] = None
+    state: ProcessInstanceState = ProcessInstanceState.ACTIVE
+    variables: Dict[str, Any] = field(default_factory=dict)
+    root_execution: Optional[Execution] = None
+    start_time: Optional[str] = None
+    end_time: Optional[str] = None
+    # execution id 索引（与树冗余，便于 O(1) 查找）
+    executions: Dict[str, Execution] = field(default_factory=dict)
+    # 并行网关 join 到达登记：gateway_id -> 已到达的 execution id 列表
+    join_arrivals: Dict[str, List[str]] = field(default_factory=dict)
+    # 活动痕迹（ACT_HI_ACTINST 内存版）
+    activity_history: List[ActivityInstance] = field(default_factory=list)
+    # 已完成任务归档（complete 后从 engine 任务表移入，HI_TASKINST 落库）
+    completed_tasks: List["Task"] = field(default_factory=list)
+
+    @property
+    def is_completed(self) -> bool:
+        return self.state != ProcessInstanceState.ACTIVE
+
+    # ---- 并行网关 join 辅助 ----
+    def register_join_arrival(self, join_activity_id: str, execution_id: str) -> None:
+        self.join_arrivals.setdefault(join_activity_id, []).append(execution_id)
+
+    def join_arrived(self, join_activity_id: str) -> List[str]:
+        return self.join_arrivals.get(join_activity_id, [])
+
+    def clear_join_arrivals(self, join_activity_id: str) -> None:
+        self.join_arrivals.pop(join_activity_id, None)

camunda/model/job.py

@@ -0,0 +1,88 @@
+"""可调度作业模型（对齐 ACT_RU_JOB 语义，M3）。
+
+Camunda JobEntity 关键字段：ID_ / TYPE_ / DUEDATE_ / RETRIES_ / LOCK_OWNER_ /
+LOCK_EXP_TIME_ / EXECUTION_ID_ / PROCESS_INSTANCE_ID_ / PROCESS_DEFINITION_ID_ /
+ACTIVITY_ID_。M3 保留核心子集。
+
+job_type（对齐 Camunda Job.TYPE_ 取值语义）：
+- "timer-catch"        : token 停在 intermediateCatchEvent(timer)，duedate 到期继续流转
+- "timer-start"        : 定义级作业（无 process_instance），到点启动流程实例；
+                          timerCycle 触发后按 repeat 续排下一个 duedate
+- "timer-boundary"     : timer 边界事件（M4-1 中断式；M4-2b4 起 cancelActivity=false
+                          非中断式 = 触发不取消宿主、spawn 并发线）。宿主活动等待期内
+                          到点触发，中断式取消宿主并让 token 改走边界事件出边
+- "timer-event-start"  : 事件子流程的 timer start 订阅（M4-2b3，实例级，execution_id
+                          = 宿主 scope，activity_id = 订阅容器 subProcess id，None=
+                          流程级=根 Process 容器）。宿主 scope 激活期单发，到点触发
+                          中断式（取消宿主）或非中断式（并行 spawn）事件子流程
+- "async-continuation" : camunda:asyncBefore 拆分出的「节点行为执行」作业
+                          （Camunda 里即 async continuation job）
+- "async-after"        : camunda:asyncAfter 拆分出的「离开推进」作业（M4-1；
+                          serviceTask/XOR 行为完成后异步流转，XOR 离开时重求值条件）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+# 默认重试次数与失败延迟（对齐 Camunda 默认行为；M3 不解析 failedJobRetryTimeCycle，
+# retry 间隔固定可配。文档化差异）
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY_SECONDS = 5.0
+
+
+@dataclass
+class Job:
+    """一条待执行作业。"""
+
+    id: str
+    job_type: str  # timer-catch | timer-start | async-continuation
+    duedate: str  # 定长 ISO "%Y-%m-%dT%H:%M:%S"（与 clock.now() 同格式，可字典序比较）
+    created: str
+    # 实例级（timer-catch / async-continuation）
+    process_instance_id: Optional[str] = None
+    execution_id: Optional[str] = None
+    # 定义级（timer-start）：指向 process key；node_id 为 startEvent id
+    process_definition_key: Optional[str] = None
+    node_id: Optional[str] = None
+    # timer-event-start：订阅容器 subProcess id（None = 流程级/根 Process 容器）；
+    # 与 execution_id（宿主 scope）共同唯一定位「哪个容器上的订阅」，撤销精确匹配
+    activity_id: Optional[str] = None
+    # 重试策略
+    retries: int = DEFAULT_MAX_RETRIES
+    max_retries: int = DEFAULT_MAX_RETRIES
+    retry_delay_seconds: float = DEFAULT_RETRY_DELAY_SECONDS
+    # timer-start cycle 续排参数（{"kind": "interval"|"cron", ...}，见 common/timers）
+    repeat: Optional[Dict[str, Any]] = None
+    # 抢占锁（多实例 JobExecutor 预留；M3 单进程不使用）
+    lock_owner: Optional[str] = None
+    lock_expire_time: Optional[str] = None
+
+    @property
+    def is_definition_level(self) -> bool:
+        """定义级作业（timer-start）不挂在任何实例上。"""
+        return self.process_instance_id is None
+
+    def is_due(self, now: str) -> bool:
+        return self.duedate <= now
+
+    def is_dead(self) -> bool:
+        return self.retries <= 0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "job_type": self.job_type,
+            "process_instance_id": self.process_instance_id,
+            "execution_id": self.execution_id,
+            "process_definition_key": self.process_definition_key,
+            "node_id": self.node_id,
+            "activity_id": self.activity_id,
+            "duedate": self.duedate,
+            "created": self.created,
+            "retries": self.retries,
+            "repeat": self.repeat,
+            "lock_owner": self.lock_owner,
+            "lock_expire_time": self.lock_expire_time,
+        }

camunda/model/task.py

@@ -0,0 +1,33 @@
+"""人工任务模型（对齐 ACT_RU_TASK 语义）。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class Task:
+    """用户任务运行时实例：等待用户 complete。"""
+
+    id: str
+    name: Optional[str] = None
+    process_instance_id: str = ""
+    execution_id: str = ""          # 持有该任务的 execution
+    task_definition_key: str = ""   # BPMN userTask id
+    assignee: Optional[str] = None
+    candidate_users: List[str] = field(default_factory=list)
+    candidate_groups: List[str] = field(default_factory=list)
+    create_time: Optional[str] = None
+    end_time: Optional[str] = None  # complete 后写入（HI_TASKINST 归档）
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "process_instance_id": self.process_instance_id,
+            "task_definition_key": self.task_definition_key,
+            "assignee": self.assignee,
+            "create_time": self.create_time,
+            "end_time": self.end_time,
+        }

camunda/model/variable.py

@@ -0,0 +1,35 @@
+"""流程变量体系（M1 简化版）。
+
+对齐 Camunda 变量语义的 Python 映射：
+- Camunda 变量的 Java 类型名 -> Python 类型判断，序列化策略 JSON
+- ObjectValue（Java 序列化对象）在 Python 侧无等价物：M1 用 JSON 可序列化对象表示，
+  文档化差异（M2 持久化时落 TEXT/JSON 列）
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+# Java 类型 -> 判定函数（按需扩展）
+_JAVA_TYPE_OF = [
+    ("String", lambda v: isinstance(v, str)),
+    ("Integer", lambda v: isinstance(v, int) and not isinstance(v, bool)),
+    ("Boolean", lambda v: isinstance(v, bool)),
+    ("Double", lambda v: isinstance(v, float)),
+]
+
+
+def java_type_name(value: Any) -> str:
+    """推断变量值的 Java 类型名（Camunda REST API 的 type 字段）。"""
+    for name, check in _JAVA_TYPE_OF:
+        if check(value):
+            return name
+    return "Object"  # dict/list/None 等统一按对象处理
+
+
+def to_typed_dict(variables: Dict[str, Any]) -> Dict[str, dict]:
+    """把 {key: value} 转成 Camunda REST 风格 {key: {type, value}}（供 API 层/调试用）。"""
+    return {
+        k: {"type": java_type_name(v), "value": v}
+        for k, v in variables.items()
+    }

camunda/parser/__init__.py

@@ -0,0 +1,5 @@
+"""parser 包：BPMN 2.0 XML 解析（lxml 自研，对齐 Camunda bpmn-model 职责）。"""
+
+from camunda.parser.bpmn_parser import parse_bpmn_xml, parse_bpmn_file
+
+__all__ = ["parse_bpmn_xml", "parse_bpmn_file"]