main 関数

Pyramid と Pylons の両方に WSGI アプリケーションを返すトップレベルの 関数があります。 Pyramid の関数は pyramidapp/__init__.py の中の main です。Pylons の関数は pylonsapp/config/middleware.py の中の make_app です。以下は Pyramid の ‘starter’ scaffold によって生成さ れた main 関数です:

from pyramid.config import Configurator

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(settings=settings)
    config.add_static_view('static', 'static', cache_max_age=3600)
    config.add_route('home', '/')
    config.scan()
    return config.make_wsgi_app()

Pyramid は Pylons に比べると決まりきった (boilerplate) コードがより少な くなります。そのため main 関数は Pylons の middleware.py, environment.py, そして routing.py モジュールの内容を含んでいます。 Pyramid の設定コードは、デフォルトアプリケーションではたった 5 行の長さ があります。一方 Pylons では 35 行です。

関数本体のほとんどは Configurator (config) を扱います。 Configurator は アプリケーションオブジェクトではありません; アプリケーションをインスタンス 化するためのヘルパーです。コンストラクタ (6行目) に設定を辞書として渡し、 route などをセットアップするために様々なメソッドを呼び出し、アプリケーション を得るために最後に config.make_wsgi_app() を呼び出します。main 関数 はそれを返します。そのアプリケーションは pyramid.router.Router の インスタンスです (Pylons アプリケーションは PylonsApp のサブクラスの インスタンスです)。

dotted Python name と asset specification

いくつかの config メソッドは、オブジェクト (例えばモジュールや callable) またはオブジェクトを指定する文字列のいずれかを受け付けします。 後者は dotted Python name と呼ばれます。それはモジュールの絶対名または モジュール中のトップレベルのオブジェクトを指定するドットで区切られた 文字列です: module, package.module, package.subpackage.module.attribute 。文字列名を渡すことで、メソッド に渡すためだけにオブジェクトをインポートしないで済むようになります。

文字列がドットで始まる場合、それはある親パッケージに対して相対的になります。 したがって、 mypyramiapp/__init__.py に定義されたこの main 関数では、親パッケージは mypyramidapp です。したがって、 名前 ”.views” は mypyramidapp/views.py を指します (注: 場合によっては、 Pyramid が親パッケージを何と考えるかを推測することは tricky です)。

これに密接に関係しているのが static asset specification です。それは、 Python パッケージ内部の非 Python ファイルまたはディレクトリに名前を付けます。 コロンは非 Python サブパスとパッケージ名を分離します: “myapp:templates/mytemplate.pt”, “myapp:static”, “myapp:assets/subdir1” 。最初の部分とコロンを取り除いた場合 (例えば “templates/mytemplate.pt”) それは現在のパッケージからの相対になります。

モジュールと属性の間にコロンを使う別の構文が存在します: “package.module:attribute” 。この使用法は推奨されません; それは Setuptools のリソース構文との互換性のために存在します。

Configurator メソッド

Configurator はアプリケーションをカスタマイズするためのメソッドを複数持っ ています。下記は、Pylons 風のアプリケーションで最も一般的に使用されるもの を、どれくらい広く使用されるかによって順番に示したものです。メソッドの 完全なリストは Pyramid の Configurator API にあります。

add_route(...)

URL ディスパッチのための route を登録します。

add_view(...)

ビューを登録します。ビューは Pylons のコントローラアクションと同等です。

scan(...)

ビューとそれ以外のいくつかを登録するためのラッパー。ビューの章で議論 されています。

add_static_view(...)

静的ファイルのディレクトリを公開する特殊なビューを追加します。これは Pylons の public ディレクトリと多少類似しています。しかし警告のために 静的ファイルの章を見てください。

include(callable, route_prefix=None)

関数が設定をさらにカスタマイズすることを可能にします。これは Pyramid において非常に一般的になった wide-open インタフェースです。 それには 3 つの主なユースケースがあります:

• 関連するコードをグループ化する; 例えば独立したモジュールで route を定義すること。

• サードパーティアドオンの初期化。多くのアドオンが、初期化ステップを すべて行なう include 関数を提供しています。

• URL プレフィックスでサブアプリケーションをマウントする。サブ アプリケーションは、協調して動作する route 、ビュー、テンプレートを 単にまとめたものです。アプリケーションを論理的な単位に分割するため にこれを使用することができます。あるいは、いくつかのアプリケーション の中で使用することができる汎用的なサブアプリケーションを書いたり、 サードパーティのサブアプリケーションをマウントすることができます。

アドオンまたはサブアプリケーションがオプションを持っている場合、典型 的にはあるプレフィックスの付いた設定を探し、文字列を適切な型に変換す ることによってそれらのオプションは設定から読まれるでしょう。例えば、 セッションマネージャは “session.” あるいは “thesessionmanager.” “session.type” のような文字列で始まるキーを探すことがあり得ます。 アドオンがどのようなプレフィックスを使用するか、そしてどのような オプションを認識するかを確認するために、アドオンのドキュメンテーション を調べてください。

callable 引数は、関数、モジュール、または dotted Python name です。 モジュールの場合、モジュールは呼び出される includeme 関数を含んで いなければなりません。下記は等価です:

