# 機能設計書 43-Python

## 概要

本ドキュメントは、space-vimにおけるPython言語サポート機能の設計仕様を定義する。本機能はpython-mode、vim-pythonsense等のプラグインを統合し、Pythonファイル編集時のコード補完、リント、フォーマット、実行機能を提供する。

### 本機能の処理概要

本機能は、Pythonファイル（.py）の編集時に、IDE相当の開発支援機能を提供する。具体的には、コードの構文チェック、自動補完、フォーマット、実行、そしてPythonコード構造のナビゲーション機能を含む。

**業務上の目的・背景**：Pythonは最も広く使用されているプログラミング言語の一つであり、データサイエンス、Web開発、自動化スクリプト等、多岐にわたる分野で使用されている。Vim上でのPython開発を効率化し、コード品質を向上させることで、開発生産性の向上を実現する。

**機能の利用シーン**：
- Pythonスクリプトの作成・編集
- コードの構文チェックとスタイルガイド準拠確認
- yapf/isortによる自動フォーマット
- Python REPLとの連携・スクリプト実行
- クラス・関数間のナビゲーション

**主要な処理内容**：
1. Pythonファイルタイプ検出時のftplugin設定適用
2. python-modeプラグインの遅延読み込み
3. ALE連携によるflake8リンターの実行
4. yapf/isortによるコードフォーマット
5. asyncrun.vimと連携した非同期スクリプト実行
6. autoflakeによる未使用インポート削除

**関連システム・外部連携**：
- python-mode/python-mode プラグイン
- jeetsukumaran/vim-pythonsense プラグイン
- flake8（リンター）
- yapf/black（フォーマッター）
- isort（インポート整列）
- autoflake（未使用コード削除）
- asyncrun.vim（非同期実行）

**権限による制御**：特になし（全ユーザー共通機能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 補完ポップアップ | 参照画面 | Pythonコードの補完候補表示 |
| 10 | ALE/Syntastic（構文エラー表示） | 参照画面 | flake8によるリアルタイム構文チェック |
| 18 | Terminal（ターミナル画面） | 結果表示画面 | Pythonスクリプトの実行結果表示 |

## 機能種別

言語サポート / コード補完 / リント / フォーマット / 実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:pymode_lint_checkers | List | No | python-mode用リンター | 文字列のリスト |
| g:pymode_trim_whitespaces | Number | No | 末尾空白の自動削除 | 0または1 |
| g:pymode_rope | Number | No | Rope（リファクタリング）の有効化 | 0または1 |
| g:pymode_indent | Number | No | インデント設定の有効化 | 0または1 |
| g:pymode_folding | Number | No | 折りたたみの有効化 | 0または1 |
| g:pymode_breakpoint_bind | String | No | ブレークポイント挿入キー | キーシーケンス |
| g:spacevim_python_run | String | No | Python実行コマンド | 実行可能パス |
| g:spacevim_python_fmt | String | No | フォーマッター指定 | 'yapf'/'black'等 |
| b:ale_linters | List | No | ALE用リンター | 文字列のリスト |
| b:ale_fixers | List | No | ALE用Fixer | 文字列のリスト |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 補完候補 | List | Python識別子の補完候補 |
| リント結果 | List | 構文エラー・警告の一覧 |
| フォーマット済みコード | String | 整形されたPythonコード |
| 実行結果 | String | スクリプト実行の標準出力・エラー |

### 出力先

- 補完ポップアップウィンドウ
- サインカラム（エラー・警告表示）
- バッファ（フォーマット適用）
- Quickfix/ターミナル（実行結果）

## 処理フロー

### 処理シーケンス

```
1. Pythonファイルオープン
   └─ ftplugin/python.vim の読み込み

2. レイヤー有効化確認
   └─ spacevim#load('python') の判定

3. バッファ設定適用
   └─ foldmethod, tabstop, textwidth の設定

4. タイマーによる遅延読み込み
   └─ 300ms後にpython-mode読み込み

5. ALE設定適用
   └─ b:ale_linters = ['flake8']
   └─ b:ale_fixers = ['remove_trailing_lines', 'isort', 'yapf']

6. キーマッピング設定
   └─ LocalLeader キーバインド
```

### フローチャート

