Python Enhancement Proposal: 1

PEP:

1

タイトル:

PEPの目的とガイドライン

バージョン:

80667

最終更新日:

2010-04-30 21:21:52 +0200 (Fri, 30 Apr 2010)

著者:

Barry Warsaw, Jeremy Hylton, David Goodger

ステータス:

アクティブ

タイプ:

プロセス

Content-Type:

text/x-rst

作成日時:

13-Jun-2000

投稿履歴:

21-Mar-2001, 29-Jul-2002, 03-May-2003

注釈

  • 西尾さんより訳修正提案→反映(2010/7/27)

PEPとは何か？

PEPはPython拡張提案(Python Enhancement Proposal)を表しています。PEPはPythonのコミュニティに対して情報を提供したり、Pythonの新機能やプロセス、環境などを説明するための設計書です。PEPは、技術的な仕様と、その機能が必要な論理的な理由を提供しなければなりません。

我々は、PEPを、新機能を提案したり、課題に関するコミュニティの意見を集約したり、Pythonに取り込まれることになる、設計上の決定をドキュメント化するための、主要なメカニズムであると位置づけています。PEPの作者は、コミュニティの中でコンセンサスを取ったり、反対意見の記録を取る責任を持ちます。

PEPはテキストファイルの形式でバージョン管理されたリポジトリの中に保管されます。そのリポジトリの変更履歴は、機能提案の経緯の記録となります。 [1]

PEPの種類

PEPの種類は、次のような3種類あります。

  1. Standards Track(標準化過程) PEP はPythonの新しい機能や実装について説明するドキュメントです。

  2. Informational(情報) PEP はPythonの設計上の課題や、Pythonコミュニティに知らせる一般的なガイドラインや情報などを説明するドキュメントです。新機能の提案は行いません。Informational PEPの場合には必ずしもPythonコミュニティの間でのコンセンサスは必要とはなりませんし、推奨もしていません。ユーザやPythonの実装者は、自由にこれらのPEPを無視したり、従ったりすることができます。

  3. Process(プロセス) PEP はPythonを取り巻くプロセスについて説明をしたり、プロセスや、プロセス中のイベントについて提案したりするドキュメントです。Process PEPはStandards Track PEPに似ていますが、Pythonの言語そのもの以外の領域が対象となります。実装の提案をする可能性はありますが、Pythonのコードベースに対して提案することはありません。このPEPはコミュニティ内のコンセンサスを必要とすることが多いでしょう。Informational PEPとは異なり、推奨以上の拘束力を持ち、ユーザーは通常これを無視することはできません。例えば、手続き、ガイドライン、意志決定法、Python開発で利用されるツールや環境などの変更などが含まれます。PEPを規定するメタなPEPもProcess PEPであると考えられています。

PEPワークフロー

PEP編集者は、PEP番号を割り当てたり、PEPのステータスを変更したりします。PEPに関連するすべてのEメールは <peps@python.org> (クロスポストはしないでください) に送って下さい。また、後ろの方で紹介する、 PEP編集者の責務とワークフローも確認してください。

PEPのプロセスは、Pythonに対する新しいアイディアを発想するところから始まります。重要な提案や、新しいアイディアは、1つのPEPに対して1つだけ含むようにする、というのを強く推奨します。もし、改善提案やパッチがそれほど大きくないのであれば、PEPを作成する必要がないケースが多いでしょう。この場合には、Pythonの開発ワークフローの方で対応することができるので、Pythonの issue tracker に対してパッチを送信します。注目されるPEPほど、受け入れられる確率は高いという傾向があります。PEP編集者は、PEPの焦点がぼやけていたり、範囲が広すぎる場合には提案を否認できる権利を持っています。疑わしい場合には、焦点がしっかりした項目にPEPを分割して下さい。

PEPごとにチャンピオンを定める必要があります。チャンピオンは、これから紹介するスタイルやフォーマットに従ってPEPを書き、適切なフォーラムで行われる議論に目を通し、出したアイディアについて、コミュニティの中でコンセンサスを取る努力を行います。PEPチャンピオン(著者とも言う)はまず、アイディアをPEPにすることができるかどうかを確かめるべきです。comp.lang.pythonニューズグループや、python-list@python.orgメーリングリスト、あるいは、python-ideasメーリングリストに投稿してみるというのがもっとも良いでしょう。

