エントリポイントの仕様

エントリポイント は、インストールされた配布物が他のプログラムから発見され使用されるように提供するコンポーネントを広報するためのメカニズムです。例えば:

  • 配布物では、それぞれが関数を参照するような console_scripts エントリポイントを指定することができます。 pip (または console_scripts を認識する他のインストーラ) が配布物をインストールする際に、各エントリポイントのコマンドラインラッパを生成します。

  • アプリケーションは、プラグインをロードするためにエントリポイントを用いることができます; 例えば、 Pygments (シンタックスハイライトを行うツール) は追加的な字句解析器を使うことが可能であり、また、別にインストールされたパッケージから提供されるスタイルを使うことができます。この件の詳細については、 プラグイン作成と発見 を見てください。

エントリポイントのファイルフォーマットは、元々は、 setuptools でビルドされたパッケージが、動作時 (ランタイム) に importlib.metadata で読み取られるであろうと思われるインテグレーションポイントメタデータを提供できるようにと開発されました。現在では、 setuptools 以外のビルドツールが importlib.metadata と互換性のあるエントリポイントのメタデータを公開し、 importlib.metadata 以外のランタイムライブラリが移植可能な形で公開されているエントリポイントのメタデータを (潜在的には、たとえ異なるキャッシングと衝突回避の戦略を採用していたとしても) 読み取ることができるようにと PyPA 相互互換性仕様において定義されています。

データモデル

