pandas
基本情報 [必須]
| 項目 |
内容 |
| モジュールパス |
pandas |
| 種別 |
ライブラリルートパッケージ |
| ファイル数 |
4（直下: init.py, _typing.py, conftest.py, testing.py） |
| サブモジュール数 |
13（_config, _libs, _testing, api, arrays, compat, core, errors, io, plotting, tests, tseries, util） |
概要 [必須]
pandas は Python のデータ分析・操作ライブラリであり、ラベル付きデータ構造（DataFrame, Series, Index）を中心とした高速で柔軟なデータ処理機能を提供する。このルートパッケージは __init__.py を通じて 100 以上の公開 API（データ構造、dtype クラス、I/O 関数、データ操作関数、時系列機能等）を単一の pd 名前空間に集約し、ユーザーに統一的なインターフェースを提供する。_typing.py が型チェッカー向けの型エイリアスとプロトコルクラスを一元管理し、conftest.py が pytest テストスイート全体のフィクスチャ基盤を、testing.py がサードパーティ向けの公開テストユーティリティを提供する。
設計パターン [必須]
| パターン名 |
適用範囲 |
説明 |
| Facade |
init.py |
13 のサブモジュールに分散した機能を単一名前空間に集約 |
| Facade |
testing.py |
内部テストモジュール _testing から公開 API のみを re-export |
| Protocol (Structural Subtyping) |
_typing.py |
I/O バッファ、Arrow データ交換、シーケンス型等のプロトコルクラスを定義 |
| Centralized Type Registry |
_typing.py |
100 以上の型エイリアスを単一モジュールに集約し循環インポートを回避 |
| Fixture Factory / Parametrize |
conftest.py |
テストデータを辞書で管理し pytest フィクスチャで全パターンをパラメタライズ |
| Plugin Hook |
conftest.py |
pytest のプラグインフック機構でテスト設定を注入 |
アーキテクチャ [必須]
モジュール構成
pandas/
├── __init__.py - パッケージエントリポイント（全公開 API の集約）
├── _typing.py - 型エイリアス・プロトコルクラスの一元管理
├── conftest.py - pytest 設定・100+ フィクスチャ定義
├── testing.py - 公開テストユーティリティ（assert_frame_equal 等）
├── _config/ - オプション管理（get_option, set_option 等）
├── _libs/ - Cython/C 拡張（高速化基盤）
├── _testing/ - 内部テストインフラストラクチャ
├── api/ - 公開 toolkit API（extensions, types, typing 等）
├── arrays/ - ExtensionArray 実装
├── compat/ - 外部ライブラリ互換性レイヤー
├── core/ - コアデータ構造・アルゴリズム（Series, DataFrame, Index 等）
├── errors/ - 例外・警告クラス定義
├── io/ - データ入出力（CSV, Excel, JSON, SQL, Parquet 等）
├── plotting/ - 可視化機能
├── tests/ - テストスイート
├── tseries/ - 時系列機能（offsets, frequencies, holidays）
└── util/ - ユーティリティ関数
コンポーネント関連図
Mermaid形式:
graph TD
Init["__init__.py<br/>パッケージエントリポイント"] --> CoreAPI["core/api.py<br/>DataFrame, Series, Index"]
Init --> IoAPI["io/api.py<br/>read_csv, read_excel, ..."]
Init --> TseriesAPI["tseries/api.py<br/>offsets, infer_freq"]
Init --> Config["_config/<br/>get_option, set_option"]
Init --> Testing["testing.py<br/>公開テストユーティリティ"]
Testing --> InternalTesting["_testing/<br/>内部テストインフラ"]
Typing["_typing.py<br/>型エイリアス・Protocol"] -.->|provides types| CoreAPI
Typing -.->|provides types| IoAPI
Conftest["conftest.py<br/>pytest フィクスチャ"] -.->|provides fixtures| Tests["tests/<br/>テストスイート"]
機能一覧 [必須]
| 機能名 |
説明 |
主要ファイル |
| パッケージ初期化・API 集約 |
全公開 API を pd 名前空間に集約、依存関係チェック |
init.py |
| 型定義管理 |
100+ の型エイリアス、I/O バッファ・Arrow プロトコルクラス |
_typing.py |
| テストフィクスチャ基盤 |
100+ のパラメタライズドフィクスチャ、pytest フック設定 |
conftest.py |
| 公開テストユーティリティ |
DataFrame/Series/Index/ExtensionArray の等値検証 |
testing.py |
公開インターフェース [必須]
クラス / 関数
| 名前 |
種別 |
用途 |
| DataFrame |
class |
2 次元ラベル付きデータ構造 |
| Series |
class |
1 次元ラベル付きデータ構造 |
| Index |
class |
軸ラベル管理 |
| read_csv |
function |
CSV ファイル読み込み |
| read_excel |
function |
Excel ファイル読み込み |
| read_json |
function |
JSON ファイル読み込み |
| read_parquet |
function |
Parquet ファイル読み込み |
| concat |
function |
DataFrame/Series の結合 |
| merge |
function |
DataFrame の結合（SQL 風） |
| get_option / set_option |
function |
グローバルオプション管理 |
| testing.assert_frame_equal |
function |
DataFrame 等値検証 |
| testing.assert_series_equal |
function |
Series 等値検証 |
| SequenceNotStr |
Protocol class |
str/bytes を除外したシーケンス型 |
| ReadBuffer / WriteBuffer |
Protocol class |
I/O バッファプロトコル |
| ArrowArrayExportable / ArrowStreamExportable |
Protocol class |
Arrow ゼロコピーデータ交換プロトコル |
（上記は代表的な公開 API の抜粋。__init__.py の __all__ に 100 以上のシンボルが宣言されている）
依存関係 [必須]
外部依存（このモジュールが依存する外部パッケージ）
| パッケージ |
主要クラス |
用途 |
| numpy |
ndarray, dtype, integer, floating |
数値計算基盤、配列データ構造 |
| numpy.typing |
ArrayLike, DTypeLike, NDArray |
型注釈用 |
| dateutil |
parser, tz |
日付パース・タイムゾーン処理（ハード依存） |
| pytest |
fixture, mark, Item |
テストフレームワーク（conftest.py） |
| hypothesis |
strategies, settings |
プロパティベーステスト（conftest.py） |
| pytz |
timezone, FixedOffset |
タイムゾーン処理（オプション） |
| pyarrow |
— |
Arrow バックエンド（オプション） |
外部依存（このモジュールが依存する内部モジュール）
| 依存先モジュール |
主要クラス |
用途 |
| pandas/_config |
get_option, set_option, reset_option, describe_option, option_context, options |
オプション管理 API |
| pandas/compat |
is_numpy_dev |
numpy 互換性チェック |
| pandas/core/api |
DataFrame, Series, Index, 各 Dtype クラス, NA, NaT 等 |
主要データ構造・関数 |
| pandas/core/col |
col |
カラム選択関数 |
| pandas/core/dtypes/dtypes |
SparseDtype |
Sparse 型定義 |
| pandas/core/computation/api |
eval |
式評価エンジン |
| pandas/core/reshape/api |
concat, merge, pivot, melt 等 |
データ再形成関数群 |
| pandas/io/api |
read_csv, read_excel, read_json 等 |
I/O 関数群 |
| pandas/io/json/_normalize |
json_normalize |
JSON 正規化 |
| pandas/tseries/api |
infer_freq |
頻度推定 |
| pandas/tseries/offsets |
offsets |
日付オフセットクラス群 |
| pandas/util/_print_versions |
show_versions |
バージョン情報表示 |
| pandas/util/_tester |
test |
テスト実行 |
| pandas/_testing |
assert_frame_equal, assert_series_equal 等 |
テストアサーション（testing.py 経由） |
| pandas/_version_meson |
version, git_version |
バージョン情報 |
| pandas/_libs |
NaTType, Period, Timedelta, Timestamp |
型参照（_typing.py, TYPE_CHECKING 時） |
| pandas/core/ops |
radd, rsub 等 |
逆演算子関数（conftest.py） |
内部依存（このモジュールに依存するもの）[最重要]
pandas のルートパッケージであるため、import pandas を行うすべてのコード（内部テストスイート、外部ユーザーコード、サードパーティライブラリ）が本モジュールに依存する。_typing.py は pandas 内部のほぼ全モジュールから型インポートされ、conftest.py のフィクスチャは pandas/tests/ 配下の全テストファイルから利用される。
| 依存元モジュール |
主要ファイル |
用途 |
| pandas/tests/ |
全テストファイル |
conftest.py のフィクスチャ、pd.testing のアサーション |
| pandas/core/ |
frame.py, series.py, generic.py, indexes/base.py 等 |
_typing.py の型エイリアス |
| pandas/io/ |
parsers/readers.py, common.py 等 |
_typing.py の FilePath, ReadBuffer, WriteBuffer 等 |
| 外部ライブラリ |
— |
pd.testing.assert_frame_equal 等の公開テスト API |
データフロー [必須]
Mermaid形式:
flowchart TD
User["ユーザーコード<br/>import pandas as pd"] --> Init["__init__.py<br/>依存チェック → API 集約"]
Init --> PublicAPI["公開 API<br/>DataFrame, Series,<br/>read_csv, merge, ..."]
Init --> TestAPI["テスト API<br/>pd.testing.assert_*"]
Init --> ConfigAPI["設定 API<br/>get_option, set_option"]
Pytest["pytest 実行"] --> Conftest["conftest.py<br/>フック・フィクスチャ"]
Conftest --> Fixtures["100+ フィクスチャ"]
Fixtures --> Tests["tests/ テストスイート"]
Typing["_typing.py"] -.->|型情報| PublicAPI
セキュリティ考慮 [必須]
| 観点 |
対策状況 |
詳細 |
| 入力検証 |
なし |
ルートパッケージレベルでは外部入力を直接処理しない。入力検証は各サブモジュール（io, core 等）が担当 |
| 認証/認可 |
該当なし |
認証機能は含まない |
| 機密データ |
該当なし |
機密データの暗号化・マスキング処理はこのレベルでは行わない |
技術的負債・既知の問題 [必須]
| 種別 |
内容 |
影響範囲 |
優先度 |
| 設計 |
conftest.py が約 2,200 行と大きく、gh-31989 で分割しない判断が行われている |
conftest.py |
低 |
| 型システム |
pandas は py.typed ライブラリではなく（init.py のコメントに記載）、公開 API は型チェッカーでの補完が不完全 |
_typing.py, init.py |
低 |
| 設計 |
init.py の all リストが手動管理されており、新規 API 追加時の更新漏れリスクがある |
init.py |
低 |
| テスト |
conftest.py の一部フィクスチャに制限あり（nogil は False のみ、timedelta64 がコメントアウト） |
conftest.py |
低 |
拡張ポイント [必須]
| 変更内容 |
修正対象ファイル |
手順・注意点 |
| 新しい公開 API の追加 |
init.py |
1. 対応サブモジュールの api.py にシンボルを追加 2. init.py のインポート文に追記 3. all に追記 |
| 新しい型エイリアスの追加 |
_typing.py |
適切なカテゴリセクションに TypeAlias を追加。TYPE_CHECKING ブロック内のインポートが必要な場合は循環インポートに注意 |
| 新しい公開テスト関数の追加 |
testing.py, _testing/ |
1. _testing/ に実装を追加 2. testing.py のインポートに追記 3. all に追記 |
| 新しいテストフィクスチャの追加 |
conftest.py |
対応するセクション（Common arguments, Dtypes 等）に @pytest.fixture を追加 |
| 新しいインデックス型のテスト対応 |
conftest.py |
indices_dict に新しいキーとインデックスオブジェクトを追加 |
注意点・特記事項 [必須]
- 設計上の制約: init.py のインポート順序には依存関係があり、特に
_config → config_init の順序は必須。新規インポートの追加位置に注意すること
- パフォーマンス:
import pandas は多数のサブモジュールを即時インポートするため、初回インポート時間が比較的長い。これは意図的な設計であり、遅延インポートは採用していない
- 互換性: all は型チェッカー向けの公開 API 宣言であり、ドキュメントベースの公開 API 決定方針を将来的に py.typed に移行する可能性がある
配下ドキュメント [必須]
サブモジュール
ファイル