PEPを書くよりも前に、アイディアを公開して意見を診断してもらうと、トータルでPEPの著者がかけなければならない時間は短くなるでしょう。Pythonを変更する多くのアイディアが提案されてきましたが、様々な理由から否認されたものも数多くあります。アイディアがオリジナルのものである場合に、初めにPythonコミュニティに投げかけると、リジェクトされる場合に、そのための議論に費やされるのを防ぐ手助けとなります(インターネットで検索するというのは代替にはなりません)。こうすることで、著者だけではなく、コミュニティ全体にアイディアが適合するということを保証しやすくなります。というのも、著者にとって良いアイディアと思えるものが、Pythonを使用している多くの人にとってもそうとは限らないからです。

チャンピオンがPythonコミュニティに、そのアイディアには採用のチャンスがあるかどうかを訪ねる際には、一度、PEPの草稿をpython-ideasメーリングリストに投げるべきです。投げて読んでもらう目的を満たすために、フォーマットが整えたり、品質を上げ、提案に関する心配なこともきちんと書いたりと、著者がPEPを具体的な形にするきっかけになるでしょう。

python-ideasの議論の後は、提案を python-dev list と、PEP editors <peps@python.org> に送ります。このドラフトは、これから説明するPEPのスタイルで書かれている必要があります。適切なフォーマットのルールにしたがっていなければ、内容を見られることなく、突き返されることになります。

PEP編集者が承認すると、PEP番号を割り当てます。Standards Track/Informational/Processのどれかを設定し、ステータスを"Draft(草案)"に設定し、最初のPEPの草案をチェックインします。PEPエディタは理由なくPEPを否認はしません。PEPを否認する理由としては、他のPEPと重複している、技術的にうまくいかない、動機が適切ではない、後方互換性に注意が向けられていない、Pythonの哲学から外れる、といったものがあります。承認フェーズの間、BDFL(慈悲深き終身独裁者, Python作者のGuido van Rossum)に相談することができます。BDFLは、PEPのドラフトの最終決裁者でもあります。

アップデートが必要になると、もしSVNのコミット件を持っていればPEP作者はチェックインすることができます。もしなければ、新しいPEPをPEP編集者にメールで送ってコミットしてもらいます。

Standards Track PEPは大きく2つのパートを含みます。設計ドキュメントと、リファレンス実装です。リファレンス実装がPEPの理解の助けとなる場合を除き、リファレンス実装を始める前に、PEPのレビューと受理が行われる必要があります。Standards Track PEPはステータスがFinal(確定)となる前までに、コード、パッチ、URLなどといった形で実装を含めなければなりません。

PEP作者は、レビューのために提出する前に、PEPに対するコミュニティのフィードバックを収集する責任があります。しかし、可能であればパブリックなメーリングリストでの長い議論は避けるべきです。議論を効率的に保つための戦略として、その話題に関するSIGメーリングリストを立てたり、初期のデザインフェーズでプライベートにコメントを募集したり、Wikiのページを用意するなどがあります。PEP作者は自分で適切に判断する必要があります。

いったん作者がPEPを完成させたら、レビューの準備ができたということをPEP編集者に知らせます。BDFLと、彼が選んだコンサルタントがPEPをレビューを行い、PEPの受理/否認を行ったり、変更を加えてもらうために作者に差し戻したりします。受理されるのが予定されるPEP(たとえば、そのままでも問題がまったくない、もしくはその実装がすでにチェックイン済み、あるいはその両方)の場合は、BDFLもPEPレビューを開始するかもしれません。最初にPEPの作者に知らされて、改訂するチャンスが与えられます。

PEPが受理されるためには、最低限の評価基準を満たしている必要があります。提案されている機能拡張に関する説明が明白で、完成されていなければなりません。その拡張は、最終的な改善点にまで言及していなければなりません。もし可能であれば、提案された実装はインタプリタの実装を過度の複雑化させないようにしなければなりません。最後に、BDFLに受け入れられるにはその機能拡張提案は"Pythonic"でなければなりません。(しかし"Pythonic"という用語には厳格な意味がありません。BDFLが受理するものであれば"Pythonic"であるという定義になっています。この論理の循環は意図的なものです) 標準ライブラリモジュールの受理の判定基準に関しては、PEP 2 [2] を参照してください。

