Python Academy · レッスン

プロジェクト構成とpyproject.toml

Q: 「プロジェクト構成とpyproject.toml」レッスンは無料ですか？

はい。「プロジェクト構成とpyproject.toml」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Python Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Python Academyコースには全4レッスンが含まれています。

Q: 「プロジェクト構成とpyproject.toml」で何を学びますか？

パッケージを構成します ブラウザで直接実行するハンズオンコードでPython Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Q: Python Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのPython Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。

Q: 「プロジェクト構成とpyproject.toml」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

Q: このPython Academyレッスンでコードを書いて実行できますか？

はい。すべてのPython Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

パッケージを構成します

「プロジェクト構成とpyproject.toml」はCoddyKit上の無料Python Academyレッスンです。これはレッスン1/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはPython Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Python Academyコースには全4レッスンが含まれています。

コードをパッケージ化する理由

スクリプトは自分のマシン上で動作しますが、パッケージはpip installを使って誰でもインストールできます。パッケージ化によって、コードの入ったフォルダーが、配布可能でバージョン管理された再利用可能な単位になります。

最初のステップは、整理されたプロジェクト構成と設定ファイルを用意することです。

srcレイアウト

推奨される構成では、インポート可能なコードをsrc/ディレクトリの下に配置します。

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.mdとtests/

srcレイアウトにすると、インストール済みのコピーではなく、プロジェクトルートから誤ってコードをインポートすることを防げます。

init.pyファイル

__init__.pyは、ディレクトリをインポート可能なパッケージとして示し、パッケージが最初にインポートされたときに実行されます。また、主要な名前をインポートして公開APIを提供する場所でもあります。

空の__init__.pyでも、パッケージを作成するには十分です。

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

pyproject.tomlとは

pyproject.tomlは、最新のPythonパッケージングで使われる、標準化された単一の設定ファイル（PEP 518/621）です。ほとんどのプロジェクトで従来のsetup.pyに置き換わり、ビルドツールによって読み込まれます。

TOML形式を使用し、角括弧で囲んだセクションと、key = value形式の行で構成されます。

build-systemテーブル

[build-system]テーブルは、パッケージのビルド方法をツールに伝えます。一般的な設定は次のとおりです。

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

その他のバックエンドにはHatchlingやFlitがありますが、考え方は同じです。

projectテーブル

[project]テーブルには、name、version、description、authors、readme、requires-python、dependenciesなどのメタデータを記述します。これはユーザーがPyPIで確認する情報です。

パッケージの身分証明書のようなものだと考えてください。

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

命名規則

パッケージ名はPyPI上で一意でなければならず、正規化の規則に従います。大文字と小文字は区別されず、ハイフンとアンダースコアは同じものとして扱われます。アップロード時の衝突を避けるため、名前を決める前に利用可能か確認してください。

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

依存関係の宣言

実行時の依存関係は、dependenciesの下に'requests>=2.28,<3'のようなバージョン制約とともに列挙します。オプションの追加機能は[project.optional-dependencies]の下に記述し、pip install mytool[dev]でインストールできるようにします。

他のパッケージと共存できるよう、安全な範囲で制約はできるだけ緩くしてください。

エントリーポイント

コマンドラインツールを配布するには、[project.scripts]にmytool = 'mypackage.cli:main'のようなエントリを追加します。インストール後にmytoolと入力すると、その関数が実行されます。blackやpytestなどのCLIも、この方法でコマンドを提供しています。

コード以外のファイルを含める

データファイル（テンプレートやJSON）は自動的には含まれません。ビルドバックエンドでパッケージデータを設定し、ファイルがwheelの中に含まれるようにします。これを忘れると、「ローカルでは動くのにインストールすると壊れる」バグがよく発生します。

開発時のeditableインストール

開発中は、pip install -e .を使ってパッケージをeditableモードでインストールします。再インストールしなくても、ソースの変更がすぐに反映されます。これは正しいpyproject.tomlに依存するため、早い段階で設定しておくことをおすすめします。

パッケージを反復的に開発する際、editableインストールは最も素早く結果を確認できる方法です。

確認テスト

プロジェクト構成の知識をテストします。

まとめ

パッケージの構成を作成しました。

srcレイアウトを使用し、__init__.pyでパッケージを示す
pyproject.tomlを標準設定として使用し、[build-system]と[project]を定義する
name、version、requires-python、dependenciesを宣言する
CLI用に[project.scripts]のエントリーポイントを追加し、パッケージデータを設定する

よくある質問