python_assembler/program/
mod.rs

1#![doc = include_str!("readme.md")]
2use crate::instructions::PythonInstruction;
3use serde::{Deserialize, Serialize};
4use std::fmt::Debug;
5
6/// 表示 Python 字节码的版本。
7#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
8pub enum PythonVersion {
9    #[default]
10    /// 未知 Python 版本。
11    Unknown,
12    /// Python 3.7 版本。
13    Python3_7,
14    /// Python 3.8 版本。
15    Python3_8,
16    /// Python 3.9 版本。
17    Python3_9,
18    /// Python 3.10 版本。
19    Python3_10,
20    /// Python 3.11 版本。
21    Python3_11,
22    /// Python 3.12 版本。
23    Python3_12,
24    /// Python 3.13 版本。
25    Python3_13,
26    /// Python 3.14 版本。
27    Python3_14,
28}
29
30impl PythonVersion {
31    /// 根据 .pyc 头部的 MAGIC_NUMBER 推断 Python 版本
32    /// 参考 importlib.util.MAGIC_NUMBER 值和 CPython 源码
33    pub fn from_magic(magic: [u8; 4]) -> Self {
34        match magic {
35            // Python 3.7.x - 0x420d0d0a
36            [66, 13, 13, 10] => PythonVersion::Python3_7,
37            // Python 3.8.x - 0x550d0d0a
38            [85, 13, 13, 10] => PythonVersion::Python3_8,
39            // Python 3.9.x - 0x610d0d0a
40            [97, 13, 13, 10] => PythonVersion::Python3_9,
41            // Python 3.10.x - 0x700d0d0a
42            [112, 13, 13, 10] => PythonVersion::Python3_10,
43            // Python 3.11.x - 0xa80d0d0a
44            [168, 13, 13, 10] => PythonVersion::Python3_11,
45            // Python 3.12.x - 0xcb0d0d0a
46            [203, 13, 13, 10] => PythonVersion::Python3_12,
47            // Python 3.13.x - 0xf30d0d0a
48            [243, 13, 13, 10] => PythonVersion::Python3_13,
49            // Python 3.14.x - 0x2b0e0d0a (可能在正式版本中变化)
50            [43, 14, 13, 10] => PythonVersion::Python3_14,
51            _ => PythonVersion::Unknown,
52        }
53    }
54
55    /// 将 Python 版本转换为对应的 MAGIC_NUMBER
56    pub fn as_magic(&self) -> [u8; 4] {
57        match self {
58            // Python 3.7.x - 0x420d0d0a
59            PythonVersion::Python3_7 => [66, 13, 13, 10],
60            // Python 3.8.x - 0x550d0d0a
61            PythonVersion::Python3_8 => [85, 13, 13, 10],
62            // Python 3.9.x - 0x610d0d0a
63            PythonVersion::Python3_9 => [97, 13, 13, 10],
64            // Python 3.10.x - 0x700d0d0a
65            PythonVersion::Python3_10 => [112, 13, 13, 10],
66            // Python 3.11.x - 0xa80d0d0a
67            PythonVersion::Python3_11 => [168, 13, 13, 10],
68            // Python 3.12.x - 0xcb0d0d0a
69            PythonVersion::Python3_12 => [203, 13, 13, 10],
70            // Python 3.13.x - 0xf30d0d0a
71            PythonVersion::Python3_13 => [243, 13, 13, 10],
72            // Python 3.14.x - 0x2b0e0d0a (可能在正式版本中变化)
73            PythonVersion::Python3_14 => [43, 14, 13, 10],
74            PythonVersion::Unknown => [0, 0, 0, 0],
75        }
76    }
77}
78
79/// .pyc 文件的头部信息。
80#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
81pub struct PycHeader {
82    /// Magic number identifying the Python version.
83    pub magic: [u8; 4],
84    /// Bit flags for the .pyc file.
85    pub flags: u32,
86    /// Timestamp of the .pyc file creation.
87    pub timestamp: u32,
88    /// Size of the .pyc file.
89    pub size: u32,
90}
91
92impl Default for PycHeader {
93    fn default() -> Self {
94        Self { magic: [0; 4], flags: 0, timestamp: 0, size: 0 }
95    }
96}
97
98/// Upvalue 信息
99#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
100pub struct Upvalue {
101    /// 若在栈中则为1，若在外部upvalue中则为0
102    pub in_stack: u8,
103    /// 寄存器或upvalue的索引
104    pub idx: u8,
105    /// 调试信息用的名称
106    pub name: String,
107}
108
109/// 局部变量信息
110#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
111pub struct LocalVar {
112    /// 局部变量的名称。
113    pub name: String,
114    /// 局部变量作用域的起始程序计数器。
115    pub start_pc: u32,
116    /// 局部变量作用域的结束程序计数器。
117    pub end_pc: u32,
118}
119
120/// 表示不同类型的 Python 对象。
121#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
122pub enum PythonObject {
123    /// Python 字符串对象。
124    Str(String),
125    /// Python 整数对象（32位）。
126    Int(i32),
127    /// Python 整数对象（64位）。
128    Integer(i64),
129    /// Python 浮点数对象。
130    Float(f64),
131    /// Python 布尔对象。
132    Bool(bool),
133    /// 另一个 Python 字符串对象（与 Str 重复，但为了兼容性保留）。
134    String(String),
135    /// Python 列表对象。
136    List(Vec<PythonObject>),
137    /// Python 元组对象。
138    Tuple(Vec<PythonObject>),
139    /// Python 字节数组对象。
140    Bytes(Vec<u8>),
141    /// Python 代码对象。
142    Code(PythonCodeObject),
143    #[default]
144    /// 表示 Python 的 None 对象。
145    None,
146}
147
148/// Python 代码对象，包含字节码指令、常量、变量等信息。
149#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
150pub struct PythonCodeObject {
151    /// 代码对象的名称。
152    pub name: String,
153    /// 代码对象的限定名称。
154    pub qualname: String,
155    /// 源文件名。
156    pub source_name: String,
157    /// 代码对象的起始行号。
158    pub first_line: u32,
159    /// 代码对象的结束行号。
160    pub last_line: u32,
161    /// 参数数量。
162    pub co_argcount: u8,
163    /// 仅限位置参数的数量。
164    pub co_posonlyargcount: u8,
165    /// 仅限关键字参数的数量。
166    pub co_kwonlyargcount: u8,
167    /// 局部变量数量。
168    pub co_nlocals: u8,
169    /// 所需的最大栈大小。
170    pub co_stacksize: u8,
171    /// 代码对象标志位。
172    pub co_flags: u32,
173    /// 字节码指令。
174    pub co_code: Vec<PythonInstruction>,
175    /// 代码对象使用的常量。
176    pub co_consts: Vec<PythonObject>,
177    /// 代码对象使用的名称。
178    pub co_names: Vec<String>,
179    /// 局部变量和自由变量名称。
180    pub co_localsplusnames: Vec<String>,
181    /// 局部变量和自由变量类型。
182    pub co_localspluskinds: Vec<u8>,
183    /// 用于调试的行号信息。
184    pub co_linetable: Vec<u8>,
185    /// 异常处理表。
186    pub co_exceptiontable: Vec<u8>,
187}
188
189/// Python .pyc 程序的高层语义定义（以指令序列为核心）
190/// Python .pyc 程序的高层语义定义（以指令序列为核心）
191#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
192pub struct PythonProgram {
193    /// .pyc 文件的头部。
194    pub header: PycHeader,
195    /// Python 程序的主代码对象。
196    pub code_object: PythonCodeObject,
197    /// 与 .pyc 文件关联的 Python 版本。
198    pub version: PythonVersion,
199}
python_assembler/program/mod.rs

python_assembler/program/
mod.rs
