pep 1 日本語翻訳(意訳含む)
※注意:これは個人学習の参考としてお考え下さい。著作権はすべてpython.orgに帰するものです。学習の助けになれば幸いです。
※本記事の利用によるすべての責任は負いかねます。
翻訳日:2023/12/28
PEP 1 – PEP の目的とガイドライン
著者：バリー・ワルシャワ、ジェレミー・ヒルトン、デヴィッド・グッガー、アリッサ・コグラン
状態：アクティブ
タイプ：プロセス
作成日：2000 年 6 月 13 日
事後履歴 : 2001年3月21日、2002年7月29日、2003年5月3日、2012年5月5日、2013年4月7日
PEPとは何ですか?
PEP は Python Enhancement Proposal の略です。
PEP は、Python コミュニティに情報を提供したり、Python またはそのプロセスや環境の新機能を説明したりする設計文書です。
PEP は、機能の簡潔な技術仕様(並びに、)機能の理論的根拠を提供する必要があります。
私たちは PEP が、主要な新機能を提案し、問題に関するコミュニティからの意見を収集し、Python に組み込まれた設計上の決定を文書化するための主要なメカニズムとなることを意図しています。
PEP 作成者は、コミュニティ内で合意を形成し、反対意見を文書化する責任があります。
PEP はバージョン管理されたリポジトリ内にテキスト ファイルとして保持されるため、PEP の改訂履歴は機能提案の履歴記録となります。
この履歴レコードは、古いリビジョンを取得するための通常の git コマンドで利用でき、 GitHub で参照することもできます。
PEP の聴衆(読み手)
PEP の一般的な主な対象者は、CPython リファレンス インタプリタとその選出された運営評議会のコア開発者、および Python 言語仕様の他の実装の開発者です。
ただし、Python コミュニティの他の部分でも、予期される API 規約を文書化し、複数のプロジェクトにわたるコラボレーションを必要とする複雑な設計調整の問題を管理するために、このプロセス (特に情報 PEP) を使用することを選択する場合があります。
PEP の種類
PEP には次の 3 種類があります。
Standards Track PEP は、Python の新しい機能または実装について説明します。また、後続の PEP が将来のバージョンで標準ライブラリのサポートを追加する前に、現在の Python バージョンの標準ライブラリの外でサポートされる相互運用性標準についても説明する場合があります。
Informational PEP は、 Python の設計上の問題について説明したり、Python コミュニティに一般的なガイドラインや情報を提供します。
しかし、新しい機能を提案するものではありません。
(情報) PEP は必ずしも Python コミュニティの合意や推奨を表すものではないため、ユーザーと実装者は自由にPEP を無視したり、または、そのアドバイスに従うことができます。Process PEP は、 Python を取り巻くプロセスを記述したり、プロセス (またはプロセス内のイベント) への変更を提案したりします。
Process PEP は Standards Track PEP に似ていますが、Python 言語自体以外の領域に適用されます。彼らは実装を提案するかもしれませんが、Python のコードベースについては提案しません。
多くの場合、コミュニティの合意が必要です。Informational PEP とは異なり、これらは推奨以上のものです。
通常、ユーザーはそれらを無視することはできません。
例には、手順、ガイドライン、意思決定プロセスの変更、Python 開発で使用されるツールや環境の変更などが含まれます。meta-PEP もProcess PEP とみなされます。
PEP ワークフロー
Python 運営評議会
この PEP には、「運営評議会」または「評議会」についての言及がいくつかあります。PEP 13に記載されている選出された運営評議会の現在のメンバーを指し、PEP が承認されるか拒否されるかを決定する最終権限者としての役割を果たします。
Python のコア開発者
この PEP には「コア開発者」への言及がいくつかあります。PEP 13で説明されている現在アクティブな Python コア チーム メンバーを指します。
Python の（レガシー） BDFL
この PEP の以前のバージョンでは、PEP 意思決定者に対して「BDFL-Delegate」というタイトルが使用されていました。
これは、Python の以前のガバナンス モデルへの歴史的参照であり、すべての設計権限は最終的に Python プログラミング言語のオリジナルの作成者である Guido van Rossum に由来していました。
対照的に、運営評議会の設計権限は、現在活動しているコア開発者による選出に基づいています。現在は、BDFL-Delegate の代わりに PEP-Delegate が使用されます。
PEP エディター
PEP 編集者は、PEP ワークフローの管理面および編集面の管理 (PEP 番号の割り当てやステータスの変更など) を担当する個人です。詳細については、 「PEP 編集者の責任とワークフロー」を参照してください。
PEP の編集は現在の編集者の招待によって行われており、@python/pep-editorsGitHub でメンションすることで連絡を取ることができます。すべての PEP ワークフローは、GitHub PEP リポジトリの問題とプル リクエストを介して実行できます。
Python のアイデアから始める
PEP プロセスは、Python の新しいアイデアから始まります。
単一の PEP に”純粋”かつ重要な提案または新しいアイデアを含めることを強くお勧めします。
PEP が集中するほど、成功する傾向があります。ほとんどの機能強化とバグ修正は PEP を必要とせず、Python 問題トラッカーに直接送信できます。
PEP 編集者は、PEP 提案があまりにも焦点がぼけている、または範囲が広すぎると思われる場合、拒否する権利を留保します。疑わしい場合は、PEP をいくつかの焦点を絞ったものに分割してください。
各 PEP にはチャンピオンが必要です。この人物は、以下で説明するスタイルと形式を使用して PEP を作成し、適切なフォーラムでの議論を先導し、アイデアに関するコミュニティのコンセンサスを構築しようとする人です。
PEP チャンピオン (別名著者) は、まずそのアイデアが PEP 可能かどうかを確認する必要があります。Python 談話のタイピング カテゴリ(静的型付けのアイデアの場合) やパッケージ化カテゴリ(パッケージ化のアイデアの場合)など、より専門的な場所が適切でない限り、通常は、Python 談話のアイデアカテゴリに投稿するのが最善の方法です。
PEP を作成する前にアイデアを公的に精査することは、潜在的な作成者の時間を節約することを目的としています。
Python を変更するために多くのアイデアが提案されましたが、さまざまな理由で拒否されました。
最初に Python コミュニティにアイデアが独創的かどうかを尋ねることは、事前の議論に基づいて拒否されることが確実な内容に多大な時間を費やすことを防ぐのに役立ちます (インターネット検索が必ずしもうまくいくとは限りません(意訳：コミュニティーの性質・独創性の有無はコミュニティーに聞こう！！))。
また、アイデアが作成者だけでなくコミュニティ全体に適用できることを確認するのにも役立ちます。
アイデアが作者にとって良さそうに思えたからといって、それが Python が使用されるほとんどの分野のほとんどの人にとってうまくいくとは限りません。
チャンピオンが (提案者や)Python コミュニティにアイデアが受け入れられる可能性があるかどうかを尋ねてきたら、PEP 草案を上記の適切な会場に提出する必要があります。これにより、作成者は PEP 草案を具体化し、適切な形式で高品質なものにし、提案する機会が得られます。
PEPの提出
上記の最初の説明に続いて、ワークフローは、PEP の共著者のいずれかがコア開発者であるかどうかによって異なります。
PEP の共著者の 1 人以上がコア開発者である場合、彼らは以下に概説するプロセスに従う責任があります。それ以外の場合（つまり、共著者の誰もコア開発者ではない場合）、PEP の作成者は PEP のスポンサーを見つける必要があります。
理想的には、コア開発者スポンサーが特定されますが、運営評議会の承認を得て非コア スポンサーの選択も可能です。
GitHub の「PEP エディター」チームのメンバーとタイピング評議会 ( PEP 729 ) のメンバーは、スポンサーになることが事前に承認されています。
スポンサーの仕事は、PEP プロセスのロジスティクスを通じて PEP 作成者を支援するためのガイダンスを提供することです (メンターのような役割を果たします)。
スポンサーになったからといって、 その人が後で共著者または PEP 代表になる資格を剥奪されるわけではありません (ただし、両方ではありません)。PEP のスポンサーはヘッダーの「Sponsor:」フィールドに記録されます。
PEP を共同作成するスポンサーまたはコア開発者が、PEP を提出する準備ができていると判断したら、提案を GitHub プル リクエスト経由でドラフト PEP として草稿を提出する必要があります。
草稿は以下に説明するように、 PEP スタイルで書かれている必要があります。
そうしないと、直ちにレビューに失敗します (ただし、軽微なエラーは編集者によって修正される場合があります)。
標準的な PEP ワークフローは次の様式です。
PEP 作成者は、PEP リポジトリをフォークし、新しい PEP を含む という 名前のファイルを作成します 。公開または PR 内の PEP によって使用されていない、利用可能な PEP 番号である必要があります。
「PEP:」ヘッダー フィールドに、ファイル名と一致名称で PEP 番号をドラフト PEP 番号を入力します。
「Type:」ヘッダーフィールドに、必要に応じて「Standards Track」、「Informational」、または「Process」を入力し、「Status:」フィールドに「Draft」と入力します。詳細については、「PEP ヘッダー プリアンブル」を参照してください。
.github/CODEOWNERSを更新して、PEP リポジトリへの書き込みアクセス権を持つ共著者またはスポンサーが新しいファイルのリストに表示されるようにします。これにより、ファイルを変更する将来のプル リクエストが確実に割り当てられます。
これを GitHub フォークにプッシュし、プル リクエストを送信します。
PEP エディターは、PR の構造、フォーマット、その他のエラーを確認します。reST 形式の PEP の場合、PEP 12がテンプレートとして提供されます。また、PEP で使用される reST マークアップの完全な紹介も提供します。
承認基準は次のとおりです。承認されると、PEP に番号が割り当てられます。
レビュー プロセスが完了し、PEP 編集者がそれを承認すると (これはPEP を受け入れることと同じではないことに注意してください)、編集者はプル リクエストをメインに強制的にコミットします。
PEP 編集者は、PEP を不当に拒否しません。PEP ステータスを拒否する理由には、作業の重複、技術的に不健全である、適切な動機を提供していない、下位互換性に対処していない、または Python の哲学に沿っていないなどが含まれます。
運営評議会は承認段階で相談を受けることができ、ドラフトの PEP 可能性の最終的な裁定者となります。
PEP リポジトリへの書き込みアクセス権を持つ開発者は、新しい PEP を作成してコミットすることで、PEP 番号を直接要求できます。
その際、開発者は、通常は PEP エディターが処理するタスクを処理する必要があります (「PEP エディターの責任とワークフロー」を参照)。
これには、初期バージョンが PEP を提出するために期待される基準を満たしていることを確認することが含まれます。
あるいは、開発者であっても、プル リクエスト経由で PEP を送信する必要があります。
その場合には、通常は自分でプロセスを処理することが期待されます。
PEP 編集者のサポートが必要な場合は、@python/pep-editors GitHub で言及してください。
更新が必要な場合、PEP 作成者 (または共同開発者) がPEP リポジトリへの書き込みアクセス権を持っていれば、新しいバージョンをチェックインできます。PEP 番号を早期に割り当てておくと、特に複数のドラフト PEP が同時に検討されている場合に、参照しやすくなります。
Standards Track PEP は、設計文書とリファレンス実装の 2 つの部分で構成されます。原理的に良さそうなアイデアでも、実装のテストを受けると実用的ではないことが判明する場合があるため、少なくともプロトタイプ実装を PEP と共同開発することが一般に推奨されます。
PEP について話し合う
PEP 番号が割り当てられ、ドラフト PEP がPEP リポジトリにコミットされたらすぐに、PEP のディスカッション スレッドを作成して、その内容を議論およびレビューするための中心的な場所を提供する必要があります。また、PEP は、Discussions-Toヘッダーにリンクされています。
PEP の作成者 (または、該当する場合はスポンサー) は、以下の基準が満たされる限り、適切な議論の場を選択できます。
このフォーラムは PEP のテーマに適しています。
このスレッドは Web 上で公開されており、関係者全員が参加できます。
議論はPython コミュニティ行動規範の対象となります。
現在のディスカッション スレッドへの直接リンクは、ヘッダーの下部にあります。
Python DiscourseのPEP カテゴリは、 ほとんどの新しい PEP で推奨される選択肢ですが、歴史的にはPython-Devメーリング リストが一般的に使用されていました。
一部の特殊なトピックには、それぞれ PEP のタイピングとパッケージ化に関する Python Discourse のタイピング カテゴリとパッケージング カテゴリなど、特定の場所があります。
PEP 作成者が最適な会場について確信が持てない場合は、PEP スポンサーと PEP 編集者がそれに応じてアドバイスすることがあります。
PEP に大幅な書き換えや、提案された仕様に対するその他の大幅な実質的な変更が加えられた場合、通常は、追加のフィードバックを求めるために、選択した場所に新しいスレッドを作成する必要があります。
問題が発生した場合は、 リンクを更新し、この新しいスレッドを指すDiscussions-To新しいエントリを追加する必要があります。
ディスカッションの場として選択されない場合は、ドラフトPEP がリポジトリにコミットされ、十分に大きな変更が加えられた場合には 、少なくともレンダリングされた PEP とDiscussions-Toスレッドへのリンクを含む簡単な発表投稿を PEP カテゴリに作成する必要があります。新しいスレッドをトリガーするために作成されました。
PEP 作成者は、PEP をレビューに提出する前に、PEP に関するコミュニティからのフィードバックを収集する責任があります。
ただし、長々と終わりのない議論を避けるために、設計の初期段階で非公開またはより限定的に調整されたフィードバックを求めること、PEP の主題に関する専門知識を持つ他のコミュニティ メンバーと協力すること、適切に専門化された議論を選択することなどの戦略が必要です。 PEP のトピック (該当する場合) については、検討する必要があります。PEP 作成者は、ここで独自の裁量を使用する必要があります。
PEP に番号が割り当てられ、PEP リポジトリにコミットされると、実質的な問題は通常、プライベート チャネル、GitHub プル リクエスト レビュー、または無関係な場ではなく、正規のパブリック スレッドで議論される必要があります。
これにより、誰もがフォローして貢献できるようになり、議論の断片化が回避され、PEP レビュー プロセスの一部として完全に考慮されるようになります。
この、指定されたスレッドに対するコメント、サポート、懸念、その他のフィードバックは、運営評議会または PEP 代表が PEP を検討する際に考慮する重要な部分です。
PEP のレビューと解決策
著者は PEP を完了すると、スタイルと一貫性について PEP 編集者にレビューを要求することができます。
ただし、PEP のコンテンツのレビューと承認は最終的には運営評議会の責任であり、著者 (およびスポンサーがいる場合はスポンサー) が PEP の最終的なレビューと解決の準備ができたと判断した場合、運営評議会の問題を開始することによって正式に開始されます。
選択されたケース（変更が明らかに有益で受け入れられる準備ができているが、PEP がまだ正式にレビューに提出されていない場合）のプロセスを迅速化するために、運営評議会は最初に PEP 作成者に依頼を通知して PEP レビューを開始することもあります。
PEP 承認の最終権限は運営評議会です。
ただし、新しい PEP が提案されるたびに、その PEP について最終決定を下すのに適切な経験があると考えるコア開発者は、その意図を運営評議会に通知することで、 PEP 代理人としての役割を果たすことを申し出ることができます 。
それを運営評議会が提案を承認した場合、PEP 代表はその PEP を承認または拒否する権限を持ちます。
Python 型システムに関連する PEP については、Typing Council ( PEP 729 ) が Steering Council に推奨事項を提供します。このような推奨事項をリクエストするには、 Typing Council の問題トラッカーで問題を作成してください。
「PEP-Delegate」という用語は、PEP の指定された意思決定者に対する運営評議会のガバナンス モデルの下で使用され、PEP のヘッダーの「PEP-Delegate」フィールドに記録されます。「BDFL-Delegate」という用語は、PEP-Delegate の非推奨のエイリアスであり、Python がBDFLによって主導されていた時代の遺産です。「BDFL-Delegate」への従来の参照はすべて「PEP-Delegate」と同等として扱う必要があります。
PEP 代表者としての推薦を申し出る個人は、関連する著者および (存在する場合) PEP のスポンサーに通知し、運営評議会にリクエストを提出する必要があります (これは新しい号を通じて行うことができます)。
この責任を負う者は、いつでも自由に運営評議会に追加のガイダンスを求めることができ、また、(意訳：議長に様に)他のコア開発者のアドバイスや視点を考慮することも期待されています。
運営評議会は通常、そのような自己推薦をデフォルトで承認しますが、拒否することもできます。
運営評議会が PEP 代議員としての自己推薦を拒否する考えられる理由としては、潜在的な利益相反の認識 (例: PEP 提出者と同じ組織で働いている)、または単に別の潜在的な PEP を検討していることが挙げられますが、これらに限定されません。
デリゲートがより適切になります。コア開発者 (または他のコミュニティ メンバー) が、特定の PEP に対する PEP デリゲートの適合性に関して懸念がある場合、運営評議会にデリゲートの検討を依頼することができます。
ボランティアが名乗り出ない場合、運営評議会は、その PEP の PEP 代表として喜んで務める候補者を特定するために、関連する専門知識を持ったコア開発者 (および場合によっては他の Python コミュニティ メンバー) にアプローチします。
適切な候補が見つからない場合、PEP は候補が見つかるまで延期としてマークされます。
以前に任命された PEP 代議員は辞任することを選択するか、理事会から辞任を求められる場合があります。
その場合、新しい PEP の場合と同じ方法で新しい PEP 代議員が任命されます (適切な者がいない場合の PEP の延期を含む)代替品が見つかります）。PEP 代表者が辞任を求められた場合、PEP の事前の受諾または拒否は無効となり、ドラフト状態に戻ります。
このような常設の代表団が設置されると、運営評議会は、後続の評議会、コア開発者、およびより広範な Python コミュニティが、現在存在する代表団、その代表団が設置された理由、および下の状況を理解できるように、十分な公的記録を維持します。もう必要なくなるかもしれません。
PEP が受け入れられるには、特定の最低基準を満たしている必要があります。提案された機能強化についての明確かつ完全な説明でなければなりません。
機能強化は純的な改善を示すものでなければなりません。提案された実装は、該当する場合、確実なものでなければならず、インタプリタを過度に複雑にしてはなりません。最後に、提案された機能強化が運営評議会に受け入れられるためには、「Python 」である必要があります。(ただし、「pythonic」は不正確な用語です。運営評議会が受け入れられるものであれば何でも定義できます。このロジックは意図的に循環しています。)標準ライブラリ モジュールの受け入れ基準については、 PEP 2を参照してください 。
運営評議会によって別途承認された場合を除き、PEP 決議の宣言はPython DiscourseのPEP カテゴリに投稿されます 。
PEP が受け入れられたら、リファレンス実装を完了する必要があります。リファレンス実装が完了し、メインのソース コード リポジトリに組み込まれると、ステータスが「最終」に変更されます。
言語機能または標準ライブラリ API の長期安定性を約束する前に、追加の設計およびインターフェイスのフィードバックを収集できるようにするために、PEP を「Provisional(暫定)」としてマークすることもできます。これは「Provisionally Accepted」の略で、提案がリファレンス実装に含めることが受け入れられたが、完全な設計が「最終」とみなされる前に追加のユーザー フィードバックが必要であることを示します。
通常の承認された PEP とは異なり、暫定的に承認された PEP は、関連する変更が Python リリースに含まれた後でも拒否または取り下げられる場合があります。
「Provisional」ステータスに依存する必要性を避けるために、可能な限り提案の範囲を縮小することが望ましいと考えられます (たとえば、一部の機能を後の PEP に延期するなど)。これは、このステータスがより広範な Python におけるバージョン互換性のコードのエコシステム問題につながる可能性があるためです。
PEP 411 には、暫定ステータスの潜在的な使用例に関する追加の詳細が記載されています。
PEP には「遅延」ステータスを割り当てることもできます。PEP の作成者または編集者は、PEP に進捗がない場合に、PEP にこのステータスを割り当てることができます。PEP が延期されると、PEP 編集者は PEP をドラフト ステータスに再割り当てできます。
PEP は「拒否」することもできます。結局のところ、それは良い考えではなかったのかもしれません。
この事実を記録しておくことが依然として重要です。「撤回」ステータスも同様です。これは、PEP 作成者自身が PEP が実際には悪いアイデアであると判断したか、競合する提案の方がより良い代替案であると受け入れたことを意味します。
PEP が承認、拒否、または撤回されると、それに応じて PEP を更新する必要があります。Status フィールドの更新に加えて、少なくとも、PEP に関する決定を下す関連投稿への直接リンクを含む Resolution ヘッダーを追加する必要があります。
PEP は別の PEP に置き換えられて、元の PEP が廃止されることもあります。これは、API のバージョン 2 がバージョン 1 を置き換えることができる情報 PEP を対象としています。
PEP のステータスの可能なパスは次のとおりです。
図には示されていませんが、「承認済み」PEP は、承認後でも技術的には「拒否」または「撤回」に移行する可能性があります。これは、PEP の承認前には気付かなかった設計の根本的な欠陥が実装プロセスで明らかになった場合にのみ発生します。暫定 PEP とは異なり、これらの移行は、承認された提案が Python リリースに含まれていない場合にのみ許可されます。リリースされた変更は、代わりに通常の非推奨プロセスを通過する必要があります (非推奨の根拠を提供する新しい PEP が必要になる場合があります)。
一部の情報 PEP とプロセス PEP は、完了する予定がない場合、ステータスが「アクティブ」になる場合があります。たとえば、PEP 1 (この PEP)。
PEP メンテナンス
一般に、PEP は、Accepted、Final、Rejected、または Superseded 状態に達すると、実質的に変更されなくなります。
解決に達すると、PEP は生きた仕様ではなく歴史的な文書とみなされます。予想される動作に関する正式な文書は、コア機能については言語リファレンス、 標準ライブラリ モジュールについてはライブラリ リファレンス、パッケージ化についてはPyPA 仕様など、別の場所で維持する必要があります。
実装の経験とユーザーのフィードバックに基づく変更が、暫定または (SC の承認を得て) 承認済み状態にあるときに標準トラック PEP に加えられた場合、PEP がその時点での実装を正確に説明するように、PEP にその変更を記録する必要があります。 Finalとマークされています。
アクティブな (情報およびプロセス) PEP は、開発慣行やその他の詳細への変更を反映するために、時間の経過とともに更新される場合があります。このような場合に従う正確なプロセスは、問題の PEP の性質と目的によって異なります。
場合によっては、延期された PEP や取り消された PEP がメジャー アップデートで復活することもありますが、多くの場合、新しい PEP を提案する方が良いでしょう。
成功する PEP (構成には)何が含まれますか?
各 PEP には次の部分/セクションが必要です。
前文 –RFC 2822スタイルのヘッダーには、PEP 番号、短い説明的なタイトル (最大 44 文字に制限)、名前、およびオプションで各著者の連絡先情報などを含む、PEP に関するメタデータが含まれます。
要約 – 対処されている技術的問題の短い (約 200 ワード) 説明。
動機 – Python 言語、ライブラリ、またはエコシステムを変更したい PEP にとって、動機は非常に重要です。PEP が解決する問題に対処するには既存の言語仕様が不十分である理由を明確に説明する必要があります。
これには、Python エコシステムの重要なプロジェクトから PEP に関する文書化されたサポートを収集することが含まれる場合があります。十分な動機のない PEP の提出は拒否される場合があります。理論的根拠 – 理論的根拠は、特定の設計上の決定が行われた理由を説明することで仕様を具体化します。検討された代替設計と、その機能が他の言語でどのようにサポートされるかなど、関連する作業について説明する必要があります。
理論的根拠は、コミュニティ内の合意の証拠を提供し、議論中に提起された重要な反対意見や懸念事項について説明する必要があります。
仕様 – 技術仕様では、新しい言語機能の構文とセマンティクスを説明する必要があります。仕様は、少なくとも現在の主要な Python プラットフォーム (CPython、Jython、IronPython、PyPy) に対して競合する相互運用可能な実装を可能にするのに十分詳細なものである必要があります。
下位互換性 – 下位非互換性を導入するすべての PEP には、これらの非互換性とその重大度を説明するセクションが含まれている必要があります。PEP は、作成者がこれらの非互換性にどのように対処するかを提案しているかを説明する必要があります。十分な下位互換性に関する論文のない PEP の提出は、完全に拒否される場合があります。
セキュリティへの影響 – PEP に関連してセキュリティ上の懸念がある場合は、PEP のレビュー担当者がそれを認識していることを確認するために、その懸念を明示的に書き出す必要があります。
これを教える方法 – 新しい機能を追加したり、言語の動作を変更したりする PEP の場合、初心者および経験豊富なユーザーに PEP を自分の仕事に適用する方法を教える方法に関するセクションを含めると役立ちます。
このセクションには、ユーザーが新しい機能を採用したり、言語変更を使用するようにコードを移行したりするのに役立つ重要なポイントと推奨されるドキュメントの変更が含まれる場合があります。
リファレンス実装 – リファレンス実装は、PEP に「最終」ステータスが与えられる前に完了する必要がありますが、PEP が受け入れられる前に完了する必要はありません。コードを記述する前に仕様と理論的根拠について合意に達するというアプローチには利点がありますが、API の詳細に関する多くの議論を解決する場合には、「大まかな合意を得てコードを実行する」という原則が依然として役立ちます。
最終的な実装には、Python 言語リファレンスまたは標準ライブラリ リファレンスのいずれかに適したテスト コードとドキュメントが含まれている必要があります。
拒否されたアイデア – PEP の議論を通じて、受け入れられなかったさまざまなアイデアが提案されます。拒否されたアイデアは、拒否された理由とともに記録する必要があります。これは、PEP の最終バージョンの背後にある思考プロセスを記録するのに役立つだけでなく、その後の議論で拒否された同じアイデアを再び持ち出すのを防ぐのにも役立ちます。
ある意味、このセクションは、特定のアイデアが最終的に追求されなかった理由に特に焦点を当てた、根拠セクションのブレイクアウト セクションと考えることができます。
未解決の問題 – PEP が草案段階にある間に、さらなる議論が必要となるアイデアが浮上する可能性があります。それらのアイデアは記録され、検討されているものの具体的な解決策は持っていないことが人々にわかるようにする必要があります。これにより、PEP の検討準備に必要なすべての問題が確実に完了するようになり、事前の議論を重複して行う人が減ります。
脚注 – PEP で引用されている脚注のコレクションであり、非インライン ハイパーリンク ターゲットをリストする場所です。
著作権/ライセンス – 新しい PEP はそれぞれ、パブリック ドメインとCC0-1.0-Universalの二重ライセンスの下に置く必要があります(例については、この PEP を参照してください)。
※通常はこの辺までで十二分かと思います。(note翻訳者より)
PEP フォーマットとテンプレート
PEP は、 reStructuredText形式を使用して UTF-8 でエンコードされたテキスト ファイルです。reStructuredText を使用すると、非常に読みやすいリッチなマークアップが可能になりますが、見た目が良く機能的な HTML も得られます。PEP 12 には、手順とPEP テンプレートが含まれています。
PEP テキスト ファイルは、 オンラインで読みやすくするために ( Sphinxベースのビルド システムを介して)自動的に HTML に変換されます。
PEP ヘッダー プリアンブル
各 PEP は次の文字で始まる必要があります。RFC 2822スタイルのヘッダー プリアンブル。ヘッダーは次の順序で表示される必要があります。「*」のマークが付いているヘッダーはオプションであり、以下で説明します。他のヘッダーはすべて必須です。
PEP: <pep number>
Title: <pep title>
Author: <list of authors' real names and optionally, email addrs>
* Sponsor: <real name of sponsor>
* PEP-Delegate: <PEP delegate's real name>
Discussions-To: <URL of current canonical discussion thread>
Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
* Topic: <Governance | Packaging | Release | Typing>
* Requires: <pep numbers>
Created: <date created on, in dd-mmm-yyyy format>
* Python-Version: <version number>
Post-History: <dates, in dd-mmm-yyyy format,
inline-linked to PEP discussion threads>
* Replaces: <pep number>
* Superseded-By: <pep number>
* Resolution: <url>
Author ヘッダーには、PEP のすべての作成者/所有者の名前と、オプションで電子メール アドレスがリストされます。Author ヘッダー値の形式は次のようにする必要があります。
Random J. User <random@example.com>
電子メール アドレスが含まれている場合、次のようにします。
Random J. User
住所が与えられていない場合。
複数の著者がいる場合は、それぞれを次の行に分けて入力する必要があります。RFC 2822継続行規則。PEP 内の個人の電子メール アドレスは、スパム収集者に対する防御として隠蔽されることに注意してください。
スポンサー フィールドには、どの開発者 (コア、または運営評議会によって承認された開発者) が PEP のスポンサーになっているかが記録されます。PEP の作成者の 1 人がコア開発者である場合、スポンサーは必要ないため、このフィールドは省略する必要があります。
PEP-Delegate フィールドは、PEP を承認するか拒否するかについての最終決定を行うために運営評議会によって任命された個人を記録するために使用されます。(reStructuredText PEP の電子メール アドレス マスキングの制限により、デリゲートの電子メール アドレスは現在省略されています。)
注: Resolution ヘッダーは Standards Track PEP にのみ必要です。これには、PEP に関する発表 (つまり、承認または拒否) が行われる電子メール メッセージまたはその他の Web リソースを指す URL が含まれています。
Discussions-To ヘッダーは、PEP の現在の正規ディスカッション スレッドへの URL を提供します。メール リストの場合、これは単なる mailto: またはリスト自体へのハイパーリンクではなく、リストのアーカイブ内のスレッドへの直接リンクである必要があります。
Type ヘッダーは、PEP のタイプ (Standards Track、Informational、または Process) を指定します。
オプションの Topic ヘッダーには、PEP が属する特別なトピック (存在する場合) がリストされます。既存のトピックについては、トピック索引を参照してください。
Created ヘッダーは、PEP に番号が割り当てられた日付を記録します。一方、Post-History は、PEP の Discussions-To スレッドの日付と対応する URL を記録するために使用されます。前者はリンクされたテキストとして、後者はリンクされたテキストとして記録されます。リンクターゲット。両方の日付セットは、dd-mmm-yyyy次の形式である必要があります14-Aug-2001。
Standards Track PEP には通常、機能がリリースされる Python のバージョンを示す Python-Version ヘッダーがあります。Python-Version ヘッダーのない Standards Track PEP は、最初は外部ライブラリとツールを通じてサポートされる相互運用性標準を示し、その後、標準ライブラリにサポートを追加するために後の PEP によって補完される可能性があります。情報 PEP とプロセス PEP には、Python-Version ヘッダーは必要ありません。
PEP には、この PEP が依存する PEP 番号を示す Requires ヘッダーがある場合があります。
PEP には、PEP が後のドキュメントによって廃止されたことを示す Superseded-By ヘッダーが含まれる場合もあります。値は、現在のドキュメントを置き換える PEP の番号です。新しい PEP には、廃止された PEP の番号を含む Replaces ヘッダーが必要です。
補助ファイル
PEP には、図などの補助ファイルが含まれる場合があります。このようなファイルには という名前を付ける必要がありますpep-XXXX-Y.ext。「XXXX」は PEP 番号、「Y」はシリアル番号 (1 から始まります)、「ext」は実際のファイル拡張子 (「png」など) に置き換えられます。
あるいは、すべてのサポート ファイルを というサブディレクトリに置くこともできます pep-XXXX。ここで、「XXXX」は PEP 番号です。サブディレクトリを使用する場合、ファイル内で使用される名前に制約はありません。
既存の PEP の変更
PEP 草案は、検討と解決のために運営評議会または PEP 代表に提出されるまで、作成者の裁量により、自由に議論および修正案に参加することができます。実質的なコンテンツの変更は通常、ヘッダーにリストされている PEP のディスカッション スレッドで最初に提案される必要があります が、コピー編集や修正はGitHub の問題またはGitHub プル リクエストDiscussions-Toとして送信できます。PEP リポジトリへの書き込みアクセス権を持つ PEP 作成者は、GitHub PR を使用して PEP 自体を更新し、変更を送信できます。他の PEP の変更に関するガイダンスについては、「PEP メンテナンス」セクションを参照してください。git push
詳細については貢献ガイドを参照してください。疑問がある場合は、まず PEP 作成者および/または PEP 編集者に確認してください。
PEP 所有権の譲渡
場合によっては、PEP の所有権を新しいチャンピオンに譲渡することが必要になることがあります。
一般に、元の作成者を転送された PEP の共著者として保持することが望ましいですが、それは実際には元の作成者次第です。
所有権を譲渡する正当な理由は、元の作成者が更新したり PEP プロセスを実行する時間や関心がなくなった、またはネットの表面から消えてしまった (つまり、連絡が取れない、または電子メールに応答しない) ことです。
所有権を譲渡する悪い理由は、作成者が PEP の方向性に同意しないことです。PEP プロセスの目的の 1 つは、PEP に関する合意形成を試みることですが、それが不可能な場合、作成者はいつでも競合する PEP を提出できます。
PEP の所有権を引き受けることに興味がある場合は、プル リクエストを通じてこれを行うこともできます。PEP リポジトリをフォークし、所有権を変更して、プル リクエストを送信します。元の作成者と @python/pep-editorsプル リクエストのコメントの両方に言及する必要があります。(元の作成者の GitHub ユーザー名が不明な場合は、電子メールを使用してください。) 元の作成者がタイムリーに応答しない場合、PEP 編集者は一方的な決定を下します (そのような決定が取り消せないわけではありません:)。
PEP 編集者の責任とワークフロー
PEP エディターは@python/pep-editorsGitHub 上のグループに追加する必要があり、PEP リポジトリを監視する必要があります。
PEP リポジトリへの書き込みアクセス権を持つ開発者は、通常は PEP エディターによって処理されるタスクを処理できることに注意してください。あるいは、開発者でも、@python/pep-editorsGitHub でメンションして PEP 編集者に支援を求めることもできます。
エディターに含まれる新しい PEP ごとに、次の処理が実行されます。
PEP がコア開発者によって共同作成されているか、スポンサーとしてコア開発者がいるか、運営評議会によってこの PEP に対して特別に承認されたスポンサーがいることを確認してください。
PEP を読んで、準備ができているかどうかを確認します。音声が聞こえて完了しています。たとえ受け入れられそうにないとしても、アイデアは技術的に意味のあるものでなければなりません。
タイトルは内容を正確に説明する必要があります。
ファイル名の拡張子は正しいです (つまり.rst)。
PEP リポジトリへの書き込みアクセス権を持つ PEP のスポンサーまたは共同作成者としてリストされている全員が.github/CODEOWNERSに追加されていることを確認します。
PEP に目を通し、言語 (スペル、文法、文構造など) およびコード スタイルに明らかな欠陥がないか確認します (例は PEP 7およびPEP 8に準拠している必要があります)。編集者は自分で問題を修正することもできますが、そうする必要はありません (reStructuredText 構文はリポジトリの CI によってチェックされます)。
プロジェクトが PEP から恩恵を受けている、または PEP をサポートしていると描写されている場合は、サポートを明確にするためにプロジェクトからの直接的な兆候が含まれていることを確認してください。これは、実際には推測に基づいたサポートであるにもかかわらず、PEP が誤ってプロジェクトを PEP をサポートしていると表現することを避けるためです。
PEP の準備ができていない場合、編集者は改訂のために具体的な指示とともに作成者に PEP を送り返します。reST フォーマットに問題がある場合は、作成者にPEP 12 をテンプレートとして使用して再送信するよう依頼してください。
リポジトリ用の PEP の準備が完了すると、PEP エディタは次のことを行います。
作成者が有効な PEP 番号を選択していることを確認するか、選択していない場合は番号を割り当てます (ほとんどの場合、次に利用可能な番号ですが、場合によっては 666 や 3141 などの特別な/ジョーク番号である場合もあります)。
100 未満の数値はメタ PEP であることに注意してください。
作成者が PEP のタイプ (「Standards Track」、「Informational」、または「Process」) を正しくラベル付けし、ステータスを「Draft」としてマークしていることを確認してください。
すべての CI ビルドと lint チェックがエラーなしで合格し、レンダリングされたプレビュー出力に明らかな問題がないことを確認します。
新しい (または更新された) PEP をマージします。
作成者に次のステップを通知します (ディスカッション スレッドを開いて PEP を更新する、お知らせを投稿するなど)。
既存の PEP の更新は、 GitHub プル リクエストとして送信する必要があります。
多くの PEP は、Python コードベースへの書き込みアクセス権を持つ開発者によって作成および保守されます。PEP 編集者は PEP リポジトリの変更を監視し、構造、文法、スペル、またはマークアップの間違いを見つけたら修正します。
PEP 編集者は PEP に対して判断を下しません。彼らは管理および編集の部分 (通常は量の少ないタスク) を行うだけです。
リソース：
著作権
このドキュメントは、パブリック ドメインまたは CC0-1.0-Universal ライセンスのどちらか寛容な方に基づいて公開されます。
出典: https://github.com/python/peps/blob/main/peps/pep-0001.rst
最終更新日: 2023-11-29 20:16:51 GMT
この記事が気に入ったらサポートをしてみませんか？