PEPが受理されたら、参照実装を完成させなければなりません。参照実装が完成し、BDFLがそれを受理すると、ステータスが"Final"になります。

PEPのステータスに"延期(Deferred)"が設定されることがあります。PEP作者と編集者は、PEPの作成に関して進捗がない場合には、PEPのステータスをこの状態に設定することができます。一度延期されると、PEP編集者が状態をさらに"ドラフト"に再設定することもあります。

PEPは"否認(Rejected)"されることもあります。おそらく、なんといってもその提案が名案ではなかったということです。しかし、この事実の記録を残しておくということは大切です。

PEPでは、オリジナルのPEPを廃止して、異なるPEPに置き換えることもできます。このフローは主にInformational PEPを意図して設定されています。APIのバージョン2を作成して、バージョン1のPEPを置き換える、ということができます。

PEPのステータスの移行可能な経路は次のようになっています。

../_images/pep-0001-1.png

いくつかのInformational PEPとProcess PEPでは、PEP 1(このPEP)のように完成させることを意図していない場合には、"Active"という状態になることもあります。

成功しているPEPには何が含まれているのか？

それぞれのPEPには次のような項目が含まれます。

  1. 前文 -- PEPのメタデータを含む、RFC 822スタイルのヘッダです。PEP番号、短いタイトル(最大44文字)、著者の名前(連絡先は任意)などを含みます。

  1. 要約 -- 最大で200語の短い説明です。技術的な課題についても言及します。

  1. 著作権/パブリックドメイン -- それぞれのPEPは、このPEPのようにパブリックドメインに属していることを明示するか、 Open Publication License としてライセンスする必要があります。

  1. 仕様 -- 新しい言語の機能の文法、意味などについて説明した、技術的な仕様書です。仕様は、議論ができるように詳しく書きます。また、あらゆるPythonのプラットフォーム(CPython, Jython, Python.NET)のそれぞれで実装可能でなければなりません。

  1. 動機 -- Pythonの言語を変更しようとしているPEPの場合には、動機が大切です。この動機の説明の中では、そのPEPが解決する問題を取り扱う時に既存のPythonの言語仕様ではどのような不足があるのか、というのを明確にしなければなりません。十分な動機がないPEPは無条件に否認されるでしょう。

  1. 論理的根拠 -- 論理的根拠は仕様を補足する説明です。デザインの動機付けとなったもの、なぜそのデザインに決定したのか、などについて説明します。また、デザインの別案や、同様の機能が他の言語でどのようにサポートされているのかという関連の説明についても触れなければなりません。

    論理的根拠では、コミュニティ内でのコンセンサスの証拠、議論の中で出された重要な反論、議論の中で話題になったことなどについても触れなければなりません。

  1. 後方互換性 -- 後方互換性を保てない変更を加えるすべてのPEPには、どのような非互換性があるのか、互換性を保つのがなぜ難しいのかというのを説明するセクションが必要です。PEPでは、作者の提案ではどのようにこの非互換性を取り扱うのか、という説明をしなければなりません。後方互換性について十分な説明のないPEPは無条件に否認されるでしょう。

  1. 参考実装 -- 参考実装は、PEPのステータスが"Final"になる前に完成していなければなりませんが、PEPが受理されるまでは完成させる必要はありません。仕様と論理的根拠についてのコンセンサスをまず取る方が良いでしょう。

    最終的な実装にはテストコードと、Pythonの言語リファレンスや標準ライブラリリファレンスとして適切に取り込めるようなドキュメントも含まなければなりません。

PEPのフォーマットとテンプレート

著者が利用できるPEPのフォーマットには2種類あります。プレーンテキストと reStructuredText です。どちらもUTF-8でエンコードされたテキストファイルです。

プレーンテキストのPEPは、堅いスタイルを堅く守った、構造化された最小のマークアップで書かれます。PEP 9には、この解説と、プレーンテキストのPEPを書き始めるのに使用可能なテンプレート [3] が含まれます。

reStructuredText のPEPは読みやすさを維持しつつ、より見た目が良く、機能的なHTMLが生成可能な、豊富なマークアップが利用できます。PEP 12には、解説とreStructuredTextのPEPのためのテンプレート [4] が含まれます。

