Pyramid アドオンと開発環境のガイドライン

Pylons プロジェクトの一部になろうとするすべてのパッケージにとっての “100% テストカバレージ, 100% ドキュメンテーション” 要件に加えて、 Pyramid アドオンと「開発環境」を作成するための、より特殊ないくつかの ガイドラインがあります。 Pylons プロジェクトウェブサイト上の Pyramid アドオン あるいは 開発環境 のセクションにあなたのアドオンを含めたいと考えるなら、これらのガイドラインを 厳守すべきです。

「アドオン」とは Pyramid 自体に依存するパッケージです。あなたの アドオンが Pyramid に依存しない場合、それはアドオンではありません (それは単なるライブラリです)。そして、それはアドオンページには掲載 されないでしょう。

異なるパッケージの種類が存在します。それは単なるアドオンではなく、通常 「Paster テンプレート」の形で実現する主張を含んでいます。それは、その 主張の集合を好むユーザの代わりに、ローカルにカスタマイズされた Pyramid アプリケーションをセットアップします。これらは「開発環境」と呼ばれます。

以下では、良いアドオンの作り方と良い開発環境の作り方について話します。

アドオンの投稿

Pyramid は、誰でもアドオンを共有できるリポジトリを提供しています。

コミュニティドキュメント (英語) を参照してください。

良いアドオンの作り方

アドオンパッケージは pyramid_foo のような名前にすべきです。ここで foo はパッケージの機能についての説明です。例えば pyramid_mailer はメールサービスを提供する何かに対する素晴らしい名前 です。希望する名前が既に使われている場合は別の名前を考えてみてください。 例えば pyramid_mailout です。パッケージの機能について1単語で簡潔に 記述できないか、希望する名前が既に使われていて、機能と関係する別名に ついて考えつかない場合は、コード名を使用してください (例えば pyramid_postoffice)。

あなたのパッケージが「設定」機能を提供している場合、設定を行う独自の フレームワークを作成する誘惑にかられるでしょう:

class MyConfigurationExtender(object):
    def __init__(self, config):
        self.config = config

    def doit(self, a, b):
        self.config.somedirective(a, b)

extender = MyConfigurationExtender(config)
extender.doit(1, 2)

そうする代わりに、 http://docs.pylonsproject.jp/projects/pyramid-doc-ja/en/latest/narr/extconfig.html#add-directive で文書化されるように configurator の add_directive メソッドを使用し てください。

def doit(config, a, b):
    config.somedirective(a, b)

config.add_directive('doit', doit)

あなたのアドオンが何らかのデフォルトの振る舞いを提供したい場合、 アドオンの __init__.py の中で includeme メソッドを提供してください。 そうすれば、 config.include('pyramid_foo') はそれを探し出します。 外部ソースからの設定インクルード を参照してください。

良い開発環境の作り方

Pyramid コードベース上に高レベルのフレームワークを作成していて、それが 「テンプレート」コード (paster create -t foo を通してユーザによって 生成されるスケルトンコード) を含む場合、他の「開発環境」パッケージとの 統一性のために、いくつかのガイドラインを以下に提示します。

  • その名前は pyramid_ 接頭辞を付けるべきではありません。例えば、 pyramid_foo の代わりに単に foo と命名すべきです。 pryamid_ 接頭辞は Pyramid に特定の機能を追加するアドオンに対して 使用されるのが適切で、それ自身の「主張」を持った個別のフレームワークの 基礎として単に Pyramid を使用するコードに対してではありません。
  • paster create によって生成されたどんなアプリケーションであっても、 開始するためにその後で paster serve development.ini を実行することが できるべきです。
  • development.ini では、 pyramid_debugtoolbar パッケージが 有効化されているべきです。
  • development.ini とよく似た、しかし pyramid_debugtoolbar を インクルードしない production.ini ファイルが存在しているべきです。
  • production.inidevelopment.ini の両方の [server:main] セクションは、ポート 6543 上で paste.httpserver を開始すべきです:

    [server:main]
    use = egg:Paste#http
    host = 0.0.0.0
    port = 6543
  • development.iniproduction.ini は logging を設定すべきです (既存のいずれかのテンプレートを参照)。
  • paster create によって生成されたアプリケーションで、 paster pshell development.ini を使用して対話型シェルを起動できるべきです。
  • 開始/設定コードは、生成されたテンプレートの主なパッケージの __init__.py の中の main という名の関数に置かれるべきです。 この関数はテンプレートの setup.py の中の paster.app_factory セクション内からリンクされるべきです。次のように:

    entry_points = """\
    [paste.app_factory]
    main = {{package}}:main
    """
    

    これは、ユーザが次のパターン (特に use = egg:{{project}}) を使用 できるようにします:

    [app:{{project}}]
    use = egg:{{project}}
    reload_templates = true
    .. other config ..
  • WSGI ミドルウェアの設定は main 関数内の命令的なコードにインラインで 埋め込まれるべきではありません。代わりに、ミドルウェアは設定ファイル中の [pipeline:main] セクション内で設定されるべきです。例えば:

    [pipeline:main]
    pipeline =
        egg:WebError#evalerror
        tm
        {{project}}