pyproject.toml ファイル

pyproject.toml ファイル #

pyproject.toml ファイルの tool.poetry セクションは、複数のセクションで構成されています。

package-mode #

Poetry がパッケージモード（デフォルト）で動作するかどうか。オプション

詳細については、基本的な使い方 を参照してください。

package-mode = false

name #

パッケージの名前。パッケージモードでは必須

これは、PEP 508 で定義されている有効な名前である必要があります。

name = "my-package"

version #

パッケージのバージョン。パッケージモードでは必須

これは、有効な PEP 440 文字列である必要があります。

version = "0.1.0"

description #

パッケージの簡単な説明。パッケージモードでは必須

description = "A short description of the package."

license #

パッケージのライセンス。

最も一般的なライセンスの推奨表記は（アルファベット順）

• Apache-2.0
• BSD-2-Clause
• BSD-3-Clause
• BSD-4-Clause
• GPL-2.0-only
• GPL-2.0-or-later
• GPL-3.0-only
• GPL-3.0-or-later
• LGPL-2.1-only
• LGPL-2.1-or-later
• LGPL-3.0-only
• LGPL-3.0-or-later
• MIT

オプションですが、これを指定することを強くお勧めします。その他の識別子は、SPDXオープンソースライセンスレジストリ に記載されています。

license = "MIT"

authors #

パッケージの作成者。パッケージモードでは必須

これは作成者のリストであり、少なくとも1人の作成者を含める必要があります。作成者は name <email> の形式である必要があります。

authors = [
    "Sébastien Eustace <sebastien@eustace.io>",
]

maintainers #

パッケージのメンテナー。オプション

これはメンテナーのリストであり、作成者とは区別する必要があります。メンテナーはメールを含めることができ、name <email> の形式である必要があります。

maintainers = [
    "John Smith <johnsmith@example.org>",
    "Jane Smith <janesmith@example.org>",
]

readme #

パッケージの README ファイルに対応するパスまたはパスのリスト。オプション

ファイルは任意の形式にできますが、PyPI に公開する場合は、PyPIフレンドリーなREADMEの推奨事項 を考慮してください。README のパスは、pyproject.toml を基準とする相対パスです。

README ファイルの内容は、ディストリビューションのメタデータの Descriptionフィールド （setuptools の long_description と同様）を設定するために使用されます。複数のファイルが指定されている場合、それらは改行で連結されます。

[tool.poetry]
# ...
readme = "README.md"

[tool.poetry]
# ...
readme = ["docs/README1.md", "docs/README2.md"]

homepage #

プロジェクトの Web サイトへの URL。オプション

homepage = "https://poetry.dokyumento.jp/"

repository #

プロジェクトのリポジトリへの URL。オプション

repository = "https://github.com/python-poetry/poetry"

documentation #

プロジェクトのドキュメントへの URL。オプション

documentation = "https://poetry.dokyumento.jp/docs/"

keywords #

パッケージに関連するキーワードのリスト。オプション

keywords = ["packaging", "poetry"]

classifiers #

プロジェクトを説明する PyPI trove classifiers のリスト。オプション

[tool.poetry]
# ...
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules"
]

packages #

最終的なディストリビューションに含めるパッケージとモジュールのリスト。

プロジェクトの構造が poetry でサポートされている標準構造と異なる場合は、最終的なディストリビューションに含めるパッケージを指定できます。

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "extra_package/**/*.py" },
]

パッケージが "lib" ディレクトリ内に保存されている場合は、指定する必要があります

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib" },
]

to パラメーターは、インストール時にパッケージが配置される相対的な宛先パスを指定するために設計されています。これにより、プロジェクト構造内のパッケージの編成をより詳細に制御できます。

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib", to = "target_package" },
]

パッケージを特定のビルド形式に制限する場合は、format を使用して指定できます

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "my_other_package", format = "sdist" },
]

今後は、sdist ビルドアーカイブにのみ my_other_package パッケージが含まれます。

packages = [
    { include = "my_package" },
    { include = "extra_package" },
]

include と exclude #

最終パッケージに含めるパターンのリスト。

パッケージングの目的で、一連の glob を無視または含める必要があることを Poetry に明示的に指定できます。 exclude フィールドに指定された glob は、パッケージのビルド時に含まれないファイルのセットを識別します。

VCS がパッケージに使用されている場合、exclude フィールドには VCS の無視設定（たとえば、git の場合は .gitignore）が設定されます。

