🍞 lib2toast

此库将lib2to3的具体语法树(CST)转换为标准Python AST。

潜在用途包括

• 使用较少依赖于Python版本的Python代码进行解析
• 扩展或修改Python语法，以实验新功能或创建类似Python的方言

用法

此库仍处于早期阶段，API可能会更改。

• lib2toast.api.compile(code, *, grammar=..., compiler=...)：将代码字符串编译成AST。此AST可以进一步编译成Python代码对象或使用内置的compile()和exec()函数执行。默认情况下，这使用覆盖了最新Python版本接受的所有语法以及一些额外语法的语法。传递一个自定义的grammar以使用不同的语法。您可以使用lib2toast.api.load_grammar从文件加载语法对象。如果这样做，通常还需要通过从lib2toast.compile.Compiler派生来自定义的compiler对象。
• lib2toast.api.run(code, *, filename=..., grammar=..., compiler=...)：编译代码然后立即执行。
• lib2toast.api.load_grammar(path, *, async_keywords=True)：从路径加载语法文件。如果async_keywords为True，将async视为Python 3.7+中的关键字。

还有一个命令行界面：使用python -m lib2toast -c code在解析代码后使用lib2toast运行code。

展示

命令行界面显示lib2toast支持解析旧版Python版本中的某些新语法

$ python3.9 -m lib2toast -c 'print(f"{"x"}")'
x

这是Python 3.12通过PEP 701引入的新语法。

它还支持一些（不是所有）在Python 3中删除的Python 2语法

$ python3.9 -m lib2toast -c 'print(1 <> 2)'
True

测试套件（test suite）展示了使用lib2toast解析Python语法变体的示例。例如

dataclass(frozen=True) C:
    x: int
    y: int = 0

实现

lib2toast是基于blib2to3实现的，blib2to3是lib2to3的分支，由Black项目维护，用于解析和格式化Python代码。它起源于lib2to3，是早期Python 3版本中附带的一个工具，用于在Python 2和3代码之间进行转换。

实现的核心部分是一个将Python代码转换为AST的工具。这使得测试正确性变得容易：只需运行Python内置的ast.parse并断言它生成相同的树，包括行和列号。到目前为止，我已经在我的lib2toast代码以及Black的一些代码上测试了编译器（Black的测试用例特别有用），但可能还有更多的错误。

Python版本支持

此库支持Python 3.9及以上版本。

不支持Python 3.8，因为它即将达到其支持期的结束，3.8和3.9之间的AST结构相当不同，而且我没有3.8的使用案例。

未来我计划支持所有受支持的上游Python版本。

贡献

欢迎为此项目做出贡献，包括关于如何使用库的核心功能的新方法的想法。

查看“问题”标签，以获取可能的贡献区域。

发行说明

版本0.1.0（2024年8月6日）

• 修复Unicode标识符的误编译；它们现在已NFKC归一化
• 修复了右侧有未加括号的元组的赋值运算符上的崩溃
• 修复了嵌套的异步生成器表达式上的崩溃
• 修复了包含以分号结束的语句的套件中的不正确的行范围
• 修复了以分号结束的语句上的崩溃
• 修复了某些三引号f字符串上的崩溃
• 修复了左侧有赋值运算符的调用上的误编译
• 使创建具有更多类型后缀的方言更容易
• 调整一些类型注解，以使子类化更容易

版本0.0.1（2024年7月1日）

初始版本。