config.include("pyramid_beaker")

import pyramid_beaker
config.include(pyramid_beaker)

import pyramid_beaker
config.include(pyramid_beaker.includeme)

route_prefix が指定された場合、それはサブコンフィギュレータの add_route メソッドによって生成される任意の URL に前置される文字列 になります。注意: ルート名はメインアプリケーションとすべてのサブ アプリケーションを横断してユニークでなければなりません。また、 route_prefix は名前については関与しません。したがって、ルートに “subapp1.route1” あるいは “subapp1_route1” のようなものを指定 すると良いでしょう。

add_subscriber(subscriber, iface=None)

Pyramid のイベントループに、リクエストの処理方法をカスタマイズする ためにコールバックを挿入します。 Renderers 章にはその使用例があります。

add_renderer(name, factory)

カスタムレンダラーを追加します。 Renderers 章に例があります。

set_authentication_policy, set_authorization_policy, set_default_permission

Pyramid の組み込みの認可メカニズムを設定します。

その他の時々使われるメソッド: add_notfound_view, add_exception_view, set_request_factory, add_tween, override_asset (テーマのために使用) 。アドオンは config.add_directive を呼ぶことにより追加の config メソッドを定義す ることができます。

route 引数

config.add_route は多くのキーワード引数を受け付けます。それらは論理的に 述語引数 と 非述語引数 に分類されます。述語引数は、 route が現在の リクエストとマッチするかどうかを判断します。 route が選ばれるためにはすべて の述語が成功しなければなりません。非述語引数は route マッチには影響しません。

name

[非述語引数] 最初の位置引数; 必須です。これは route のユニークな 名前でなければなりません。 name はビューを登録する場合、あるいは URL を生成する場合に route を識別するために使用されます。

pattern

[述語引数] 第2の位置引数; 必須です。これは任意の “{variable}” プレースホルダを含む URL パスです。例えば “/articles/{id}” や “/abc/{filename}.html” などです。先頭のスラッシュはオプションです。 プレースホルダはデフォルトでスラッシュまでのすべての文字とマッチします。 しかし、正規表現を指定することで、それより短く (例えば数値変数に対 して “{variable:\d+}”) あるいはそれより長く (スラッシュを含めて URL の残り全体とマッチする “{variable:.*}”) マッチさせることが できます。プレースホルダによってマッチした部分文字列は、ビューの中では request.matchdict として利用可能になります。

ワイルドカード構文 “*varname” は URL の残りとマッチし、単一の文字列 の代わりにセグメントのタプルとして matchdict にそれを格納します。 つまり、パターン “/foo/{action}/*fizzle” は URL “/foo/edit/a/1” とマッチし、 matchdict {'action': u'edit', 'fizzle': (u'a', u'1')} を生成します。

2つの特別なワイルドカード “*traverse” と “*subpath” が存在します。 これらは URL の残りに対してトラバーサルを行う高度な場合に使用されます。

XXX バックスラッシュを含む正規表現 (\d) に raw 文字列構文を使用するべき?

request_method

[述語引数] HTTP メソッド: “GET”, “POST”, “HEAD”, “DELETE”, “PUT” 。 このタイプのリクエストだけが route とマッチするでしょう。

request_param

[述語引数] 値が “=” を含んでいない場合 (例えば “q”)、リクエストには 指定されたパラメータ (GET または POST 変数) が存在しなければなりません。 値が “=” を含んでいる場合 (例えば “name=value”)、パラメータはさらに 指定された値を持っていなければなりません。

POST によって他の HTTP メソッドにトンネルする場合、これは特に有用です。 ウェブブラウザはフォームから PUT や DELETE メソッドを送信することが できません。そのため、 POST を使用して、パラメータ _method="PUT" をセットすることは慣習的です。フレームワークまたはアプリケーションは、 “_method” パラメータを見て別の HTTP メソッドがリクエストされたように 装います。Pyramid では request_param="_method=PUT でこれをする ことができます。

xhr

[述語引数] リクエストに “X-Requested-With” ヘッダーがなければならない 場合 True にします。いくつかの Javascript ライブラリ (JQuery や Prototype など) は、 AJAX リクエストとユーザーが起動したブラウザ リクエストを区別するために、AJAX リクエストの中でこのヘッダーをセット します。

custom_predicates

[述語引数] route がリクエストとマッチするかどうかを判断するために 呼ばれる callable のシーケンス。他の述語引数では必要とすることが 行えない場合はこの機能を使用してください。 callable がすべて True を 返す場合のみ、そのリクエストは route とマッチします。個々の callable は 2 つの引数 info および request を受け取ります。 request は現在のリクエストです。 info は下記を含んでいる 辞書です:

info["match"]  =>  現在の route 用のマッチ辞書
info["route"].name  =>  現在の route の名前
info["route"].pattern  =>  現在の route の URL パターン

マッチ辞書を修正して、ビューがどのようにそれを見るかに影響を与える ことができます。例えば、ID に基づいてモデルオブジェクトを検索して、 オブジェクトを異なるキーの下にマッチ辞書に入れることができます。 レコードがモデルの中に見つからない場合、 False を返すことができます。

利用可能な他の引数: accept, factory, header, path_info, traverse 。