不应在新项目中使用 cadence-python，因其已于2025年底彻底停止维护、不兼容python 3.11+、依赖过时的tchannel/thrift技术栈；唯一受支持的替代方案是temporalio，它基于grpc、原生支持async/await、完整适配python 3.9–3.14。
cadence 是 Uber 开源的分布式工作流引擎（2019 年已归档，由 temporal 接续演进），其官方 Python 客户端 cadence-python 在 2025 年底已彻底停止维护，PyPI 上最后发布版本为 0.38.0（2021 年 11 月），且不兼容 Python 3.11+。
这意味着：你现在不应在新项目中使用 cadence-python，它已实质死亡。
为什么 pip install cadence-python 会失败或运行报错
常见错误现象包括：ModuleNotFoundError: No module named 'thrift'、AttributeError: module 'ssl' has no attribute 'PROTOCOL_TLSv1_2'（Python 3.12+）、或 ImportError 来自 thriftpy2 的 ABI 不兼容。
- 该客户端强依赖
thriftpy2==0.4.12，而该版本未适配 Python 3.11 的typing变更和 3.12 的 SSL 模块重构 - 底层通信基于 Thrift over TChannel，而 TChannel 在 2022 年后已无活跃维护，与现代 asyncio 生态（如
httpx、uvloop）完全脱节 - PyPI 页面显示
cadence-python最后一次 CI 通过是 2021 年，测试矩阵最高只到 Python 3.9
替代方案只有 Temporal + temporalio
Uber 将 Cadence 代码库重命名为 temporal 后，Python 生态已全面迁移。当前唯一受支持、持续更新的客户端是 temporalio（PyPI 包名），最新稳定版为 1.14.0（2026 年 1 月发布），完整支持 Python 3.9–3.14。
立即学习“Python免费学习笔记（深入）”；
-
temporalio基于 gRPC + Protobuf，而非 Thrift，性能更好、调试更直观（可直接用grpcurl查看 workflow 状态） - 原生支持 async/await，
Workflow.run()和Activity.execute()都是协程函数，无需手动管理线程池 - 类型提示完备：
temporalio.types.WorkflowID、temporalio.common.RetryPolicy等均带完整 stubs，IDE 自动补全可靠 - 若你有遗留 Cadence IDL 或 workflow logic，需重写——二者 API 不兼容，没有平滑升级路径
从 cadence-python 迁移到 temporalio 的关键断点
不是“改几个 import”，而是工作流建模层的重写。最常卡住的地方是序列化逻辑和异常传播机制。
-
cadence-python默认用PickleSerializer，而temporalio默认用JSONSerializer；若 workflow 参数含datetime、Decimal或自定义类，必须显式注册CompositeSerializer - Cadence 的
RetryPolicy是 dict 结构，Temporal 的RetryPolicy是 dataclass 实例，字段名也不同（例如maximum_attempts→maximum_attempts保留，但expiration_interval已弃用） - 本地开发时，Cadence 用
cadence-serverDocker 镜像，Temporal 必须用temporalio/auto-setup（旧版temporalio/server已停更），端口默认从7933（TChannel）变为7233（gRPC）
如果你必须临时跑通老代码
仅限调试或下线过渡期，不建议长期使用。
- 锁定 Python 3.9.19（最后一个被
cadence-pythonCI 覆盖的 patch 版本） - 手动降级：
pip install thrift==0.13.0 thriftpy2==0.4.12 protobuf==3.20.3（更高版本会触发DescriptorPool冲突） - 禁用 TLS 验证（仅限本地）：
CADENCE_TLS_ENABLED=false，否则tchannel会因 OpenSSL 3.0+ 报SSL_CTX_set_options错误
真正麻烦的从来不是换包命令，而是 workflow 的 retry 行为、心跳超时、worker 注册逻辑这些隐式契约——它们在 Cadence 和 Temporal 中语义已有偏移。别指望靠 patch 让老客户端活过 2026 年中。
