flowchart TB
    subgraph 用户层
        A[Python 源代码] --> B[命令行 / REPL / 脚本]
    end

    subgraph 前端_编译层
        C[词法分析器 Tokenizer] --> D[PEG 解析器 Parser]
        D --> E[AST 抽象语法树]
        E --> F[编译器 Compiler]
        F --> G[Code Object 字节码对象]
    end

    subgraph 运行时_执行层
        H[字节码解释器 ceval.c]
        I[栈帧管理 Frame]
        J[执行栈 Stack]
        K[Tier 2 优化器 / JIT]
    end

    subgraph 对象系统
        L[基础对象 PyObject]
        M[类型系统 PyTypeObject]
        N[内置类型]
        O[用户定义类型]
    end

    subgraph 内存管理
        P[引用计数 Refcount]
        Q[内存分配器 PyMem]
        R[垃圾回收器 GC]
        S[对象池 Pool]
    end

    subgraph 标准库_模块
        T[内置模块 builtins]
        U[C 扩展模块]
        V[Python 模块]
    end

    subgraph C_API层
        W[嵌入接口 Embedding]
        X[扩展接口 Extension]
        Y[线程管理 GIL]
    end

    B --> C
    G --> H
    H --> I
    I --> J
    H --> K
    H --> L
    L --> M
    M --> N
    M --> O
    L --> P
    P --> Q
    Q --> R
    R --> S
    H --> T
    T --> U
    T --> V
    W --> H
    X --> L
    Y --> H

sequenceDiagram
    autonumber
    participant U as 用户
    participant M as main()
    participant I as Py_Initialize
    participant P as Parser
    participant C as Compiler
    participant E as Eval Loop
    participant O as Objects
    participant G as GC

    U->>M: python script.py
    M->>I: 初始化解释器
    I->>I: 初始化类型系统
    I->>I: 创建 builtins 模块
    I->>I: 初始化 GC
    I->>I: 设置 sys.path

    M->>P: 读取源文件
    P->>P: 词法分析（Token）
    P->>P: 语法分析（PEG）
    P-->>C: 返回 AST

    C->>C: 符号表分析
    C->>C: 字节码生成
    C-->>E: 返回 Code Object

    E->>E: 创建 Frame
    loop 字节码执行
        E->>E: 取指令
        E->>O: 操作对象（LOAD/STORE/CALL）
        O->>O: 引用计数管理
        alt 触发 GC
            E->>G: 检查阈值
            G->>G: 标记-清除
            G-->>E: 回收完成
        end
        alt 异常
            E->>E: 查找异常表
            E->>E: 跳转到 handler
        end
    end

    E-->>M: 返回结果
    M->>I: Py_Finalize
    I->>G: 清理所有对象
    I->>I: 释放内存
    M-->>U: 退出

// 核心配置项
config.optimization_level  // 优化级别（0/1/2）
config.use_environment    // 是否读取环境变量
config.isolated           // 隔离模式
config.hash_seed          // 字典哈希种子
config.tracemalloc        // 内存追踪

/* minimal_python.c - 最小 Python 嵌入示例 */
#include <Python.h>

int main(int argc, char *argv[])
{
    // 1. 初始化 Python 解释器
    Py_Initialize();

    // 2. 执行 Python 代码
    PyRun_SimpleString("print('Hello from CPython!')");

    // 3. 清理解释器
    if (Py_FinalizeEx() < 0) {
        return 120;  // 清理失败
    }

    return 0;
}

gcc -o minimal_python minimal_python.c \
    $(python3-config --cflags --ldflags --embed)
./minimal_python

/* mymodule.c - 简单的扩展模块 */
#define PY_SSIZE_T_CLEAN
#include <Python.h>

// 1. 定义模块函数：计算斐波那契数
static PyObject*
fib(PyObject *self, PyObject *args)
{
    int n;
    // 解析参数：单个整数
    if (!PyArg_ParseTuple(args, "i", &n)) {
        return NULL;  // 参数解析失败，异常已设置
    }

    // 边界检查
    if (n < 0) {
        PyErr_SetString(PyExc_ValueError, "n must be >= 0");
        return NULL;
    }

    // 计算斐波那契（递归实现）
    long a = 0, b = 1;
    for (int i = 0; i < n; i++) {
        long temp = a;
        a = b;
        b = temp + b;
    }

    // 返回 Python 整数对象
    return PyLong_FromLong(a);
}

