3. Bố cục kho lưu trữ

30 min read 5922 words
cpythonpythoninternals

3. Bố cục kho lưu trữ

Kho lưu trữ CPython được tổ chức xung quanh các hệ thống con chính của trình thông dịch: triển khai đối tượng, bộ máy thời gian chạy, đường dẫn trình biên dịch, trình phân tích cú pháp, mô-đun tích hợp, thư viện chuẩn, kiểm tra, tài liệu và tệp xây dựng nền tảng.

Cách tốt đầu tiên là coi cây nguồn như một bản đồ trách nhiệm.```text cpython/ Include/ Objects/ Python/ Parser/ Modules/ Lib/ Programs/ Tools/ Doc/ Grammar/ PC/ PCbuild/ Mac/


## 3.1 Cấu trúc cấp cao nhất

| Thư mục | Vai trò chính |
| ----------- | --------------------------------------------------- |
|`Include/`| Tiêu đề C công khai, nội bộ và riêng tư |
|`Objects/`| Triển khai các loại đối tượng cốt lõi |
|`Python/`| Thời gian chạy, trình biên dịch, vòng lặp thông dịch, khởi tạo |
|`Parser/`| Mã hỗ trợ mã thông báo và trình phân tích cú pháp |
|`Grammar/`| Tệp đầu vào ngữ pháp |
|`Modules/`| Các mô-đun mở rộng và tích hợp được viết bằng C |
|`Lib/`| Thư viện chuẩn Python |
|`Lib/test/`| Bộ kiểm tra hồi quy CPython |
|`Programs/`| Điểm vào có thể thực thi |
|`Tools/`| Công cụ dành cho nhà phát triển và xây dựng |
|`Doc/`| Nguồn tài liệu |
|`PC/`| Tệp nguồn và cấu hình dành riêng cho Windows |
|`PCbuild/`| Hệ thống xây dựng Windows |
|`Mac/`| hỗ trợ dành riêng cho macOS |

Các thư mục quan trọng nhất để đọc nội bộ là:```text
Include/
Objects/
Python/
Parser/
Modules/
Lib/test/
```Các thư mục đó bao gồm mô hình đối tượng, công cụ thực thi, trình biên dịch, trình phân tích cú pháp, các loại tích hợp, API C và các thử nghiệm.

## 3.2`Include/`: Tệp tiêu đề C`Include/`chứa các tệp tiêu đề được sử dụng bởi chính CPython, các mô-đun mở rộng và trình nhúng.

Một bố cục đơn giản hóa:```text
Include/
    Python.h
    object.h
    unicodeobject.h
    listobject.h
    dictobject.h
    cpython/
    internal/
```Tệp quan trọng nhất là:```c
#include <Python.h>

Python.hlà tiêu đề chung chung cho các mô-đun mở rộng. Nó bao gồm nhiều tiêu đề công khai khác và hiển thị API C mà hầu hết các tác giả tiện ích mở rộng sử dụng.

Danh mục tiêu đề