概念的に、エントリポイントは３個の属性を持たなければならないと定義されています:

  • エントリポイントが属する group は、それがどのような種類のオブジェクトを提供するのかを示します。例えば、 console_scripts グループはコマンドとして使える関数を参照するエントリポイント用であり、一方、 pygments.styles は pygments スタイルを定義するクラスを提供するグループです。利用する側 (コンシューマ) は、通常、期待するインタフェースを定義しています。衝突を避けるために、新しいグループを定義するのであればコンシューマは自身の PyPI での名前の後に . を後置したもので始まるグループ名を使うべきです。グループ名は、ひとつかそれ以上の文字・数字・アンダースコアをドット文字で区切ったもの (正規表現で ^\w+(\.\w)*$) でなければなりません。

  • グループ内では、エントリポイントを name で識別します。このことの正確な意味は利用する側次第です。コンソールスクリプトでは、エントリポイントの名前はそのコマンドを起動するのに使われる名前です。配布物の内部では、エントリポイントの名前は一意に決まるべきです。別の配布物が同じ名前を提供する場合には、利用する側でそのような衝突をどのように扱うのかを決めます。名前は = を除いてどんな文字を含んでいても構いませんが、空白文字で始まったり終わったりすることはできず、 [ で始まることもできません。エントリポイントをこれから作るのであれば、文字・数字・アンダースコア・ドットとダッシュ (正規表現で言うと [\w.-]+) だけを用いることが推奨されています。

  • object reference は Python のオブジェクトを指し示しています。 importable.module 、または、 importable.module:object.attr の形式のいずれかです。ドットやコロンで区切られた各部分は、 Python の正当な識別子です。次のようにルックアップされることを意図したものです:

    import importlib
modname, qualname_separator, qualname = object_ref.partition(':')
obj = importlib.import_module(modname)
if qualname_separator:
    for attr in qualname.split('.'):
        obj = getattr(obj, attr)

注釈

とりわけそれがプログラムを起動する関数を指し示している場合には、いくつかのツールはこの種のオブジェクトへの参照、もっと良い用語で言えば 'エントリポイント' を自分自身で呼び出します。

さらに追加のプロパティがあります: extras は、エントリポイントを提供する配布物の追加的な機能をを識別する１組みの文字列です。もし指定されていれば、そのような 'extras' の依存関係をエントリポイントが要求しています。メタデータのフィールド Provides-Extra (複数回の使用可) を見てください。

エントリポイント用に extras を使うことはもはや推奨されていません。利用する側は、既存の配布物からそれを取り出して解析することをサポートするべきですが、しかし、無視しても構いません。新しい公開用ツールは、 extras を指定することをサポートする必要はありません。 extras を扱う機能は setuptools が 'egg' パッケージを管理するモデルに紐づいたものですが、しかし、 pip や virtualenv のようなもっと新しいツールでは異なるモデルを採用しています。

ファイルフォーマット

エントリポイントは、配布物の *.dist-info ディレクトリの中の entry_points.txt と呼ばれるファイル内で定義されます。これは、インストール済みの配布物に関しては インストール済みパッケージを記録する 、 wheels に関しては バイナリ配布物のフォーマット に記述されます。このファイルでは UTF-8 エンコーディングを使います。

ファイルの内容は、 Python の configparser モジュールで読み取ることができる INI フォーマットです。しかしながら、 configparser はデフォルトでは変数名を大文字小文字の区別をせずに扱う一方で、エントリポイントでは区別をします。大文字小文字の区別をする configparser はこのようにして作成できます:

import configparser

class CaseSensitiveConfigParser(configparser.ConfigParser):
    optionxform = staticmethod(str)

エントリポイントのファイルでは、名前と値を区切るのに常に = を使わなければなりません (他方で configparser は : で区切ることも許容します) 。

設定ファイルの各セクションはエントリポイントの各グループを表していて、名前は名前であり、値はオブジェクトへの参照と任意の extras の両方をエンコードします。 extras が使われる場合には、角括弧の中にコンマ区切りで列挙します。

Within a value, readers must accept and ignore spaces (including multiple consecutive spaces) before or after the colon, between the object reference and the left square bracket, between the extra names and the square brackets and colons delimiting them, and after the right square bracket. The syntax for extras is formally specified in 依存関係指定子. For tools writing the file, it is recommended only to insert a space between the object reference and the left square bracket.

例:

[console_scripts]
foo = foomod:main
# One which depends on extras:
foobar = foomod:main_bar [bar,baz]

# pytest plugins refer to a module, so there is no ':obj'
[pytest11]
nbval = nbval.plugin

スクリプト向けの使用法

console_scripts と gui_scripts: エントリポイントのふたつのグループは、パッケージング全体の中で特別な重要性を持っています。このふたつのグループでは、エントリポイントの名前は、パッケージがインストールされた後にシステムのシェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、このコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数は、プロセスの終了コードとして使われる整数を返しても構わず、 None を返すと 0 を返したのと同じに扱われます。

例えば、 micmd = memo:main というエントリポイントは、 micmd というコマンドを生成し、このようにスクリプトを起動することになるでしょう:

import sys
from mymod import main
sys.exit(main())

console_scripts と gui_scripts の違いは、 Windows システムにだけ影響を与えます。 console_scripts はコンソールで実行できるようにラップされるので、コンソールに接続されて 入出力に sys.stdin ・ sys.stdout ・ sys.stderr を使えます。 gui_scripts は GUI で実行可能となるようにラップされるので、コンソールなしで起動することができ、しかし、アプリケーション側でリダイレクトしておかない限りは標準入出力を使うことができません。他のプラットフォームではこのような区別をしません。

インストールツールは、 console_scripts と gui_scripts の両方について、インストールスキームのスクリプト用ディレクトリにラッパをセットアップするものと期待されています。(しかし、インストールツールは) このディレクトリをコマンドラインツールを探索するために定義される PATH 環境変数に入れることについては責任を持ちません。

名前からファイルが作られることと、いくつかのファイルシステムでは大文字小文字を区別しないことから、パッケージはこれらのグループについては大文字か小文字かの違いしかないような名前を使うことを避けるべきです。名前が大文字小文字しか違わない場合のインストールツールの挙動は未定義です。

歴史

  • 2017年10月: setuptools の既存のエントリポイント機能を公式のものとするためのこの仕様が書かれました (discussion) 。

  • January 2026: Replaced outdated direct references to PEP 508 and PEP 685 with a reference to 依存関係指定子.