# 機能設計書 68-Python言語サポート

## 概要

本ドキュメントは、Doom EmacsにおけるPython言語サポートモジュールの機能設計を記述する。本モジュールはPython開発に必要な編集、実行、テスト、環境管理機能を包括的に提供する。

### 本機能の処理概要

Python言語サポートモジュールは、Python/Cythonコードの編集サポート、REPL連携、テストフレームワーク統合、仮想環境管理（pyenv/uv/conda/poetry/pipenv/pyvenv）、LSP連携などの機能を提供する。

**業務上の目的・背景**：
Pythonはデータサイエンス、Web開発、自動化など幅広い分野で使用される主要言語である。本モジュールにより、Pythonプロジェクトの効率的な開発環境を提供し、仮想環境管理やテスト実行をシームレスに行える。

**機能の利用シーン**：
- Pythonスクリプト/モジュールの編集
- IPython/Jupyter REPLでの対話的実行
- pytest/noseによるテスト実行
- pyenv/uv/condaによる環境切り替え
- LSPによる補完・診断

**主要な処理内容**：
1. python-mode/python-ts-modeによる編集サポート
2. REPL連携（python-shell, IPython, Jupyter）
3. テストフレームワーク統合（pytest, nose）
4. 仮想環境管理（pyenv, uv, conda, poetry, pipenv, pyvenv）
5. インポート管理（pyimport, py-isort）
6. LSP連携（pyright/pylsp）

**関連システム・外部連携**：
- python-mode：メジャーモード
- lsp-pyright：LSPクライアント
- pytest/nose：テストフレームワーク
- pyenv/uv/conda/poetry/pipenv：環境管理

**権限による制御**：
本機能に権限による制御は存在しない。

## 関連画面

本機能は画面を持たないエディタ機能である。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | コード編集、REPL、テスト実行 |

## 機能種別

言語サポート / REPL連携 / テスト統合 / 環境管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +python-ipython-command | list | No | IPython起動コマンド | 実行可能コマンドリスト |
| +python-jupyter-command | list | No | Jupyter起動コマンド | 実行可能コマンドリスト |

### 入力データソース

- Pythonソースファイル（.py）
- プロジェクト設定（pyproject.toml, requirements.txt, setup.py等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| repl-buffer | buffer | REPL出力バッファ |
| test-output | buffer | テスト結果バッファ |

### 出力先

- *Python* REPLバッファ
- *pytest* / *nosetests* バッファ

## 処理フロー

### 処理シーケンス

```
1. .py ファイルオープン
   └─ python-mode/python-ts-mode 有効化

2. モード初期化
   ├─ REPL ハンドラ設定
   ├─ docsets 設定
   ├─ ligatures 設定
   ├─ flycheck 設定
   └─ LSP 起動（+lsp時）

3. 仮想環境検出
   ├─ pyvenv-track-virtualenv
   ├─ pyenv-mode（+pyenv時）
   ├─ uv-mode（+uv時）
   └─ conda（+conda時）

4. 編集・実行
   ├─ コード補完
   ├─ REPL送信
   └─ テスト実行
```

### フローチャート

```mermaid
flowchart TD
    A[.py ファイルオープン] --> B{+tree-sitter?}
    B -->|Yes| C[python-ts-mode]
    B -->|No| D[python-mode]
    C --> E[共通初期化]
    D --> E
    E --> F[REPL/docsets/ligatures設定]
    F --> G{+lsp?}
    G -->|Yes| H[lsp!]
    G -->|No| I[環境検出]
    H --> I
    I --> J{pyenv/uv/conda?}
    J -->|pyenv| K[pyenv-mode-set]
    J -->|uv| L[uv-mode]
    J -->|conda| M[conda-env]
    J -->|pyvenv| N[pyvenv-track]
    K --> O[編集開始]
    L --> O
    M --> O
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Python3優先 | python3があればそれを使用 | python-shell-interpreter未設定時 |
| BR-02 | BASIC REPL | Python 3.13+でPYTHON_BASIC_REPL=1を設定 | pyrepl対策 |
| BR-03 | shebang検出 | shebangからPythonバージョンを検出 | flycheck設定時 |
| BR-04 | tab-width同期 | python-indent-offsetをtab-widthに反映 | python-mode-hook |

### 計算ロジック

特になし。

## データベース操作仕様

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Python未インストール | pythonコマンドが見つからない | doctor.elで検出 |
| - | 仮想環境未検出 | 仮想環境が見つからない | デフォルトPython使用 |

### リトライ仕様

特になし。

## トランザクション仕様

該当なし。

## パフォーマンス要件

特になし。

## セキュリティ考慮事項

- 仮想環境のPythonパスを信頼して使用
- REPLでの任意コード実行に注意

## 備考

- +lspフラグでLSPサポートを有効化
- +pyrightフラグでlsp-pyrightを使用
- +pyenvフラグでpyenv-modeを有効化
- +uvフラグでuv-modeを有効化
- +condaフラグでconda環境管理を有効化
- +poetryフラグでpoetry連携を有効化
- +cythonフラグでCythonサポートを有効化
- +tree-sitterフラグでpython-ts-modeを使用

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: 設定変数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/lang/python/config.el` | カスタム変数定義（3-7行目） |