両方のスタイルのPEPを、web [5] 上で見ることができるHTMLに変換するためのPythonスクリプトがあります。プレーンテキストのPEPをパースして変換する処理はこのスクリプトにふくれまれます。reStructuredTextのPEPのパースと変換をする場合には、スクリプトから Docutils のコードを呼び出して行われます。

PEPヘッダー前文

PEPは、RFC 822のスタイルのヘッダー前文から書き始める必要があります。ヘッダーは次のような順番で書かれなければなりません。"*"記号のついたヘッダーはオプションです。後で説明します。それ以外のヘッダーは必須です。

作者のヘッダには、すべてのPEPの作者/オーナーの名前と、オプションでEメールアドレスを列挙します。作者のヘッダは、Eメールアドレス付きの場合には次のようなフォーマットで書かなければなりません。

Random J. User <address@dom.ain>

メールアドレスなしの場合には次のように書きます。

Random J. User

過去の経緯から、"address@dom.ain (Random J. User)"という形式で書かれたPEPも数多くありますが、PEPを新しく作成する場合には上記で説明したような表記にしてください。また、PEPをアップデートする場合には、上記のフォーマットに変更することも可能です。

もし作者が複数いる場合には、RFC 2822の行連結規則に従って、複数行に分けて記述してください。PEP内のEメールアドレスは、スパムメール業者対策として、少し変更された表現で表示されます。

注釈

Standards Track PEPにのみ、Resolutionヘッダーが必要となります。これは、PEPに関する発表を行ったEメールのメッセージもしくはその他のWebのリソースへのURLを含みます。

通常、初期のドラフトのフェーズで行われるように、PEPが公に議論されていない時には、Discussions-Toヘッダーに、議論を行っているメーリングリストや、URLを記載します。作者がプライベートで議論している場合や、python-list, python-devといったメーリングリストで議論している場合にはDiscussions-Toヘッダーは必要ありません。Discussions-Toヘッダーに書いたEメールアドレスは少し変更された形式で表現されます。

Typeヘッダーには、PEPの種類(Standards Track, Informational, Process)を指定します。

PEPのフォーマットはContent-Typeヘッダーで指定します。指定できる値は、プレーンテキストのPEP(PEP 9 [3] 参照)の場合は"text/plain"。reStructuredTextのPEP(PEP 12 [4] 参照)の場合には"text/x-rst"を指定します。Content-Typeヘッダーがない場合にデフォルトはプレーンテキスト("text/plain")です。

Createdヘッダーには、PEPに番号が割り振られた日時を指定します。Post-Historyは、新しいバージョンののPEPをpython-list, python-devあるいは両方に投稿した日時を記録します。両方のヘッダーとも、14-Aug-2001のような、dd-mmm-yyyyというフォーマットで書きます。

Standards Track PEPの場合には、その機能がリリースされるPythonのバージョンを示す、Python-Versionヘッダーを含めなければなりませんInformational PEPとProcess PEPではPython-Versionヘッダーは不要です。

PEPにはRequiresヘッダーを含めることができます。これは、そのPEPが依存しているPEPの番号を指定します。

また、最新のドキュメントで古いPEPを置き換えられる場合には、Replaced-Byヘッダーを設定します。値には、現在のPEPを置き換えるPEPの番号を指定します。新しい方のPEPは、置き換えたPEPの番号を指定した、Replacesヘッダーを設定します。

補助ファイル

PEPにはダイアグラムなどの補助ファイルを含めることができます。これらのファイルは、 pep-XXXX-Y. という形式の名前にします。"XXXX"はPEPの番号で、"Y"は1から始まる連続した数値です。"ext"は"png"などの、実際のファイルの拡張に置き換えてください。

PEPのバグの報告/更新の投稿

どのようにPEPのバグを報告したり、更新を投稿するかは、PEPの成熟度、PEP作者の好み、送ろうとしているコメントの性質によって異なります。PEPが初期のドラフト段階であれば、直接PEPの作者にコメントや変更点を送るのがベストでしょう。ステータスが先に進んでいる場合や、完了しているPEPに対してコメントを送る場合には、Pythonの issue tracker を使うと、内容が保存されるため、望ましいでしょう。もしもPEPの作者がPython開発者の場合には、"bug/patch"を彼に設定します。そうでない場合には、PEP編集者を設定します。

