The `pyproject.toml` file

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

package-mode

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

詳細については、basic usageを参照してください。

package-mode = false

name

パッケージの名前。パッケージ・モードで必要

これは、PEP 508で定義されている有効な名前でなければなりません。

name = "my-package"

version

パッケージのバージョン。パッケージ・モードで必要

これは有効なPEP 440文字列でなければなりません。

version = "0.1.0"

Note

プロジェクトにセマンティックバージョン管理を使用したい場合は、hereを参照してください。

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 Open Source License Registryに記載されています。

license = "MIT"

Note

プロジェクトがプロプライエタリで、特定のライセンスを使用していない場合は、この値をProprietaryとして設定できます。

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からの相対パスです。

Note

パスで大文字と小文字が区別されるかどうかはプラットフォームのデフォルトに従いますが、大文字と小文字を区別しないことをお勧めします。

具体的には、macOSとWindowsではrEaDmE.mdにrEaDmE="rEaDmE.mD"を設定できますが、Linuxユーザーはリポジトリのクローンを作成した後にpoetry installを実行できません。これは、macOSとWindowsが大文字と小文字を区別せず、大文字と小文字を保持するためです。

READMEファイルの内容は、ディストリビューションのメタデータのDescription fieldフィールドに入力するために使用されます(setuptoolsのlong_descriptionと同様です)。複数のファイルを指定すると、改行で連結されます。

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

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

homepage

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

homepage = "https://python-poetry.org/"

repository

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

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

documentation

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

documentation = "https://python-poetry.org/docs/"

keywords

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

keywords = ["packaging", "poetry"]

classifiers

プロジェクトを記述するPyPItrove classifiersのリスト。オプション

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

Note

Pythonクラシファイアは自動的に追加され、pythonの要件によって決定されることに注意してください。

licenseプロパティは、ライセンス分類子も自動的に設定します。

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パッケージが含まれます。

Note

packagesを使用すると、パッケージの自動検出機能が無効になります。つまり、"default"パッケージを明示的に指定する必要があります。

たとえば、my_packageという名前のパッケージがあり、extra_packageという名前の別のパッケージも含めたい場合は、my_packageを明示的に指定する必要があります。

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

Note

PoetryはPythonのサブパッケージを検出するのに十分賢い方法です。

したがって、ルートパッケージが存在するディレクトリを指定するだけで済みます。

include and exclude

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

Poetryに対して、パッケージ化のためにglobのセットを無視するか含めるかを明示的に指定できます。 excludeフィールドに指定されたglobは、パッケージの構築時に含まれない一連のファイルを識別します。

VCSがパッケージに使用されている場合、excludeフィールドにはVCSのignore設定(gitの場合は.gitignoreなど)がシードされます。

Note

includeでエントリを明示的に宣言すると、VCSのignore設定が無効になります。

[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 and dependency groups

Poetryは、デフォルトでPyPIへの依存関係を検索するように設定されています。この場合は、名前とバージョン文字列だけが必要です。

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

private repositoryを使用する場合は、次のようにpyproject.tomlファイルに追加します。

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

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

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

Note

パッケージと互換性のあるPythonバージョンを宣言することは必須であることに注意してください。

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

依存関係をgroupsに整理して、より詳細な方法で管理できます。

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

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

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

`scripts`

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

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

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

Note

スクリプトが追加または更新されたら、poetry installを実行して、プロジェクトのvirtualenvで利用できるようにします。

`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オプションを使用してエクストラを指定できます。

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

指定しないエクストラは削除されます。この動作は、インストール対象として選択されていないoptional dependency groups(例えばinstall --withで指定されていないもの)とは異なることに注意してください。

すべてのエクストラは--all-extrasオプションでインストールできます。

poetry install --all-extras

Note

install--extrasと上記のバリエーション(--all-extras、--extras fooなど)は、現在のプロジェクトで定義された依存関係に対してのみ機能することに注意してください。依存関係によって定義された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で構築されたパッケージをインストールまたは指定する場合、PEP 508で説明されているように、このセクションで定義されている追加機能を有効にすることができます。

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

pip install awesome[databases]

Note

各extraに指定された依存関係は、すでにプロジェクト依存関係として定義されている必要があります。

dependency groupsにリストされている依存関係は、追加として指定できません。

`plugins`

Poetryは、エコシステム標準のentry pointsとして公開され、importlib.metadataを使用して検出できる任意のプラグインをサポートしています。これはsetuptoolsのエントリポイント機能と似ています(互換性もあります)。

プラグインを登録する構文は次のとおりです。

[tool.poetry.plugins] # Optional super table

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

Which are:

A - プラグインの型、例えばpoetry.pluginやflake8.extension
B - プラグインの名前
C - pythonモジュールのインポートパス
D - プラグイン(関数またはクラス)のエントリポイント

例(frompoetry-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"

If you publish your package on PyPI, they will appear in the Project Links section. PyPIでパッケージを公開すると、"プロジェクトリンク"セクションに表示されます。

Poetry and PEP-517

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

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

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

Note

newまたはinit コマンドを使用すると、自動的に追加されます。

Note

pyproject.tomlがpoetryをビルドバックエンドとして直接参照している場合、代わりにpoetry-coreをアップデートするべきです。

The pyproject.toml file

package-mode

name

version

description

license

authors

maintainers

readme

homepage

repository

documentation

keywords

classifiers

packages

include and exclude

dependencies and dependency groups

scripts

extras

plugins

urls

Poetry and PEP-517

The `pyproject.toml` file

`scripts`

`extras`

`plugins`

`urls`