// 2. 定义方法表
static PyMethodDef MyMethods[] = {
    {"fib", fib, METH_VARARGS, "Calculate Fibonacci number"},
    {NULL, NULL, 0, NULL}  // 哨兵
};

// 3. 定义模块结构
static struct PyModuleDef mymodule = {
    PyModuleDef_HEAD_INIT,
    "mymodule",           // 模块名
    "Example module",     // 模块文档
    -1,                   // 模块状态大小（-1 表示不支持子解释器）
    MyMethods
};

// 4. 模块初始化函数（必须命名为 PyInit_<模块名>）
PyMODINIT_FUNC
PyInit_mymodule(void)
{
    return PyModule_Create(&mymodule);
}

gcc -shared -fPIC -o mymodule.so mymodule.c \
    $(python3-config --cflags --ldflags)

import mymodule

result = mymodule.fib(10)
print(f"fib(10) = {result}")  # 输出：fib(10) = 55

/* pointmodule.c - 定义 Point 类型 */
#include <Python.h>

// 1. 定义 C 结构体
typedef struct {
    PyObject_HEAD      // 必须：对象头（包含 refcnt 和 type）
    double x;          // 成员变量
    double y;
} PointObject;

// 2. 构造函数（__new__）
static PyObject*
Point_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    PointObject *self;
    self = (PointObject*) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->x = 0.0;
        self->y = 0.0;
    }
    return (PyObject*) self;
}

// 3. 初始化函数（__init__）
static int
Point_init(PointObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"x", "y", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|dd", kwlist,
                                      &self->x, &self->y)) {
        return -1;
    }

    return 0;
}

// 4. 析构函数（__del__）
static void
Point_dealloc(PointObject *self)
{
    Py_TYPE(self)->tp_free((PyObject*) self);
}

// 5. 方法：距离计算
static PyObject*
Point_distance(PointObject *self, PyObject *args)
{
    PointObject *other;
    if (!PyArg_ParseTuple(args, "O!", &PointType, &other)) {
        return NULL;
    }

    double dx = self->x - other->x;
    double dy = self->y - other->y;
    double dist = sqrt(dx*dx + dy*dy);

    return PyFloat_FromDouble(dist);
}

// 6. 方法表
static PyMethodDef Point_methods[] = {
    {"distance", (PyCFunction) Point_distance, METH_VARARGS,
     "Calculate distance to another point"},
    {NULL}
};

// 7. 成员访问器（属性）
static PyMemberDef Point_members[] = {
    {"x", T_DOUBLE, offsetof(PointObject, x), 0, "x coordinate"},
    {"y", T_DOUBLE, offsetof(PointObject, y), 0, "y coordinate"},
    {NULL}
};

// 8. 类型对象定义
static PyTypeObject PointType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "point.Point",
    .tp_doc = "Point objects",
    .tp_basicsize = sizeof(PointObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Point_new,
    .tp_init = (initproc) Point_init,
    .tp_dealloc = (destructor) Point_dealloc,
    .tp_methods = Point_methods,
    .tp_members = Point_members,
};

// 9. 模块初始化
static PyModuleDef pointmodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "point",
    .m_doc = "Point type example",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_point(void)
{
    PyObject *m;

    if (PyType_Ready(&PointType) < 0)
        return NULL;

    m = PyModule_Create(&pointmodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&PointType);
    if (PyModule_AddObject(m, "Point", (PyObject*) &PointType) < 0) {
        Py_DECREF(&PointType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

from point import Point

p1 = Point(3.0, 4.0)
p2 = Point(0.0, 0.0)

print(f"p1 = ({p1.x}, {p1.y})")  # 输出：p1 = (3.0, 4.0)
dist = p1.distance(p2)
print(f"Distance: {dist}")        # 输出：Distance: 5.0