Khu vực tiêu đề Khán giả Tính ổn định
Include/*.h Người dùng API C công khai Tương đối ổn định
Include/cpython/ API dành riêng cho CPython Ít di động hơn
Include/internal/ Chỉ nội bộ CPython Có thể thay đổi tự do

Sự khác biệt này quan trọng. Mã bên trong CPython có thể bao gồm các tiêu đề nội bộ. Tiện ích mở rộng của bên thứ ba nói chung là không nên.

Ví dụ:```c #include "Python.h"


Nhưng:```c
#include "internal/pycore_runtime.h"
```dành cho mã lõi CPython. Nó hiển thị các cấu trúc thời gian chạy nội bộ không phải là một phần của API công khai ổn định.

## 3.3`Objects/`: Triển khai đối tượng tích hợp`Objects/`chứa các triển khai C của nhiều loại đối tượng Python cốt lõi.

Ví dụ:

| Tập tin | Thực hiện |
| ------------------- | --------------------------------- |
|`object.c`| Hoạt động đối tượng cơ sở |
|`typeobject.c`| Nhập đối tượng, lớp, MRO, vị trí |
|`longobject.c`| Số nguyên Python |
|`floatobject.c`| Python nổi |
|`unicodeobject.c`| Chuỗi Python |
|`bytesobject.c`     | `bytes`                           |
| `bytearrayobject.c` | `bytearray`                       |
| `listobject.c`      | `list`                            |
| `tupleobject.c`     | `tuple`                           |
| `dictobject.c`      | `dict`                            |
| `setobject.c`       | `set`Và`frozenset`             |
| `funcobject.c`| Đối tượng chức năng |
|`methodobject.c`| Đối tượng phương thức tích hợp |
|`moduleobject.c`| Đối tượng mô-đun |
|`genobject.c`| Trình tạo và coroutine |
|`frameobject.c`| Hỗ trợ đối tượng khung |
|`codeobject.c`| Đối tượng mã |
|`cellobject.c`| Tế bào đóng cửa |
|`descrobject.c`| Mô tả |

Thư mục này là nơi tốt nhất để nghiên cứu cách biểu diễn và vận hành các giá trị Python.

Ví dụ: hành vi liệt kê tồn tại chủ yếu ở:```text
Objects/listobject.c
```Hành vi từ điển sống chủ yếu ở:```text
Objects/dictobject.c
```Hành vi chuỗi tồn tại chủ yếu ở:```text
Objects/unicodeobject.c
```Khi Python chạy:```python
items = []
items.append(1)
```hoạt động phân bổ, thay đổi kích thước, tra cứu phương thức và nối thêm danh sách cơ bản cuối cùng liên quan đến mã trong`Objects/listobject.c`và gõ máy móc vào`Objects/typeobject.c`.

## 3,4`Python/`: Lõi thời gian chạy, trình biên dịch và phiên dịch`Python/`chứa nhiều máy móc trung tâm của CPython.

Các tập tin quan trọng bao gồm:

| Tập tin | Vai trò |
| ------------------ | -------------------------------------------------- |
|`ceval.c`| Vòng đánh giá mã byte |
|`bytecodes.c`| Định nghĩa hướng dẫn mã byte trong CPython hiện đại |
|`compile.c`| AST để biên dịch đối tượng mã |
|`symtable.c`| Phân tích bảng ký hiệu |
|`ast.c`| Hỗ trợ AST |
|`pythonrun.c`| Điểm vào thực thi cấp cao |
|`pylifecycle.c`| Khởi tạo và hoàn thiện thời gian chạy |
|`import.c`| Hỗ trợ nhập khẩu |
|`errors.c`| API lỗi và trạng thái ngoại lệ |
|`traceback.c`| Hỗ trợ truy nguyên |
|`sysmodule.c`| Thực hiện`sys`                            |
| `bltinmodule.c`| Các chức năng tích hợp và mô-đun dựng sẵn |
|`marshal.c`| Định dạng tuần tự hóa nội bộ cho các đối tượng mã |
|`thread.c`| Lớp trừu tượng chủ đề |
|`context.c`| Hỗ trợ biến bối cảnh |
|`bootstrap_hash.c`| Khởi tạo bí mật băm |

Tên tập tin không chỉ đơn thuần là nhãn. Chúng phản ánh các hệ thống con thời gian chạy sâu.

### Thực thi trình thông dịch

Trình thông dịch mã byte tập trung vào vòng đánh giá. Trong lịch sử điều này gắn liền với`ceval.c`. Trong các phiên bản CPython mới hơn, định nghĩa opcode và các phần thông dịch được tạo có thể được chia thành các tệp bổ sung.

Vai trò khái niệm:```text
frame enters evaluation
    ↓
bytecode instruction fetched
    ↓
instruction dispatch
    ↓
object operation
    ↓
stack and frame state updated
```### Đường dẫn trình biên dịch

Mã trình biên dịch hạ thấp các nút AST thành các đối tượng mã.

Một đường dẫn đơn giản:```text
source text
    ↓
tokens
    ↓
parse tree
    ↓
AST
    ↓
symbol table
    ↓
compiler
    ↓
code object
```Các tập tin chính thường là:```text
Parser/
Python/ast.c
Python/symtable.c
Python/compile.c
Objects/codeobject.c
```## 3,5`Parser/`: Hỗ trợ mã thông báo và trình phân tích cú pháp`Parser/`chứa mã thông báo, hỗ trợ trình tạo trình phân tích cú pháp, tệp triển khai trình phân tích cú pháp và mã liên quan đến trình phân tích cú pháp được tạo.

Các lĩnh vực quan trọng bao gồm:

| Khu vực | Vai trò |
| ---------------------- | ------------------------------------ |
| mã thông báo | Chuyển đổi văn bản nguồn thành mã thông báo |
| trình phân tích cú pháp | Xây dựng cấu trúc cú pháp từ mã thông báo |
| máy móc PEG | Hỗ trợ trình phân tích cú pháp PEG của Python |
| tập tin phân tích cú pháp được tạo | Được tạo ra từ các định nghĩa ngữ pháp |

Công việc của trình phân tích cú pháp là quyết định xem văn bản nguồn có phải là cú pháp Python hợp lệ hay không và xây dựng các cấu trúc mà sau này trở thành AST.

Ví dụ:```python
x = 1 + 2
```Trình phân tích cú pháp cần nhận ra:```text
assignment statement
target name x
expression 1 + 2
integer literal 1
integer literal 2
binary addition operator
```Phân tích cú pháp đi trước phân tích ngữ nghĩa. Trình phân tích cú pháp biết cú pháp. Việc vượt qua bảng ký hiệu sau đó sẽ quyết định xem tên là biến cục bộ, toàn cục, miễn phí hay biến ô.

## 3.6`Grammar/`: Định nghĩa ngữ pháp`Grammar/`chứa các tệp đầu vào ngữ pháp được sử dụng để tạo mã liên quan đến trình phân tích cú pháp.

Ngữ pháp xác định cú pháp Python ở dạng được sử dụng bởi công cụ phân tích cú pháp của CPython.

Đối với công việc nội bộ, những thay đổi về ngữ pháp có tác động lớn. Một sự thay đổi cú pháp có thể ảnh hưởng đến:```text
parser generation
AST generation
compiler behavior
error messages
tests
documentation
tools that parse Python
```Sự thay đổi ở cấp độ ngữ pháp thường yêu cầu tái tạo và kiểm tra mục tiêu.

Quy trình làm việc thông thường là:```text
edit grammar input
regenerate parser files
rebuild CPython
run parser, AST, compiler, and syntax tests
```## 3,7`Modules/`: Mô-đun tích hợp và mở rộng`Modules/`chứa nhiều mô-đun C được gửi cùng với CPython.

Ví dụ:

| Tệp hoặc thư mục | Mô-đun |
| ------------------- | ------------------------ |
|`_io/`| Triển khai I/O |
|`_decimal/`| Máy gia tốc thập phân |
|`_sqlite/`| Mô-đun SQLite |
|`_ssl.c`| Hỗ trợ SSL |
|`_hashopenssl.c`| Băm với OpenSSL |
|`_ctypes/`          | `ctypes`                 |
| `arraymodule.c`     | `array`                  |
| `mathmodule.c`      | `math`                   |
| `itertoolsmodule.c` | `itertools`              |
| `functoolsmodule.c` | `_functools`             |
| `posixmodule.c`     | `os`hoạt động nền tảng |
|`timemodule.c`      | `time`|

Một số mô-đun thư viện tiêu chuẩn được viết bằng Python và sử dụng bộ tăng tốc C từ`Modules/`.

Ví dụ: một mô-đun Python công khai có thể nằm trong`Lib/`, trong khi một người trợ giúp quan trọng về hiệu suất sống ở`Modules/`.

Mẫu này cung cấp cho CPython một API công khai rõ ràng trong khi vẫn duy trì việc triển khai C nhanh cho các đường dẫn nóng.

## 3,8`Lib/`: Thư viện chuẩn`Lib/`chứa thư viện chuẩn Python.

Ví dụ:

| Đường dẫn | Vai trò |
| -------------------- | -------------------------------- |
|`Lib/os.py`| Lớp giao diện hệ điều hành |
|`Lib/pathlib/`| Đường dẫn hướng đối tượng |
|`Lib/importlib/`| Triển khai hệ thống nhập khẩu |
|`Lib/asyncio/`| Khung I/O không đồng bộ |
|`Lib/collections/`| Tiện ích sưu tập |
|`Lib/dataclasses.py`| Hỗ trợ lớp dữ liệu |
|`Lib/typing.py`| Hỗ trợ đánh máy |
|`Lib/unittest/`| Khung kiểm thử đơn vị |
|`Lib/json/`| Triển khai JSON |
|`Lib/concurrent/`| Tương lai và nhóm quy trình/luồng |

Nhiều nội dung CPython dễ hiểu hơn bằng cách đọc thư viện chuẩn cấp Python trước.

Ví dụ,`importlib`chứa phần lớn hệ thống nhập bằng mã Python. CPython khởi động nó một cách đặc biệt, nhưng phần lớn vẫn có thể đọc được dưới dạng Python.

## 3,9`Lib/test/`: Kiểm tra hồi quy`Lib/test/`chứa bộ thử nghiệm của CPython.

Thư mục này rất cần thiết cho công việc nội bộ.

Ví dụ:

| Tệp thử nghiệm | Tập trung |
| ------------------- | -------------------- |
|`test_dict.py`| Hành vi từ điển |
|`test_list.py`| Liệt kê hành vi |
|`test_gc.py`| Người thu gom rác |
|`test_sys.py`       | `sys`mô-đun |
|`test_dis.py`| Tháo gỡ mã byte |
|`test_compile.py`| Hành vi của trình biên dịch |
|`test_ast.py`| Hành vi AST |
|`test_importlib/`| Hệ thống nhập khẩu |
|`test_capi/`| Hành vi API C |
|`test_threading.py`| Hành vi phân luồng |

Khi nghiên cứu một hệ thống con, hãy ghép nối tệp triển khai với các thử nghiệm của nó.

| Thực hiện | Kiểm tra |
| ---------------------- | ----------------------------- |
|`Objects/dictobject.c` | `Lib/test/test_dict.py`     |
| `Objects/listobject.c` | `Lib/test/test_list.py`     |
| `Python/compile.c`     | `Lib/test/test_compile.py`  |
| `Python/symtable.c`    | `Lib/test/test_symtable.py` |
| `Python/sysmodule.c`   | `Lib/test/test_sys.py`      |
| `Modules/mathmodule.c` | `Lib/test/test_math.py`|

Thói quen này ngăn cản việc đọc mã một cách cô lập. Hành vi của CPython được xác định bằng mã cộng với các bài kiểm tra cộng với tài liệu cộng với các kỳ vọng về khả năng tương thích.

## 3.10`Programs/`: Điểm vào có thể thực thi`Programs/`chứa các tệp nguồn cho các chương trình thực thi CPython.

Các tập tin điển hình bao gồm:```text
Programs/python.c
Programs/_testembed.c

Programs/python.clà điểm vào trình thông dịch dòng lệnh thông thường.

Đường dẫn khởi động đơn giản hóa trông như sau:```text main() ↓ initialize runtime ↓ configure interpreter ↓ run command, script, module, stdin, or REPL ↓ finalize runtime


## 3.11`Tools/`: Công cụ dành cho nhà phát triển`Tools/`chứa các chương trình trợ giúp để phát triển CPython.

Ví dụ bao gồm các công cụ dành cho:```text
generated file maintenance
bytecode and opcode metadata
C API inspection
test support
build support
freeze tooling
scripts used by maintainers
```Nội dung chính xác thay đổi theo thời gian. Nguyên tắc quan trọng là nhiều tệp được tạo trong CPython có đầu vào nguồn và công cụ tái tạo.`Tools/`thường là nơi những công cụ đó tồn tại.

Khi thay đổi ngữ pháp, khối Phòng khám đối số, định nghĩa opcode hoặc siêu dữ liệu được tạo, hãy kiểm tra quy trình làm việc của công cụ có liên quan trước khi chỉnh sửa đầu ra được tạo.

## 3.12`Doc/`: Nguồn tài liệu`Doc/`chứa nguồn tài liệu của CPython.

Tài liệu bao gồm:```text
language reference
library reference
C API reference
extending and embedding
how-to guides
tutorial
installing and using Python
```Đối với công việc nội bộ, tài liệu rất quan trọng vì những thay đổi về hành vi thường yêu cầu cập nhật tài liệu.

Thay đổi CPython có thể yêu cầu chỉnh sửa ở một số nơi:```text
implementation code
tests
documentation
news entry
C API docs
library docs
```Nguồn tài liệu sử dụng reStructuredText thay vì Markdown.

## 3.13 Thư mục nền tảng

CPython hỗ trợ nhiều nền tảng. Một số thư mục tồn tại chủ yếu dành cho cấu hình và bản dựng dành riêng cho nền tảng.

| Thư mục | Vai trò nền tảng |
| ------------------------------------------ | ------------------------------ |
|`PC/`| Nguồn/cấu hình dành riêng cho Windows |
|`PCbuild/`| Tệp xây dựng Visual Studio |
|`Mac/`| hỗ trợ macOS |
| tập tin nền tảng trong`Python/`Và`Modules/`| Triển khai dành riêng cho hệ điều hành |

Hỗ trợ nền tảng xuất hiện xuyên suốt cây thông qua quá trình biên dịch có điều kiện.

Mẫu ví dụ:```c
#ifdef MS_WINDOWS
    /* Windows-specific code */
