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 のバージョンを確実に 得るためです。