AutoCython

自动将 Python 源码编译为 Cython 二进制扩展（.so/.pyd），支持六重 AST 混淆、并发编译、跨平台运行。

概述

AutoCython 是一个 Python 源码保护工具，通过 Cython 编译 + AST 混淆提高逆向成本，将 .py 文件转换为二进制扩展模块。混淆不是 encryption，也不宣称不可逆；二进制中仍可能包含运行时所需的常量与字符串。

特性

• 一键编译 — 单文件 (-f) 或整目录 (-p) 批量编译为 .so/.pyd
• 六重 AST 混淆 — docstring 移除、局部变量重命名、字符串 escaped-literal 改写、常量折叠、控制流平坦化、虚假分支注入；默认完整保留运行时 annotation，兼容 FastAPI / Pydantic / dataclass
• 并发编译 — 基于 ThreadPoolExecutor 的多线程并行编译，可配置并发数
• 实时进度面板 — 基于 Rich 的实时任务状态表格、进度条、耗时统计
• 跨平台 — 支持 Linux、macOS、Windows，自动适配 .so/.pyd 扩展名
• 包路径保真 — 编译包内模块时保留 qualified module name，兼容 Pydantic / FastAPI 等依赖运行时模块命名空间的框架
• 可复现构建 — 通过 --seed 参数固定混淆随机种子
• 智能排除 — 自动跳过 __init__.py、常见虚拟环境/构建目录和 kd-dist 动态 split facade/fragment；支持 # AutoCython No Compile 标记豁免
• 中英双语 — CLI 帮助信息和进度面板自动适配系统语言

安装

pip install AutoCython-zhang

当前编译链要求 Cython>=3,<4。该约束用于避免旧版 Cython 在编译后破坏 Pydantic / FastAPI / dataclass 等依赖运行时注解的框架行为。

Python 语法兼容边界

项目以 Python >=3.9 语法解析，实际可编译范围由当前 Cython backend 决定。常用的 async、keyword-only/positional-only 参数、walrus operator、类型注解、yield、comprehension 等均走 Cython 编译链；源码会按 PEP 263 coding cookie 读取，混淆输出在原编码无法表示生成文本时自动改写为 UTF-8 临时源码。

当前 Cython 3.x 尚不实现以下语法，AutoCython 会在编译前抛出 UnsupportedSyntaxError，而非运行一轮 setup 后返回难以定位的 backend traceback：

• match/case structural pattern matching
• except* exception groups
• PEP 695 generic type parameters/type alias statements（运行时 Python 支持时）

obfuscate_source() 本身仍可处理并执行 match/case AST；限制只作用于 Cython binary build。

兼容性补充：Pydantic 兼容 shim 只对词法作用域内可识别的 pydantic.BaseModel 子类生效，且仅补充 Cython 所需的 ignored_types；Pydantic v2 的 model_config（包括条件、try、带注解和继承场景）及 legacy class Config 均保留，pydantic.v1 不会被误判。字符串混淆采用编译期 ASCII escaped literal，不生成 runtime decoder、缓存或 sys.intern 副作用；运行时得到的仍是普通 Python str。编译产物先写入目标目录的 staging 文件，校验成功后才原子替换旧产物，截断或失败的中间文件不会覆盖已有结果。

v2.3.9 收紧了 Pydantic、编码、包路径和混淆边界；nonlocal 闭包绑定修复仍包含在此版本中。

依赖

使用方法

编译单文件

AutoCython -f demo.py

编译整个目录

AutoCython -p ./my_project

常用选项

AutoCython -p ./src -c 4          # 4 线程并发编译
AutoCython -f main.py -d          # 编译后删除源文件
AutoCython -p ./src --seed 42     # 固定混淆种子（可复现）
AutoCython -v                     # 查看版本
AutoCython -h                     # 查看帮助

排除文件

在文件头两行内添加注释即可跳过编译：

# AutoCython No Compile

作为库调用

from AutoCython.compile import compile_to_binary

# 编译单文件
output = compile_to_binary("demo.py", del_source=False, obfuscate=True, obfuscate_seed=42)
print(f"生成: {output}")

API 概览

核心函数

目录结构

AutoCython/
├── AutoCython/
│   ├── __init__.py          # 包入口，导出 compile() 和 main()
│   ├── _version.py          # 单一版本号来源
│   ├── AutoCython.py        # 主编译调度逻辑
│   ├── compile.py           # Cython 编译核心（临时目录隔离）
│   ├── obfuscate.py         # 六重 AST 混淆引擎
│   ├── run_tasks.py         # 并发任务执行 + Rich 实时面板
│   └── tools.py             # CLI 参数解析、文件扫描、国际化
├── tests/
│   ├── test_autocython.py   # 主入口集成测试
│   ├── test_compile.py      # 编译功能单元测试
│   ├── test_obfuscate.py    # 混淆引擎单元测试
│   ├── test_obfuscate_advanced.py  # 混淆高级场景测试
│   ├── test_obfuscate_anti.py      # 混淆反模式/边界测试
│   ├── test_compile_anti.py        # 编译反模式测试
│   ├── test_run_tasks.py    # 任务执行器测试
│   ├── test_tools.py        # 工具函数测试
│   └── kd_dist/             # 知识蒸馏测试集（编译矩阵 + 行为等价）
├── pyproject.toml           # 项目配置与构建定义
├── requirements.txt         # 依赖清单
├── LICENSE                  # MIT 许可证
└── DESIGN.md                # 设计文档

相关文档

• 设计文档
• PyPI 主页
• GitHub 仓库