#else
    /* POSIX-like code */
#endif
```Việc đọc nội bộ thường yêu cầu phân biệt logic thời gian chạy di động với các nhánh dành riêng cho nền tảng.

## 3.14 Đầu vào mã và nguồn được tạo

CPython chứa cả tệp viết tay và tệp được tạo.

Các khu vực được tạo phổ biến bao gồm:```text
parser output from grammar
AST-related generated files
opcode metadata and bytecode tables
Argument Clinic output
frozen importlib modules
configuration files
```Tệp được tạo thường có nhận xét ở gần đầu giải thích cách tạo tệp.

Trước khi chỉnh sửa khối cơ học đáng ngờ, hãy tìm các điểm đánh dấu như:```text
generated by
do not edit
clinic start generated code
autogenerated
```Chỉnh sửa thủ công đối với các vùng được tạo thường bị mất trong quá trình tái tạo.

## 3.15 Đường dẫn đọc qua kho lưu trữ

Con đường đọc đầu tiên tốt là:```text
Programs/python.c
    ↓
Python/pylifecycle.c
    ↓
Python/pythonrun.c
    ↓
Python/compile.c
    ↓
Python/ceval.c
    ↓
Objects/object.c
    ↓
Objects/typeobject.c
    ↓
Objects/dictobject.c
    ↓