どちらに送るかわからない場合には、まず最初にPEPの作者および編集者、あるいは両方に確認してください。

PEP作者がPythonコミッターであれば、"svn commit"を使用して自分でPEPの変更をコミットすることで、更新をかけることもできます。

PEPの所有権の譲渡

時々、PEPの所有権を新しいチャンピオンに譲渡しなければならない場面があるでしょう。我々としては、共著者として、PEPの原作者の名前も残した方が良いと考えますが、そうするかどうかは原作者の考え方次第です。所有権を譲渡する理由として適切なのは、原作者がそのPEPを更新したり、完成させたりする時間、もしくは興味がなくなった、メールに応答できないなど、ネットが使用できる環境から遠ざかっている、などがあります。PEPの方向性に同意できないから、というのは良くなり理由です。PEPの作者はできるだけコンセンサスを取ろうと努力しますが、もしそれができないのであれば、対抗案のPEPを投稿することもできます。

PEPの所有権を引き受けたい場合には、原作者とPEP編集者<peps@python.org>の両方に、引き継ぐことができないか問い合わせるメールを送ってください。もし、常識的な期間の範囲内で原作者がメールの返信を返さない場合には、PEP編集者が一方的に決定を行うこともあります。ただし、この決定はひっくり返すことも可能です:)。

PEP編集者の責務とワークフロー

PEP編集者は<peps@python.org>メーリングリストに参加しなければなりません。PEPに関連するメールのやりとりはかならず<peps@python.org>に、もしくはCCで送ってください。ただし、クロスポストは行わないでください。

新しく来たPEPごとに、編集者は次のようなことを行います。

  • PEPを読み、準備が整っているかチェックします。そのアイディアが受け入れられそうかどうかに関わらず、PEPのアイディアが技術的に意味を持っているかどうか確認します。

  • 内容を正確に説明しているタイトルを付けます。

  • 自然言語(スペルや文法、構文)、マークアップ(reST PEPの場合)、コードスタイル(サンプルコードがPEP 8&7にマッチしているか？)という観点でPEPの編集を行います。

もしも、PEPの準備ができていない場合には、編集者は変更してもらうために、指示を付けて作者に送り返します。

PEPがリポジトリに格納する準備ができると、PEP編集者は次のようなことを行います:

  • PEPの番号を割り振ります。ほとんどの場合は、利用可能な最小の数値を指定しますが、666や3141のように、時々特別な/ジョークの番号が付けられます。

  • PEPをPEP 0のリストに追加します。カテゴリーリストと、番号リストの2箇所追加します。

  • PEPをSVNに追加します。Subversionのリポジトリの使い方の説明に関しては、 the FAQ for Developers を参照してください。

    読み込み専用でリポジトリをチェックアウトするには次のようにタイプします:

    svn checkout http://svn.python.org/projects/peps/trunk peps

    読み書き両方できる形でチェックアウトするには次のようにタイプします:

    svn checkout svn+ssh://pythondev@svn.python.org/peps/trunk peps

    svn:eol:style プロパティは native に、 svn:keywords プロパティには Author Date Id Revision を設定してください。

  • python.orgをモニターして、PEPがpython.orgに適切に追加されているかを確認します。

  • 次の段階に入ったという情報をPEP作者に送ります。python-list, python-dev, python-3000にも投稿します。

既存のPEPのアップデートについても、peps@python.orgに連絡が来ます。多くのPEP作者はSVNのコミット権限を持っていないため、PEP編集者がコミットを行います。

Pythonのコードベースへの書き込み権限を持っている開発者が書いたり、メンテナンスしているPEPも数多くあります。PEP編集者はpython-checkinsメーリングリストをモニターし、PEPの変更を確認します。構文や文法、スペル、マークアップのミスを見つけたら修正を加えます。

編集者はPEPの判断は行いません。編集者が行うのは、管理と編集の部分になります。PEP 1のような場合を除き、作業のボリュームはそれほど多くはありません。

リソース:

参照と脚注

著作権

このドキュメントはパブリック・ドメインに属します。