```mermaid
flowchart TD
    A[Pythonファイルオープン] --> B{pythonレイヤー有効?}
    B -->|No| C[終了]
    B -->|Yes| D[ftplugin設定適用]
    D --> E[バッファ設定]
    E --> F{タイマー有効?}
    F -->|Yes| G[300ms後にpython-mode読み込み]
    F -->|No| H[即時読み込み]
    G --> I[ALE設定適用]
    H --> I
    I --> J[キーマッピング設定]
    J --> K[編集開始]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | レイヤー有効化ルール | pythonレイヤーが有効な場合のみftplugin処理を実行 | ファイルオープン時 |
| BR-43-02 | リント統合ルール | syntax-checkingレイヤー有効時はpymode_lintを無効化 | レイヤー読み込み時 |
| BR-43-03 | 遅延読み込みルール | 起動時間最適化のため300ms後にpython-modeを読み込み | タイマー有効時 |
| BR-43-04 | フォーマッターフォールバック | ALEFix存在時はALEを使用、なければ直接yapf実行 | フォーマット実行時 |

### 計算ロジック

該当なし

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

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フォーマッター未インストール | yapf/blackが未インストール | エラーメッセージ表示 |
| - | リンター未インストール | flake8が未インストール | ALE経由でエラー表示 |
| - | Python未インストール | python実行可能ファイルが見つからない | パス設定の案内 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- python-modeの遅延読み込みにより起動時間を最適化
- asyncrun.vimによる非同期実行でエディタの応答性を維持

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

- 外部ツール（flake8, yapf等）はローカル環境のものを使用
- 任意のPythonコードを実行するため、信頼できるコードのみを対象とする

## 備考

- g:spacevim_python_fmt で使用するフォーマッターを変更可能（デフォルト: yapf）
- autoflakeによる未使用インポート削除は LocalLeader+a で手動実行

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

Python言語サポートで使用される設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+lang/python/config.vim` | python-mode用のグローバル設定変数 |

**読解のコツ**: `g:pymode_*` プレフィックスの変数がpython-mode固有の設定。

#### Step 2: エントリーポイントを理解する

Pythonファイルオープン時の処理起点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | python.vim | `core/ftplugin/python.vim` | ftpluginエントリーポイント |

**主要処理フロー**:
1. **1-4行目**: 二重読み込み防止とレイヤー有効化チェック
2. **6行目**: `setlocal foldmethod=indent tabstop=4 textwidth=79` でバッファ設定
3. **8-10行目**: タイマー有効時の遅延読み込みスケジュール
4. **12-17行目**: ALE用リンター・Fixer設定
5. **19-24行目**: LocalLeaderキーマッピング定義

#### Step 3: プラグイン登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | packages.vim | `layers/+lang/python/packages.vim` | プラグイン登録 |

**主要処理フロー**:
- **1行目**: vim-pythonsense の即時登録
- **2-6行目**: python-mode の条件付き登録（speed_up_via_timer判定）

#### Step 4: 遅延読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | defer.vim | `core/autoload/spacevim/defer.vim` | 遅延読み込み実装 |

**主要処理フロー**:
- **81-83行目**: `spacevim#defer#python()` 関数でpython-mode読み込み

#### Step 5: 言語固有関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | python.vim | `core/autoload/spacevim/lang/python.vim` | Python言語固有関数 |

**主要処理フロー**:
- **1-7行目**: `spacevim#lang#python#run()` - スクリプト実行
- **9-11行目**: `spacevim#lang#python#stop()` - 実行停止
- **36-46行目**: `spacevim#lang#python#fmt()` - フォーマット実行
- **48-96行目**: `spacevim#lang#python#autoflake()` - 未使用コード削除

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

```
Pythonファイルオープン
    │
    ├─ core/ftplugin/python.vim
    │      ├─ spacevim#load('python') 確認
    │      ├─ setlocal 設定
    │      ├─ timer_start(300, 'spacevim#defer#python')
    │      ├─ b:ale_linters/b:ale_fixers 設定
    │      └─ nnoremap キーマッピング
    │
    ├─ 300ms後
    │      └─ core/autoload/spacevim/defer.vim
    │             └─ spacevim#defer#python()
    │                    └─ plug#load('python-mode')
    │
    └─ キー操作時
           ├─ LocalLeader+= → spacevim#lang#python#fmt()
           ├─ F5 / LocalLeader+cc → spacevim#lang#python#run()
           ├─ LocalLeader+cs → spacevim#lang#python#stop()
           └─ LocalLeader+a → spacevim#lang#python#autoflake()
```

### データフロー図

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

Pythonソースコード ──▶ ftplugin設定適用 ──────▶ バッファ設定
     │
     ├─────────────────▶ ALE/flake8 リント ────▶ エラー表示
     │
     ├─────────────────▶ yapf/isort フォーマット ▶ 整形済みコード
     │
     └─────────────────▶ asyncrun.vim 実行 ────▶ ターミナル出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| python.vim | `core/ftplugin/python.vim` | 設定 | Pythonファイル用ftplugin |
| packages.vim | `layers/+lang/python/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+lang/python/config.vim` | 設定 | python-mode設定 |
| python.vim | `core/autoload/spacevim/lang/python.vim` | ソース | Python言語固有関数 |
| defer.vim | `core/autoload/spacevim/defer.vim` | ソース | 遅延読み込み処理 |