Objects/listobject.c
```Đường dẫn này tuân theo quá trình thực thi từ quá trình khởi động đến hành vi thời gian chạy.

Đường dẫn đọc thứ hai cho nội bộ đối tượng:```text
Include/object.h
    ↓
Include/cpython/object.h
    ↓
Objects/object.c
    ↓
Objects/typeobject.c
    ↓
Objects/longobject.c
    ↓
Objects/unicodeobject.c
    ↓
Objects/listobject.c
    ↓
Objects/dictobject.c
```Đường dẫn thứ ba cho mã nguồn tới mã byte:```text
Grammar/
    ↓
Parser/
    ↓
Python/ast.c
    ↓
Python/symtable.c
    ↓
Python/compile.c
    ↓
Objects/codeobject.c
    ↓
Python/ceval.c
```## 3.16 Cách tìm mã cho tính năng Python

Bắt đầu từ tính năng Python, sau đó ánh xạ nó tới một hệ thống con.

| Tính năng | Các tập tin đầu tiên để kiểm tra |
| ------------- | ------------------------------------------ |
|`list.append` | `Objects/listobject.c`                     |
| `dict[key]`   | `Objects/dictobject.c`                     |
| `x.y`         | `Objects/object.c`, `Objects/typeobject.c` |
| `class C:`    | `Objects/typeobject.c`, `Python/compile.c` |
| `try/except`  | `Python/compile.c`, `Python/ceval.c`       |
| `import x`    | `Lib/importlib/`, `Python/import.c`        |
| `async def`   | `Python/compile.c`, `Objects/genobject.c`  |
| `with`        | `Python/compile.c`, `Python/ceval.c`       |
| `len(x)`      | `Python/bltinmodule.c`, loại khe |
|`print(x)`    | `Python/bltinmodule.c`, mô-đun I/O tệp |

Sử dụng các bài kiểm tra để xác nhận hành vi:```bash
./python -m test test_dict
./python -m test test_descr
./python -m test test_importlib
```## 3.17 Bố cục kho lưu trữ dưới dạng kiến trúc

Cấu trúc thư mục phản ánh kiến trúc của CPython.```text
Include/    exposes C interfaces
Objects/    defines runtime values
Python/     executes and manages programs
Parser/     understands syntax
Modules/    provides C-backed modules
Lib/        provides Python-level standard library
Lib/test/   protects behavior
Programs/   starts the executable
Tools/      maintains generated and developer workflows
Doc/        explains public behavior
```Bố cục này không hoàn hảo. Mã cũ hơn, các ràng buộc về nền tảng, khả năng tương thích ngược và các tệp được tạo sẽ tạo ra các ngoại lệ. Tuy nhiên, cấu trúc vẫn đủ mạch lạc để hướng dẫn việc đọc nguồn.

## 3.18 Tóm tắt chương

Kho lưu trữ CPython là một hệ thống làm việc, không phải là tập hợp các tệp riêng biệt.`Objects/`xác định giá trị Python là gì.`Python/`xác định cách chương trình biên dịch và thực thi.`Parser/`Và`Grammar/`xác định xử lý cú pháp.`Modules/`Và`Lib/`cung cấp thư viện chuẩn.`Include/`hiển thị giao diện C.`Lib/test/`xác định phần lớn mạng lưới an toàn hồi quy.

Một người đọc hiệu quả sẽ chuyển đổi giữa việc triển khai, kiểm tra và tài liệu. Nội bộ CPython trở nên dễ dàng hơn khi mỗi tệp nguồn có một vị trí rõ ràng trong kiến ​​trúc thời gian chạy.