**読解のコツ**:
- `+python-ipython-command`: IPython起動オプション
- `+python-jupyter-command`: Jupyter起動オプション

#### Step 2: python-mode設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/lang/python/config.el` | python use-package（16-106行目） |

**主要処理フロー**:
- **22-25行目**: tree-sitter設定
- **34-36行目**: LSP設定
- **38-41行目**: REPL handler設定
- **43-44行目**: docsets設定
- **46-62行目**: ligatures設定
- **68-71行目**: Python3優先設定
- **78行目**: PYTHON_BASIC_REPL=1設定
- **80-97行目**: flycheck executable設定

#### Step 3: 環境管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/lang/python/config.el` | pipenv（173-196行目） |
| 3-2 | config.el | `modules/lang/python/config.el` | pyvenv（199-210行目） |
| 3-3 | config.el | `modules/lang/python/config.el` | pyenv-mode（214-223行目） |
| 3-4 | config.el | `modules/lang/python/config.el` | uv-mode（226-243行目） |
| 3-5 | config.el | `modules/lang/python/config.el` | conda（246-256行目） |
| 3-6 | config.el | `modules/lang/python/config.el` | poetry（259-263行目） |

#### Step 4: テストフレームワークを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/lang/python/config.el` | nose（132-151行目） |
| 4-2 | config.el | `modules/lang/python/config.el` | python-pytest（154-167行目） |

#### Step 5: autoload関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | python.el | `modules/lang/python/autoload/python.el` | REPL関連関数 |

**主要処理フロー**:
- **4-21行目**: +python-executable-find（実行ファイル検出）
- **24-42行目**: +python/open-repl（REPL起動）
- **45-54行目**: +python/open-ipython-repl
- **57-67行目**: +python/open-jupyter-repl

### プログラム呼び出し階層図

```
python-mode/python-ts-mode
    │
    ├─ set-repl-handler! (+python/open-repl)
    │
    ├─ set-docsets! ("Python 3", "NumPy", "SciPy", "Pandas")
    │
    ├─ set-ligatures!
    │
    ├─ [+lsp]
    │      └─ lsp!
    │
    └─ [環境管理]
           ├─ pyvenv-track-virtualenv
           ├─ +python-pyenv-mode-set-auto-h
           ├─ +python-uv-mode-set-auto-h
           └─ conda-env-initialize-interactive-shells

+python/open-repl
    │
    └─ run-python
           │
           └─ [pipenv プロジェクト?]
                  └─ pipenv run python
```

### データフロー図

```
[入力]                    [処理]                           [出力]

.py ファイル ───▶ python-mode ───▶ シンタックスハイライト
                      │
                      ├─ LSP連携 ───▶ 補完・診断
                      │
                      ├─ REPL ───▶ 実行結果
                      │
                      └─ pytest ───▶ テスト結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/lang/python/config.el` | ソース | メイン設定 |
| python.el | `modules/lang/python/autoload/python.el` | ソース | REPL/インポート関数 |
| pyenv.el | `modules/lang/python/autoload/pyenv.el` | ソース | pyenv連携 |
| uv.el | `modules/lang/python/autoload/uv.el` | ソース | uv連携 |
| conda.el | `modules/lang/python/autoload/conda.el` | ソース | conda連携 |
| doctor.el | `modules/lang/python/doctor.el` | 診断 | Python環境診断 |
| packages.el | `modules/lang/python/packages.el` | 設定 | 依存パッケージ定義 |
