> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# pyproject.toml ファイルの作成方法

> Python の pyproject.toml ファイルの完全ガイド: 作成方法、依存関係の記述、バージョンの固定、プロジェクトを本番環境向けに準備する方法を学びます。

## Python 向けの pyproject.toml ファイル

`pyproject.toml` ファイルは、プロジェクトのビルドシステム要件と依存関係をすべて 1 つのファイルにまとめて指定する現代的な方法です。このガイドでは、開発環境と本番環境の一貫性を保つために `pyproject.toml` を作成、設定、利用する方法を説明します。

## pyproject.toml ファイルとは？

`pyproject.toml` は、Python プロジェクトの依存関係、ビルドシステム、その他のメタデータを記述します。これにより次のことが可能になります。

* あなたとチームが同一の環境を維持できる
* 新しい協力者が環境を正確に再現できる
* 開発用と本番用の依存関係を別々に設定できる

***

<Steps>
  <Step title="pyproject.toml ファイルを作成する">
    まず、プロジェクトのルートに `pyproject.toml` という名前のファイルを作成します。
  </Step>

  <Step title="プロジェクトの詳細を定義する">
    `pyproject.toml` ファイルでは、まずプロジェクトのメタデータを定義することから始めます。ここではプロジェクト名、バージョン、説明、その他の関連情報を定義します。\
    プロジェクト名は ASCII 文字、数字、アンダースコア「\_」、ハイフン「-」、ピリオド「.」で構成する必要があります。アンダースコア、ハイフン、ピリオドで始まったり終わったりしてはいけません。例:

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="プロジェクトの依存関係を記述する">
    次に、プロジェクトに必要な依存関係を記述します。開発用と本番用の両方の依存関係を指定できます。本番用の依存関係は `dependencies` セクションに記述し、開発用の依存関係は `optional-dependencies` の下に特定のグループ名（例: `dev`）を付けて記述できます。\
    依存関係のバージョンは、`==`、`>=`、`<` などの比較演算子を使って指定できます。以下の例ではバージョンを指定していません。これは最新版がインストールされることを意味します。
    本番環境では、再現性を確保し、非互換な更新による破損を防ぐために、正確なバージョンを指定することを推奨します。

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord-py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]
    ```
  </Step>

  <Step title="ビルドシステムを設定する">
    最後に、ビルドシステムの要件を指定する必要があります。これは pip のようなツールがプロジェクトのビルドとインストール方法を知るために必要です。ここではビルドバックエンドとして `setuptools` を使用します。これは Python プロジェクトで一般的な選択肢ですが、`poetry` などの他のものを選ぶこともできます。

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]

    [build-system]
    requires = ["setuptools"]
    build-backend = "setuptools.build_meta"
    ```
  </Step>
</Steps>

***

## pip で依存関係をインストールする

`pyproject.toml` ファイルに記述された依存関係をインストールするには、pip または `pyproject.toml` に対応した他のツールを使用できます。これにより、依存関係をインストールした状態でプロジェクトの作業を行えます。

```bash theme={null}
pip install .
```

このコマンドは `pyproject.toml` ファイルを読み込み、`dependencies` に記述された依存関係をインストールし、開発用にプロジェクトをセットアップします。開発用の依存関係も併せてインストールしたい場合は、次を使用できます。

```bash theme={null}
pip install .[dev]
```

これにより本番用と開発用の両方の依存関係がインストールされ、必要なツールをすべて揃えた状態でプロジェクトの作業を行えます。

## ベストプラクティスとヒント:

* **常に最新に保つ**: 新しい依存関係を追加するたびに `pyproject.toml` を定期的に見直し、更新する
* **正確なバージョンを使う**: 本番環境での予期しない問題を避けるため、`>`、`>=`、バージョン指定なしではなく、常に `==` を使う
* **バージョン管理**: 依存関係の変更やバージョンの更新を追跡するため、`pyproject.toml` を git にコミットする
* **隔離された環境**: グローバルな競合を避けるため、プロジェクトごとに 1 つの仮想環境を維持する
* **ローカルでテストする**: デプロイ前に、新しい環境で `pip install .` を使ってファイルをテストする

***

## 次のステップ

`pyproject.toml` ファイルの設定が完了したら:

1. Git リポジトリにコミットする。
2. プロジェクトを **Square Cloud** にホスティングする。
3. GitHub 経由での自動 deploy を設定する。
4. プロフェッショナルな Python アプリケーションホスティングへようこそ！

適切に構成された `pyproject.toml` ファイルは、あらゆる成功する Python アプリケーションの基盤であり、Square Cloud 上でアプリケーションが完璧に動作することを保証します。