Pyramid 1.4 の新機能¶
この文書では Pyramid バージョン 1.4 をその前身である Pyramid 1.3 を比較した場合の新機能について説明します。また、 2 つの バージョン間の後方非互換性と Pyramid 1.4 に加えられた deprecation (廃止予定) に加えて、ソフトウェア依存関係の変更とドキュメンテーションの 顕著な追加分をドキュメント化します。
メジャー機能追加¶
Pyramid 1.4 の主な追加機能は以下の通りです。
サードパーティ述語¶
ビューの作成者は、サードパーティのカスタムビュー、 route 、 subscriber 述語を
pyramid.config.Configurator.add_view_predicate()
,pyramid.config.Configurator.add_route_predicate()
,pyramid.config.Configurator.add_subscriber_predicate()
を用いて 追加して使うことができるようになりました。そのため、例えば:config.add_view_predicate('abc', my.package.ABCPredicate)
このようにすると、その述語を構成したアプリケーション内でビューの作成者が 以下のようにすることが可能になります:
@view_config(abc=1)
同様の機能は
pyramid.config.Configurator.add_route()
およびpyramid.config.Configurator.add_subscriber()
として存在します。 詳細は Adding A Third Party View, Route, or Subscriber Predicate を参照してください。
容易なカスタム JSON シリアライズ¶
- ビューがカスタムオブジェクトを返すことができるようになりました。
カスタムオブジェクトは、そのオブジェクトのクラスに
__json__
メソッド を定義することにより JSON レンダラーによって JSON にシリアライズされます。 このメソッドはjson.dumps
によってネイティブにシリアライズできる値 (int, list, 辞書, 文字列など) を返さなければなりません。 詳細は カスタムオブジェクトのシリアライズ を参照してください。 返されたオブジェクトに__json__
メソッドを追加することができない場合、 さらに JSON レンダラーは未知のオブジェクトを JSON シリアライズに変換 するためのカスタム型アダプタを定義することができるようになりました。
Mako と Chameleon の部分的なテンプレートレンダリング¶
- Mako レンダラーが asset spec 中での def 名の使用をサポートするように
なりました。 asset spec 中に def 名がある場合、システムはテンプレート
全体をレンダリングする代わりに、テンプレート内の def で指定された
テンプレートをレンダリングします。 def を指定する asset spec の例は
package:path/to/template#defname.mako
です。これは、テンプレート 全体をレンダリングする代わりにtemplate.mako
テンプレートの内部のdefname
という名前の def をレンダリングします。 ビューから('defname', {})
形式でタプルを返す古い方法は、後方互換性 のためにサポートされます。
- Chameleon ZPT レンダラーが asset spec 中でのマクロ名の使用をサポート
するようになりました。 asset spec 中にマクロ名がある場合、システム
はテンプレート全体をレンダリングする代わりに
define-macro
として リストされたマクロをレンダリングして結果を返します。 asset spec の例:package:path/to/template#macroname.pt
。 これは、テンプレート全体の代わりにtemplate.pt
テンプレート中でmacroname
として定義されたマクロをレンダリングします。
サブリクエストサポート¶
- 開発者は
pyramid.request.Request.invoke_subrequest()
API を使用 してサブリクエストを起動することができます。これによって、開発者は あるビュー callable の内部からサブリクエストを呼び出すことによって 別のビュー callable からのレスポンスを得ることができるようになります。 詳細は Invoking a Subrequest を参照してください。
マイナー機能追加¶
pyramid.authentication.AuthTktAuthenticationPolicy
がsha512
のようなより新しいハッシュアルゴリズムをサポートするために 更新されました。既存のアプリケーションは、可能な場合にはデフォルトの md5 ハッシュに対する改善されたセキュリティに更新することを検討すべきです。
pyramid.config.Configurator.add_directive()
は、 partial や__call__
を実装したオブジェクトのように__name__
および__doc__
属性を持たない任意の callable を受け取るようになりました。 https://github.com/Pylons/pyramid/issues/621 と https://github.com/Pylons/pyramid/pull/647 を参照してください。
- このリリースから、
request_method
ビュー/route 述語が使われている場合にGET
が指定されたらHEAD
も指定されたものとみなすようになりました。 例えば、@view_config(request_method='GET')
を使うことは@view_config(request_method=('GET', 'HEAD'))
を使うことと等価です。@view_config(request_method=('GET', 'POST')
を使うことは@view_config(request_method=('GET', 'HEAD', 'POST')
を使うことと等価です。 これは HEAD が body を省略した GET の変種であるためです。また、 WebOb には HEAD が使用された場合に空の body を返すための特別なサポートがあります。
- 任意の callable によるリクエストオブジェクトの拡張をサポートするために
pyramid.config.Configurator.add_request_method()
が導入されました。 このメソッドは、プロパティだけでなくメソッドもサポートすることで、 今では deprecated とドキュメント化されたpyramid.config.Configurator.set_request_property()
を拡張します。 さらにこのメソッドは、リクエスト生成時にset_request_property()
と比べて より少ないコードを実行します。
- 静的ビュー機構は
pyramid.httpexceptions.HTTPNotFound
およびpyramid.httpexceptions.HTTPMovedPermanently
例外を戻り値として 返すのではなく例外として投げるようになりました。そのため、これらの例外を notfound ビュー (または他の例外ビュー) によって捕捉することができます。
- 述語不一致例外が起きた場合 (述語が働かないために与えられたリクエストに 一致するビューがない場合に見られる) 、一致しなかった述語に関するテキストの 説明が例外に含まれるようになりました。
pyramid.config.Configurator.add_permission()
ディレクティブ メソッドが Configurator に追加されました。このディレクティブは、 独立した内省可能なパーミッションを Pyramid 内省システムに登録します。 Pyramid 上に構築されたフレームワークは、したがって実行中のシステムで サポートされているパーミッションの完全なリストを構築するためにpermissions
introspectable カテゴリーデータを使用できます。 このメソッドが追加される以前にも、pyramid.config.Configurator.add_view()
呼び出しで パーミッションに名前を付けることの副作用として この introspectable カテゴリーにパーミッションが登録されていました。 このメソッドは、単に関連するビューと共にパーミッションに名前を付ける ことなくpermissions
introspectable カテゴリーにパーミッションを 入れられるようにします。これはadd_permission
の使用の一例です:config = Configurator() config.add_permission('view')
pyramid.session.UnencryptedCookieSessionFactoryConfig()
関数が、 セッションの直列化の方法 (デフォルトでは、 HMAC+pickle によって行われます) に影響を与えるために使用できるsigned_serialize
およびsigned_deserialize
フックを受け取るようになりました。
pyramid.testing.DummyRequest
が、pyramid.util.InstancePropertyMixin
クラスによって提供されるset_property
のようなメソッドをサポートするようになりました。
pyramid.config.Configurator.add_request_method()
やpyramid.config.Configurator.set_request_property()
によって追加 されたリクエストプロパティおよびメソッドが、 tween でも利用可能になり ました。
pyramid.config.Configurator.add_request_method()
やpyramid.config.Configurator.set_request_property()
によって追加 されたリクエストプロパティおよびメソッドが、pyramid.paster.bootstrap()
から返されたリクエストオブジェクトでも 利用可能になりました。
pyramid.paster.bootstrap()
中に、提供されたリクエストにまだ コンテキストがセットされていない場合、環境リクエストのrequest.context
が root オブジェクトとなるようになりました。
pyramid.decorator.reify
が API になり、 API ドキュメンテーション に追加されました。
pyramid.testing.testConfig()
コンテキストマネージャーが追加されました。 これは、例えばwith testing.testConfig(...):
のようにして、 テストでコンフィギュレータを生成するために使用することができます。
- 利便性のための
pyramid.session.check_csrf_token()
新 API 関数が 追加されました。
check_csrf
ビュー述語が追加されました。これにより、例えばconfig.add_view(someview, check_csrf=True)
ができるようになります。 この述語がチェックされた時に、request.params
中のcsrf_token
の 値がリクエストのセッション中の csrf トークンと一致すればビューは実行を 許可されます。そうでなければ実行は許可されません。
- 命令的に定義されたテーブルが動作するように、
Base.metadata.bind = engine
がalchemy
scaffold に追加されました。
- scaffold の
.ini
ファイルにドキュメンテーションへの参照を含む コメントが追加されました。
request_param
ビュー/route 述語に複数の値をシーケンスとして指定 することが可能になりました。以前は、単一の文字列値だけが許されていました。 https://github.com/Pylons/pyramid/pull/705 を見てください。
pyramid.authentication.BasicAuthAuthenticationPolicy
に HTTP BASIC 認証ポリシーが追加されました。
pyramid.config.Configurator.testing_securitypolicy()
メソッドが、 生成したポリシーオブジェクトを返すようになりました。
pyramid.config.testing_securitypolicy()
によって生成された DummySecurityPolicy が、forget
メソッドが呼ばれた場合にそのポリシーのforgotten
値を (値True
に) 設定するようになりました 。
pyramid.config.testing_securitypolicy()
によって生成された DummySecurityPolicy が、そのポリシーのremembered
値を設定する ようになりました。それはremember
メソッドが呼ばれたときに渡されるprincipal
引数の値です。
- 新しい
physical_path
ビュー述語。もし指定された場合にはその値は文字列 またはタプルで、それらはこの述語がマッチする、トラバーサルによって見つかった コンテキストの物理的なトラバーサルパスを表わします。例えば:physical_path='/'
やphysical_path='/a/b/c'
やphysical_path=('', 'a', 'b', 'c')
です。これは、あるオブジェクトが トラバーサルされる時に潜在的に常にあるビューを表示したいけれども、 それがどんな種類のオブジェクトになるかは分からず、したがってcontext
述語を使用することができない場合に便利です。
effective_principals
route/ビュー述語が追加されました。
pyramid.authentication
に含まれる内蔵の認可ポリシーのどれかが 使用されている場合に、pyramid.security.authenticated_userid()
から返された userid 、またはpyramid.security.effective_principals()
から返された principals リストに含まれる userid は、文字列system.Everyone
またはsystem.Authenticated
のどちらかになることはできません。 これらの 2 つの文字列は Pyramid が内部で使用するために予約されます。 また、それらはもはや有効な userid として認められません。
pyramid.view.view_config
に_depth
引数を渡すことができる ようになりました。それは、他のソフトウェアが view_config によく似た カスタムデコレータを提供したい場合に、デコレータの制限された合成再使用 を可能にします。
pyramid.config.Configurator.add_view()
にデコレータの iterable を渡せるようになりました。これによって、ユーザ自身でデコレータを組み合わせる ことを必要とせずに複数のデコレータによってビューをラップできるようになります。
pyramid.security.view_execution_permitted()
は、以前はビューを 見つけられない場合に True を返していました。存在しないビューが実行 を許可されると主張しても無意味なので、その場合はTypeError
例外を 送出するようになりました。 https://github.com/Pylons/pyramid/issues/299 を見てください。
- ほとんどの場合にビューから
pyramid.response.Response
オブジェクト が返されることを見越した、実行速度の小さな改善。ビューによって返された オブジェクトのクラスがこのクラスである場合に、一部のコードがショートカット されます。同様の小さな最適化がpyramid.request.Request.is_response()
に対して行われました。
- すべての
p*
コマンド (pserve
,pshell
,pviews
など) でa=1 b=2
形式で可変引数を使用することができるようになりました。 それによりパラメータ化された.ini
ファイル中の値を埋めることが できます (例えばpshell etc/development.ini http_port=8080
)。
- ユーザがサブスクライバ callable に対する未使用の引数を無視したり、
イベントサブスクライバとサブスクライバ述語の関係を標準化することが
できるように、複数のインタフェースを伴う通知に対して登録されたとしても
サブスクライバとサブスクライバ述語の両方が単一の
event
引数だけを 受け取ることができるようになりました。
後方非互換性¶
- Pyramid ルーターは、リクエストの WSGI 環境辞書に値
bfg.routes.route
やbfg.routes.matchdict
を追加しなくなりました。 これらの値はrepoze.bfg
1.0 (事実上マイナーリリース 7 つ前) で deprecated とドキュメント化されています。 あなたのコードがこれらの値に依存している場合は、代わりにrequest.matched_route
とrequest.matchdict
を使用してください。
pyramid.traversal.ResourceTreeTraverser.__call__
(別名ModelGraphTraverser.__call__
) に environ 辞書を直接渡すことは できなくなりました。代わりにリクエストオブジェクトを渡す必要があります。 リクエストの代わりに environ を渡すと、 Pyramid 1.1 からは deprecation 警告が発生していました。
- リクエストファクトリとして
webob.request.LegacyRequest
を使用している 場合、 Pyramid は正常に動作しなくなりました。 LegacyRequest クラスの インスタンスには文字列を返すrequest.path_info
があり、Pyramid の このリリースはrequest.path_info
が無条件でユニコードであることを 仮定しています。
pyramid.chameleon_zpt
とpyramid.chameleon_text
からget_renderer
,get_template
,render_template
,render_template_to_response
という名前の関数が削除されました。 これらは Pyramid 1.0 からインポート時に deprecation 警告が出ていました。 これらの関数の代わりに、pyramid.renderers.get_renderer()
,pyramid.renderers.get_renderer().implementation()
,pyramid.renderers.render()
,pyramid.renderers.render_to_response()
をそれぞれ使用してください。
pyramid.configuration
モジュールが削除されました。このモジュールは Pyramid 1.0 から deprecated になり、使用すると deprecation 警告が表示 されていました。代わりにpyramid.config
を使用してください。
pyramid.paster.PyramidTemplate
API が削除されました。それは Pyramid 1.1 から deprecated になり、インポート時に警告が出ていました。 あなたのコードがこれに依存している場合、代わりにpyramid.scaffolds.PyramidTemplate
をインポートするように コードを修正してください。
pyramid.settings.get_settings()
API が削除されました。この API は Pyramid 1.0 から deprecation 警告が表示されていました。あなたのコードが この API に依存している場合は、代わりにpyramid.threadlocal.get_current_registry().settings
を使用するか、 リクエストからアクセス可能なレジストリのsettings
属性 (request.registry.settings
) を使用してください。
pyramid.testing
モジュールから以下の API が削除されました。 これらは Pyramid 1.0 から deprecation 警告が表示されていました:registerDummySecurityPolicy
, 代わりにpyramid.config.Configurator.testing_securitypolicy()
を使ってください。
registerResources
(別名registerModels
), 代わりにpyramid.config.Configurator.testing_resources()
を使ってください。
registerEventListener
, 代わりにpyramid.config.Configurator.testing_add_subscriber()
を使ってください。
registerTemplateRenderer
(別名registerDummyRenderer
), 代わりにpyramid.config.Configurator.testing_add_template()
を使ってください。
registerView
, 代わりにpyramid.config.Configurator.add_view()
を使ってください。
registerUtility
, 代わりにpyramid.config.Configurator.registry.registerUtility()
を使ってください。
registerAdapter
, 代わりにpyramid.config.Configurator.registry.registerAdapter()
を使ってください。
registerSubscriber
, 代わりにpyramid.config.Configurator.add_subscriber()
を使ってください。
registerRoute
, 代わりにpyramid.config.Configurator.add_route()
を使ってください。
registerSettings
, 代わりにpyramid.config.Configurator.add_settings()
を使ってください。
- Pyramid 1.3 とそれ以前には、ビューによって返された Response オブジェクトの
__call__
メソッドがすべての finished コールバックが実行される前に 起動されていました。このリリース以降、Response オブジェクトの__call__
メソッドはfinished コールバックが実行された後に起動されます。 これはpyramid.request.Request.invoke_subrequest()
機能をサポート するためです。
Deprecations¶
pyramid.config.Configurator.set_request_property()
ディレクティブ が deprecated とドキュメント化されました。このメソッドは今でも使えますが、 より機能豊富なpyramid.config.Configurator.add_request_method()
を 代わりに使うことが推奨されます (それは同じ能力をすべて持っていて、さらに リクエストオブジェクトをメソッドによって拡張することができます)。
- アプリケーションが明示的に
hashalg
引数を渡さずにpyramid.authentication.AuthTktAuthenticationPolicy
ポリシー を使用した場合、このポリシーは deprecation 警告を発するでしょう。これは、 デフォルトが理論上は衝突攻撃を受けると考えられる “md5” だからです。 本当に “md5” を望むなら、警告を取り除くためにそれを明示的に指定しなければ なりません。
ドキュメントの強化¶
- Upgrading Pyramid の章が narrative ドキュメンテーションに追加 されました。この章は、 Pyramid API の deprecation と削除に対処する方法、 テストを実行している間やサーバーを起動している間に Pyramid によって 生成された deprecation 警告を表示する方法について記述します。
- Invoking a Subrequest の章が narrative ドキュメンテーションに追加 されました。
pyramid.authentication.AuthTktAuthenticationPolicy
を使用する すべてのチュートリアルはhashalg
引数として明示的にsha512
を渡すようになりました。
- narrative および API ドキュメントに対して多くの整理と改善が行われました。
依存関係の変更¶
- Pyramid は WebOb 1.2b3+ を要求するようになりました(以前の Pyramid
リリースは、 1.2dev+ に依存していました) 。これは、
request.path_info
をテキストとして返す WebOb のバージョンを確実に 得るためです。