#0122（2025/05/05） `.toml` ファイル活用ガイド

# Python環境構築における `.toml` ファイル活用ガイド 

### 1. はじめに

中級エンジニアとして、自身のプロジェクトで再現性・可搬性の高い環境構築を目指すには、従来の `requirements.txt` に加え、`pyproject.toml` を活用する方法が効果的です。

本ガイドでは、TOML形式の概要から、Poetryによる環境構築の詳細手順とディレクトリ構成、`poetry new` コマンドの内部動作、類似技術との比較までを解説します。

---

### 2. TOML とは

* **TOML**: "Tom's Obvious, Minimal Language" の略。
* **特徴**: キー/値ペアによるシンプルな記述、セクションによる階層的構造、コメントサポート。
* **標準化**: PEP 517/518/621 に準拠し、`pyproject.toml` が公式にビルド・依存管理設定ファイルとして採用。

```toml
# コメントは # で始める
[tool.example]
name = "sample_project"
version = "0.1.0"
```

---

### 3. TOML サンプル: `pyproject.toml`

```toml
[tool.poetry]
name = "awesome-app"
version = "0.1.0"
description = "中級者向けサンプルプロジェクト"
authors = ["aaa <aaaa@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.95.0"
uvicorn = "^0.22.0"

[tool.poetry.dev-dependencies]
pytest = "^7.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
```

* `[tool.poetry]` 配下にメタ情報
* `dependencies` / `dev-dependencies` の分離により、本番と開発用依存を明確に管理

---

### 4. 環境構築のサンプルコードとディレクトリ構成

#### 4.1 Poetry を使った例（詳細）

1. **Poetry のインストール**

   ```bash
   curl -sSL https://install.python-poetry.org | python3 -
   export PATH="$HOME/.local/bin:$PATH"
   poetry --version  # 確認
   ```

2. **新規プロジェクトの作成**

   ```bash
   poetry new awesome-app
   cd awesome-app
   ```

   #### ✅ `poetry new` で実行される内容

   `poetry new プロジェクト名` は、以下のような Python パッケージの雛形を自動生成します：

   ```
   awesome-app/
   ├── pyproject.toml         # 依存とビルド設定（TOML形式）
   ├── README.rst             # プロジェクト説明用
   ├── awesome_app/           # アプリケーション本体（パッケージ）
   │   ├── __init__.py
   │   └── main.py            # 必要に応じて作成
   └── tests/                 # 単体テスト用ディレクトリ
       ├── __init__.py
       └── test_awesome_app.py
   ```

3. **依存ライブラリの追加**

   ```bash
   poetry add fastapi uvicorn
   poetry add --dev pytest
   ```

   * `dependencies`: 本番環境や実行時に必要なパッケージ
   * `dev-dependencies`: 開発・テスト・静的解析にのみ使うツール

4. **仮想環境の作成・起動**

   ```bash
   poetry shell               # 自動で仮想環境に入る（Poetry 2.0 ではプラグイン必要）
   poetry env info --path     # 仮想環境のパス確認
   source $(poetry env info --path)/bin/activate  # 直接アクティブにする方法
   ```

5. **アプリケーションの実行・開発フロー**

   * 開発サーバ起動：

     ```bash
     uvicorn awesome_app.main:app --reload
     ```
   * テスト実行：

     ```bash
     pytest
     ```
   * スクリプト定義（任意）：

     ```toml
     [tool.poetry.scripts]
     start = "awesome_app.main:main"
     ```

     ```bash
     poetry run start
     ```

6. **パッケージのビルドと公開**

   * ビルド：

     ```bash
     poetry build
     ```

     → `dist/` 以下に `.whl` と `.tar.gz` を生成

   * 公開：

     ```bash
     poetry publish --username __token__ --password <your_api_token>
     ```

   PyPI への公開により、`pip install あなたのパッケージ名` で他者に使ってもらえる状態になります。

---

### 5. 本番環境と開発環境の使い分け：`dependencies` と `dev-dependencies`

| セクション                            | いつ使う？     | 例                             | インストール範囲                              |
| -------------------------------- | --------- | ----------------------------- | ------------------------------------- |
| `[tool.poetry.dependencies]`     | 本番・実行時に必要 | fastapi, requests, sqlalchemy | `poetry install --no-dev` でもインストールされる |
| `[tool.poetry.dev-dependencies]` | 開発・テスト専用  | pytest, black, mypy           | 通常の `poetry install` 時のみインストールされる     |

* **ローカルやCIでの開発時**:

  ```bash
  poetry install
  ```

* **本番環境にデプロイ時（軽量化）**:

  ```bash
  poetry install --no-dev
  ```

このように、本番環境では不要なライブラリを省いて、軽量・安全な環境を構築できます。

---

### 6. `poetry.lock` とは何か？

`poetry.lock` は、Poetry が自動生成する**ロックファイル**で、すべての依存ライブラリとそのバージョンを**完全に固定**するために使われます。

#### ✅ 目的

* 同じ `pyproject.toml` でも、インストールするタイミングによって異なるバージョンの依存が入ることを防ぐ
* **すべての開発者／環境で同じ依存構成を再現する**（再現性の確保）

#### ✅ 内容例

```toml
[[package]]
name = "requests"
version = "2.31.0"
dependencies = [
    "urllib3 >=1.26,<2.0",
    "certifi >=2022.12.7"
]
```

#### ✅ 開発フローでの使い方

* 初回 `poetry add` や `poetry install` で自動生成される
* チームやCI/CDでは、**`poetry.lock` を Git に含めて共有**
* 本番環境でも同じ依存構成を再現可能

#### ⚠️ 注意

* **手動で編集しない**
* **必ずバージョン管理（Git）に含める**

---

### 7. 類似技術との違い比較

| 技術               | 記述ファイル                                 | 仮想環境管理      | ロック機能 | 備考                |
| ---------------- | -------------------------------------- | ----------- | ----- | ----------------- |
| requirements.txt | `requirements.txt`                     | 手動 (`venv`) | ×     | シンプルだが再現性が限定的     |
| pip-tools        | `requirements.in` + `requirements.txt` | 手動 (`venv`) | ○     | 依存解決とロックが可能       |
| Poetry           | `pyproject.toml` + `poetry.lock`       | 自動          | ○     | 一貫管理、公開機能も備える     |
| PDM              | `pyproject.toml`                       | 自動          | ○     | 軽量・PEP 準拠         |
| Conda            | `environment.yml`                      | 自動          | ○     | 非Pythonパッケージも管理可能 |
| Hatch            | `pyproject.toml`                       | 自動          | ○     | 柔軟な拡張性・プラグイン対応    |
| pipenv           | `Pipfile`                              | 自動          | ○     | シンプルなユースケースに向く    |

---

### 8. まとめ

* `.toml` (TOML形式) は現代的なPythonプロジェクトの標準フォーマット。
* `pyproject.toml` を活用すると、依存・ビルド設定・ツール設定を一元管理できる。
* Poetry を中心に据えれば、**中級者向け**の再現性・可搬性の高い開発フローが実現可能。
* `poetry new` によってプロジェクト雛形を素早く構築し、依存・仮想環境・テスト・ビルド・公開まで統合的に扱える点が強み。
* `dependencies` と `dev-dependencies` の適切な使い分けにより、本番環境を安全かつ軽量に保つことができる。
* `poetry.lock` により、全ての環境で正確に同じ依存構成を再現可能にする。

プロジェクトの規模やチームの開発フローに応じて、`.toml` を中心とした構成を検討しましょう。