3. リポジトリのレイアウト
#3. リポジトリのレイアウト
CPython リポジトリは、インタプリタの主要なサブシステム (オブジェクト実装、ランタイム機構、コンパイラ パイプライン、パーサー、組み込みモジュール、標準ライブラリ、テスト、ドキュメント、プラットフォーム ビルド ファイル) を中心に編成されています。
適切な最初のパスは、ソース ツリーを責任のマップとして扱うことです。```text cpython/ Include/ Objects/ Python/ Parser/ Modules/ Lib/ Programs/ Tools/ Doc/ Grammar/ PC/ PCbuild/ Mac/
## 3.1 最上位構造
|ディレクトリ |主な役割 |
| ----------- | --------------------------------------------------- |
|`Include/`|パブリック、内部、プライベート C ヘッダー |
|`Objects/`|コア オブジェクト タイプの実装 |
|`Python/`|ランタイム、コンパイラ、インタープリタ ループ、初期化 |
|`Parser/`|トークナイザーとパーサーのサポート コード |
|`Grammar/`|文法入力ファイル |
|`Modules/`| C で書かれた組み込みモジュールと拡張モジュール
|`Lib/`| Python標準ライブラリ |
|`Lib/test/`| CPython 回帰テスト スイート |
|`Programs/`|実行可能エントリ ポイント |
|`Tools/`|開発者および構築ツール |
|`Doc/`|ドキュメントのソース |
|`PC/`| Windows 固有のソース ファイルと構成ファイル |
|`PCbuild/`| Windows ビルド システム |
|`Mac/`| macOS 固有のサポート |
内部情報を読み取るための最も重要なディレクトリは次のとおりです。```text
Include/
Objects/
Python/
Parser/
Modules/
Lib/test/
```これらのディレクトリには、オブジェクト モデル、実行エンジン、コンパイラ、パーサー、組み込み型、C API、およびテストが含まれます。
## 3.2`Include/`: C ヘッダー ファイル`Include/`CPython 自体、拡張モジュール、およびエンベッダーによって使用されるヘッダー ファイルが含まれています。
簡略化されたレイアウト:```text
Include/
Python.h
object.h
unicodeobject.h
listobject.h
dictobject.h
cpython/
internal/
```最も重要なファイルは次のとおりです。```c
#include <Python.h>
Python.h拡張モジュールの包括的なパブリック ヘッダーです。これには、他の多くのパブリック ヘッダーが含まれており、ほとんどの拡張機能作成者が使用する C API を公開します。
ヘッダーのカテゴリ
| ヘッダー領域 | 観客 | 安定性 |
|---|---|---|
Include/*.h |
パブリック C API ユーザー | 比較的安定している |
Include/cpython/ |
CPython 固有の API | 可搬性が低い |
Include/internal/ |
CPython 内部のみ | 自由に変更可能 |
この区別が重要です。 CPython 内のコードには内部ヘッダーを含めることができます。サードパーティの拡張機能は通常は使用すべきではありません。
例えば：```c #include "Python.h"
しかし：```c
#include "internal/pycore_runtime.h"
```CPython コア コード用です。これは、安定したパブリック API の一部ではない内部ランタイム構造を公開します。
##3.3`Objects/`: 組み込みオブジェクトの実装`Objects/`多くのコア Python オブジェクト タイプの C 実装が含まれています。
例:
|ファイル |道具 |
| ------------------- | --------------------------------- |
|`object.c`|基本オブジェクトの操作 |
|`typeobject.c`|型オブジェクト、クラス、MRO、スロット |
|`longobject.c`| Python の整数 |
|`floatobject.c`| Python フロート |
|`unicodeobject.c`| Python 文字列 |
|`bytesobject.c` | `bytes` |
| `bytearrayobject.c` | `bytearray` |
| `listobject.c` | `list` |
| `tupleobject.c` | `tuple` |
| `dictobject.c` | `dict` |
| `setobject.c` | `set`そして`frozenset` |
| `funcobject.c`|関数オブジェクト |
|`methodobject.c`|組み込みメソッドオブジェクト |
|`moduleobject.c`|モジュールオブジェクト |
|`genobject.c`|ジェネレーターとコルーチン |
|`frameobject.c`|フレームオブジェクトのサポート |
|`codeobject.c`|コードオブジェクト |
|`cellobject.c`|クロージャセル |
|`descrobject.c`|記述子 |
このディレクトリは、Python 値がどのように表現され、操作されるかを学ぶのに最適な場所です。
たとえば、リストの動作は主に次の場所に存在します。```text
Objects/listobject.c
```辞書の動作は主に次の場所に存在します。```text
Objects/dictobject.c
```文字列の動作は主に次のような場所に存在します。```text
Objects/unicodeobject.c
```Python が実行されると、次のようになります。```python
items = []
items.append(1)
```基礎となるリストの割り当て、サイズ変更、メソッドの検索、および追加操作には、最終的にコードが含まれます。`Objects/listobject.c`機械を入力してください`Objects/typeobject.c`。
##3.4`Python/`: ランタイム、コンパイラー、インタープリターコア`Python/`CPython の中心的な機構の多くが含まれています。
重要なファイルには次のものが含まれます。
|ファイル |役割 |
| ------------------ | -------------------------------------------------- |
|`ceval.c`|バイトコード評価ループ |
|`bytecodes.c`|最新の CPython におけるバイトコード命令の定義 |
|`compile.c`| AST からコードオブジェクトへのコンパイラ |
|`symtable.c`|シンボルテーブル分析 |
|`ast.c`| ASTサポート |
|`pythonrun.c`|高レベルの実行エントリ ポイント |
|`pylifecycle.c`|実行時の初期化と終了処理 |
|`import.c`|輸入サポート |
|`errors.c`|例外状態およびエラー API |
|`traceback.c`|トレースバックのサポート |
|`sysmodule.c`|の実装`sys` |
| `bltinmodule.c`|組み込み関数と組み込みモジュール |
|`marshal.c`|コード オブジェクトの内部シリアル化形式 |
|`thread.c`|スレッド抽象化レイヤー |
|`context.c`|コンテキスト変数のサポート |
|`bootstrap_hash.c`|ハッシュシークレットの初期化 |
ファイル名は単なるラベルではありません。これらは、深いランタイム サブシステムを反映しています。
### インタプリタの実行
バイトコード インタプリタは評価ループを中心に配置されています。歴史的にこれは`ceval.c`。新しい CPython バージョンでは、オペコード定義と生成されたインタープリター部分が追加のファイルに分割される場合があります。
概念的な役割:```text
frame enters evaluation
↓
bytecode instruction fetched
↓
instruction dispatch
↓
object operation
↓
stack and frame state updated
```### コンパイラ パイプライン
コンパイラ コードは、AST ノードをコード オブジェクトに降格します。
簡略化されたパス:```text
source text
↓
tokens
↓
parse tree
↓
AST
↓
symbol table
↓
compiler
↓
code object
```通常、キー ファイルは次のとおりです。```text
Parser/
Python/ast.c
Python/symtable.c
Python/compile.c
Objects/codeobject.c
```##3.5`Parser/`: トークナイザーとパーサーのサポート`Parser/`トークナイザー、パーサー ジェネレーター サポート、パーサー実装ファイル、および生成されたパーサー関連コードが含まれています。
重要な分野には次のようなものがあります。
|エリア |役割 |
| ---------------------- | ------------------------------------ |
|トークナイザー |ソーステキストをトークンに変換します |
|パーサー |トークンから構文構造を構築します。
|ペグ機械 | Python の PEG パーサーをサポート |
|生成されたパーサー ファイル |文法定義から生成 |
パーサーの仕事は、ソース テキストが有効な Python 構文であるかどうかを判断し、後に AST となる構造を構築することです。
例：```python
x = 1 + 2
```パーサーは以下を認識する必要があります。```text
assignment statement
target name x
expression 1 + 2
integer literal 1
integer literal 2
binary addition operator
```解析はセマンティック分析の前に行われます。パーサーは構文を認識します。シンボル テーブル パスは、名前がローカル変数、グローバル変数、フリー変数、またはセル変数であるかどうかを後で決定します。
##3.6`Grammar/`: 文法定義`Grammar/`パーサー関連のコードを生成するために使用される文法入力ファイルが含まれています。
この文法は、CPython のパーサー ツールによって使用される形式で Python 構文を定義します。
内部の作業では、文法の変更は大きな影響を与えます。構文の変更は以下に影響を与える可能性があります。```text
parser generation
AST generation
compiler behavior
error messages
tests
documentation
tools that parse Python
```文法レベルの変更には、多くの場合、再生成と対象を絞ったテストが必要です。
通常のワークフローは次のとおりです。```text
edit grammar input
regenerate parser files
rebuild CPython
run parser, AST, compiler, and syntax tests
```##3.7`Modules/`: 内蔵および拡張モジュール`Modules/`CPython に同梱されている多くの C モジュールが含まれています。
例:
|ファイルまたはディレクトリ |モジュール |
| ------------------- | ------------------------ |
|`_io/`| I/O 実装 |
|`_decimal/`| 10 進アクセラレータ |
|`_sqlite/`| SQLite モジュール |
|`_ssl.c`| SSL サポート |
|`_hashopenssl.c`| OpenSSL によるハッシュ |
|`_ctypes/` | `ctypes` |
| `arraymodule.c` | `array` |
| `mathmodule.c` | `math` |
| `itertoolsmodule.c` | `itertools` |
| `functoolsmodule.c` | `_functools` |
| `posixmodule.c` | `os`プラットフォームの運用 |
|`timemodule.c` | `time`|
一部の標準ライブラリ モジュールは Python で書かれており、C アクセラレータを使用します。`Modules/`。
たとえば、パブリック Python モジュールは次の場所に存在する可能性があります。`Lib/`、パフォーマンス重視の民間ヘルパーが住んでいる間、`Modules/`。
このパターンは、ホット パスの高速な C 実装を維持しながら、CPython にクリーンなパブリック API を提供します。
## 3.8`Lib/`: 標準ライブラリ`Lib/`Pythonの標準ライブラリが含まれています。
例:
|パス |役割 |
| -------------------- | -------------------------------- |
|`Lib/os.py`| OSインターフェース層 |
|`Lib/pathlib/`|オブジェクト指向のパス |
|`Lib/importlib/`|インポートシステムの導入 |
|`Lib/asyncio/`|非同期 I/O フレームワーク |
|`Lib/collections/`|収集ユーティリティ |
|`Lib/dataclasses.py`|データクラスのサポート |
|`Lib/typing.py`|タイピングサポート |
|`Lib/unittest/`|単体テストフレームワーク |
|`Lib/json/`| JSON の実装 |
|`Lib/concurrent/`|先物とプロセス/スレッド プール |
CPython の内部の多くは、最初に Python レベルの標準ライブラリを読むと理解しやすくなります。
例えば、`importlib`Python コードのインポート システムの大部分が含まれています。 CPython は特別にブートストラップしますが、大部分は Python として読み取れるままです。
##3.9`Lib/test/`: 回帰テスト`Lib/test/`CPython のテスト スイートが含まれています。
このディレクトリは内部作業に不可欠です。
例:
|テストファイル |フォーカス |
| ------------------- | -------------------- |
|`test_dict.py`|辞書の動作 |
|`test_list.py`|リストの動作 |
|`test_gc.py`|ガベージコレクター |
|`test_sys.py` | `sys`モジュール |
|`test_dis.py`|バイトコードの逆アセンブリ |
|`test_compile.py`|コンパイラの動作 |
|`test_ast.py`| AST の動作 |
|`test_importlib/`|輸入システム |
|`test_capi/`| C API の動作 |
|`test_threading.py`|スレッド動作 |
サブシステムを調査するときは、実装ファイルとそのテストを組み合わせます。
|実装 |テスト |
| ---------------------- | ------------------------- |
|`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`|
この習慣により、コードを単独で読むことができなくなります。 CPython の動作は、コード、テスト、ドキュメント、互換性の期待によって定義されます。
##3.10`Programs/`: 実行可能なエントリ ポイント`Programs/`CPython 実行可能プログラムのソース ファイルが含まれています。
一般的なファイルには次のようなものがあります。```text
Programs/python.c
Programs/_testembed.c
Programs/python.cは、通常のコマンドライン インタープリタのエントリ ポイントです。
簡略化された起動パスは次のようになります。```text main() ↓ initialize runtime ↓ configure interpreter ↓ run command, script, module, stdin, or REPL ↓ finalize runtime
##3.11`Tools/`: 開発者ツール`Tools/`CPython 開発用のヘルパー プログラムが含まれています。
例には、次のツールが含まれます。```text
generated file maintenance
bytecode and opcode metadata
C API inspection
test support
build support
freeze tooling
scripts used by maintainers
```正確な内容は時間の経過とともに変化します。重要なルールは、CPython で生成された多くのファイルにはソース入力と再生成ツールがあるということです。`Tools/`多くの場合、これらのツールが存在する場所です。
文法、Argument Clinic ブロック、オペコード定義、または生成されたメタデータを変更する場合は、生成された出力を編集する前に、関連するツールのワークフローを確認してください。
##3.12`Doc/`: ドキュメントのソース`Doc/`CPython のドキュメント ソースが含まれています。
ドキュメントの内容は次のとおりです。```text
language reference
library reference
C API reference
extending and embedding
how-to guides
tutorial
installing and using Python
```内部の作業では、動作の変更にはドキュメントの更新が必要になることが多いため、ドキュメントが重要です。
CPython の変更には、いくつかの場所での編集が必要になる場合があります。```text
implementation code
tests
documentation
news entry
C API docs
library docs
```ドキュメント ソースでは、Markdown ではなく reStructuredText が使用されます。
## 3.13 プラットフォームディレクトリ
CPython は多くのプラットフォームをサポートしています。一部のディレクトリは、主にプラットフォーム固有の構成とビルドのために存在します。
|ディレクトリ |プラットフォームの役割 |
| ------------------------------------------ | ------------------------------ |
|`PC/`| Windows 固有のソース/構成 |
|`PCbuild/`| Visual Studio ビルド ファイル |
|`Mac/`| macOS のサポート |
|プラットフォームファイル`Python/`そして`Modules/`| OS 固有の実装 |
プラットフォームのサポートは、条件付きコンパイルを通じてツリー全体に表示されます。
パターン例:```c
#ifdef MS_WINDOWS
/* Windows-specific code */
#else
/* POSIX-like code */
#endif
```内部の読み取りでは、多くの場合、移植可能なランタイム ロジックとプラットフォーム固有のブランチを区別する必要があります。
## 3.14 生成されたコードとソース入力
CPython には、手書きのファイルと生成されたファイルの両方が含まれています。
一般的に生成される領域は次のとおりです。```text
parser output from grammar
AST-related generated files
opcode metadata and bytecode tables
Argument Clinic output
frozen importlib modules
configuration files
```生成されたファイルには、通常、その作成方法を説明するコメントが上部近くにあります。
機械的であると思われるブロックを編集する前に、次のようなマーカーを探してください。```text
generated by
do not edit
clinic start generated code
autogenerated
```生成された領域に対する手動編集は通常、再生成中に失われます。
## 3.15 リポジトリを介した読み取りパス
最初に読むのに適したパスは次のとおりです。```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
```このパスは、プロセスの起動からランタイム動作までの実行をたどります。
オブジェクト内部の 2 番目の読み取りパス:```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
```ソースからバイトコードへの 3 番目のパス:```text
Grammar/
↓
Parser/
↓
Python/ast.c
↓
Python/symtable.c
↓
Python/compile.c
↓
Objects/codeobject.c
↓
Python/ceval.c
```## 3.16 Python 機能のコードを見つける方法
Python 機能から開始して、それをサブシステムにマップします。
|特集 |最初に検査するファイル |
| ------------- | ------------------------------------------ |
|`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`、タイプ スロット |
|`print(x)` | `Python/bltinmodule.c`、ファイル I/O モジュール |
テストを使用して動作を確認します。```bash
./python -m test test_dict
./python -m test test_descr
./python -m test test_importlib
```## 3.17 アーキテクチャとしてのリポジトリのレイアウト
ディレクトリ構造は 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
```このレイアウトは完璧ではありません。古いコード、プラットフォームの制約、下位互換性、および生成されたファイルによって例外が発生します。それでも、その構造はソースを読むのに十分な一貫性を持っています。
## 3.18 章の概要
CPython リポジトリは、分離されたファイルのコレクションではなく、動作するシステムです。`Objects/`Python の値が何であるかを定義します。`Python/`プログラムがどのようにコンパイルおよび実行されるかを定義します。`Parser/`そして`Grammar/`構文処理を定義します。`Modules/`そして`Lib/`標準ライブラリを提供します。`Include/`C インターフェイスを公開します。`Lib/test/`回帰セーフティネットの大部分を定義します。
生産的な読者は、実装、テスト、ドキュメントの間を行き来します。各ソース ファイルがランタイム アーキテクチャ内で明確な場所を確保されると、CPython の内部構造がより簡単になります。