[tool.poetry]
# ...
include = ["CHANGELOG.md"]

ここで示すように、これらのパターンを含める必要がある形式を指定することもできます

[tool.poetry]
# ...
include = [
    { path = "tests", format = "sdist" },
    { path = "for_wheel.txt", format = ["sdist", "wheel"] }
]

形式が指定されていない場合、include はデフォルトで sdist のみになります。

対照的に、exclude はデフォルトで sdist と wheel の両方になります。

exclude = ["my_package/excluded.py"]

dependencies と依存関係グループ #

Poetry は、デフォルトで PyPI での依存関係の検索を設定しています。この場合、名前とバージョン文字列のみが必要です。

[tool.poetry.dependencies]
requests = "^2.13.0"

プライベートリポジトリ を使用する場合は、次のように pyproject.toml ファイルに追加できます

[[tool.poetry.source]]
name = "private"
url = "http://example.com/simple"

複数のリポジトリが構成されている場合は、特定のパッケージを探す場所を poetry に明示的に指示できます

[tool.poetry.dependencies]
requests = { version = "^2.13.0", source = "private" }

[tool.poetry.dependencies]
python = "^3.7"

依存関係をよりきめ細かく管理するために、グループに整理できます。

[tool.poetry.group.test.dependencies]
pytest = "*"

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

依存関係グループの管理方法の詳細については依存関係グループを、その他のキーとバージョン範囲の指定に関する詳細については依存関係の指定を参照してください。

scripts #

このセクションでは、パッケージのインストール時にインストールされるスクリプトまたは実行可能ファイルについて説明します。

[tool.poetry.scripts]
my_package_cli = 'my_package.console:run'

ここでは、my_package パッケージの console モジュールにある run 関数を実行する my_package_cli スクリプトがインストールされます。

extras #

Poetry は、以下を表現するために extras をサポートしています。

• パッケージを強化するが必須ではないオプションの依存関係、および
• オプションの依存関係のクラスター。

[tool.poetry]
name = "awesome"

[tool.poetry.dependencies]
# These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0"

# A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.9", optional = true }
mysqlclient = { version = "^1.3", optional = true }

[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]

Poetry でパッケージをインストールするときは、-E|--extras オプションを使用して extras を指定できます。

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

指定しない extras はすべて削除されます。この動作は、install --with で指定されていないなど、インストール用に選択されていないオプションの依存関係グループとは異なることに注意してください。

--all-extras オプションを使用すると、すべての extras をインストールできます。

poetry install --all-extras

[tool.poetry.dependencies]
pandas = {version="^2.2.1", extras=["computation", "performance"]}

[tool.poetry.group.dev.dependencies]
fastapi = {version="^0.92.0", extras=["all"]}

Poetry でビルドされたパッケージをインストールまたは指定する場合、このセクションで定義された extras は、PEP 508で説明されているようにアクティブ化できます。

たとえば、pip を使用してパッケージをインストールする場合、databases extra に必要な依存関係は以下のようにインストールできます。

pip install awesome[databases]

plugins #

Poetry は任意のプラグインをサポートしており、これらはエコシステム標準のエントリポイントとして公開され、importlib.metadata を使用して検出できます。これは、setuptools のエントリポイント機能と同様であり、互換性があります。プラグインを登録するための構文は次のとおりです。

[tool.poetry.plugins] # Optional super table

[tool.poetry.plugins."A"]
B = "C:D"

以下のとおりです。

• A - プラグインのタイプ。たとえば、poetry.plugin または flake8.extension など
• B - プラグインの名前
• C - Python モジュールのインポートパス
• D - プラグインのエントリポイント (関数またはクラス)

例 (poetry-plugin-export から)

[tool.poetry.plugins."poetry.application.plugin"]
export = "poetry_plugin_export.plugins:ExportApplicationPlugin"

urls #

基本的な URL (homepage、repository、documentation) に加えて、urls セクションで任意のカスタム URL を指定できます。

[tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

パッケージを PyPI に公開すると、それらは Project Links セクションに表示されます。

Poetry と PEP-517 #

PEP-517 は、Python プロジェクトをビルドするための代替ビルドシステムを定義する標準的な方法を導入しています。

Poetry は、軽量なコアライブラリを提供することで PEP-517 に準拠しています。したがって、Python プロジェクトの管理に Poetry を使用する場合は、次のように pyproject.toml ファイルの build-system セクションでそれを参照する必要があります。

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