Metadata-Version: 2.4
Name: AutoCython-zhang
Version: 2.3.9
Summary: 自动Cython，使用Cython批量编译.py文件为.pyd文件！
Author-email: zhang_gavin <qq814608@163.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/zhang0281/AutoCython
Project-URL: repository, https://github.com/zhang0281/AutoCython
Project-URL: documentation, https://github.com/zhang0281/AutoCython#readme
Keywords: cython,compile,pyd,pyc,python,autopyd
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools
Requires-Dist: cython<4,>=3
Requires-Dist: rich
Dynamic: license-file

# AutoCython

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

[![PyPI](https://img.shields.io/pypi/v/AutoCython-zhang)](https://pypi.org/project/AutoCython-zhang/)
[![Python](https://img.shields.io/pypi/pyversions/AutoCython-zhang)](https://pypi.org/project/AutoCython-zhang/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 概述

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 帮助信息和进度面板自动适配系统语言

## 安装

```bash
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` 闭包绑定修复仍包含在此版本中。

### 依赖

| 包 | 用途 |
|---|------|
| `cython>=3,<4` | Python → C 编译核心；确保运行时注解不被旧版编译链破坏 |
| `setuptools` | 构建扩展模块 |
| `rich` | 终端实时进度面板 |

## 使用方法

### 编译单文件

```bash
AutoCython -f demo.py
```

### 编译整个目录

```bash
AutoCython -p ./my_project
```

### 常用选项

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

### 排除文件

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

```python
# AutoCython No Compile
```

### 作为库调用

```python
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 概览

### 核心函数

| 函数 | 模块 | 描述 |
|------|------|------|
| `compile()` | `AutoCython.AutoCython` | 主入口：解析参数并调度编译任务 |
| `compile_to_binary()` | `AutoCython.compile` | 将单个 `.py` 文件编译为二进制扩展 |
| `obfuscate_source()` | `AutoCython.obfuscate` | 对源码执行六重 AST 混淆变换，并保留运行时 annotation 与编译所需 directives |
| `run_tasks()` | `AutoCython.run_tasks` | 并发任务执行引擎（含实时进度面板） |
| `find_python_files()` | `AutoCython.tools` | 递归扫描目录下的可编译 `.py` 文件 |
| `parse_arguments()` | `AutoCython.tools` | CLI 参数解析（中英双语） |
| `get_platform_extension()` | `AutoCython.compile` | 返回当前平台的二进制扩展名 |
| `get_system_language()` | `AutoCython.tools` | 检测系统语言（`zh`/`en`） |

## 目录结构

```
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                # 设计文档
```

## 相关文档

- [设计文档](DESIGN.md)
- [PyPI 主页](https://pypi.org/project/AutoCython-zhang/)
- [GitHub 仓库](https://github.com/zhang0281/AutoCython)
