pyramid.config

class Configurator(registry=None, package=None, settings=None, root_factory=None, security_policy=None, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, response_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, autocommit=False, exceptionresponse_view=<function default_exceptionresponse_view>, route_prefix=None, introspection=True, root_package=None)[源代码]

配置器用于配置 Pyramid application registry .

通过使用上下文管理器自动处理调用，可以管理配置器生命周期。 pyramid.config.Configurator.begin() 和 pyramid.config.Configurator.end() 以及 pyramid.config.Configurator.commit() .

with Configurator(settings=settings) as config:
    config.add_route('home', '/')
    app = config.make_wsgi_app()

如果 registry 论点不是 None ，它必须是 pyramid.registry.Registry 表示要配置的注册表的类。如果 registry 是 None ，配置程序将创建一个 pyramid.registry.Registry 实例本身；它还将执行一些在其他情况下不会执行的默认配置。在构造之后，可以使用配置器向注册表添加进一步的配置。

警告

如果 registry 如果为上述类实例赋值，则忽略所有其他构造函数参数，但 package .

如果 package 参数已传递，它必须是对python的引用 package （例如） sys.modules['thepackage'] 或A dotted Python name 一样。此值用作基础，以转换传递给各种配置方法的相对路径，例如接受 renderer 变为绝对路径。如果 None 如果传递了（默认值），则假定包是python包，其中 呼叫者 的 Configurator 建造师的生命。

如果 root_package 传递时，它将通过配置层次结构传播，作为包含包相对于主包的包定位资源的一种方法。 Configurator 创建。如果 None 通过（默认），则 root_package 将从 package 参数。这个 package 属性始终指向使用时包含的包 include() 而 root_package 不会改变。

如果 settings 参数已传递，它应该是表示 deployment settings 对于此应用程序。以后可以使用 pyramid.registry.Registry.settings 属性（AKA） request.registry.settings ）

如果 root_factory 参数已传递，它应该是表示默认值的对象 root factory 对于您的申请或 dotted Python name 一样。如果是 None 将使用默认根工厂。

如果 security_policy 传递，则它应该是 security policy 或者是 dotted Python name 都是一样的。

如果 authentication_policy 是通过的，它应该是 authentication policy 或A dotted Python name 一样。

如果 authorization_policy 是通过的，它应该是 authorization policy 或A dotted Python name 一样。

备注

A ConfigurationError 在未提供身份验证策略的情况下提供授权策略时将引发（授权需要身份验证）。

如果 renderers 是 None （默认值），默认设置为 renderer 使用工厂。否则，它应该是表示一组渲染器工厂的元组列表，这些工厂应该配置到此应用程序中，并且每个元组表示一组应该传递给 pyramid.config.Configurator.add_renderer() .

如果 debug_logger 未传递，将使用记录到记录器的默认调试记录器（记录器名称将是 呼叫者 配置器）。如果它被传递，则它应该是 logging.Logger （PEP 282）标准库类或python记录器名称。调试记录器由使用 Pyramid 记录警告和授权调试信息。

如果 locale_negotiator 通过了，应该是 locale negotiator 实施或 dotted Python name 一样。见 使用自定义区域设置协商器 .

如果 request_factory 通过了，应该是 request factory 实施或 dotted Python name 一样。见 更改请求工厂 . 默认情况下是 None ，这意味着使用默认的请求工厂。

如果 response_factory 通过了，应该是 response factory 实施或 dotted Python name 一样。见 更改响应工厂 . 默认情况下是 None ，这意味着使用默认响应工厂。

如果 default_permission 通过了，应该是 permission 要用作对该配置器执行的所有视图配置注册的默认权限的字符串。权限字符串的示例：“view”。添加默认权限会使您不必使用显式权限保护每个视图配置，除非应用程序策略要求对特定视图进行某些异常。默认情况下， default_permission 是 None ，这意味着不显式声明权限的视图配置将始终由完全匿名的用户执行（任何有效的授权策略都将被忽略）。

参见

也见 设置默认权限 .

如果 session_factory 是传递的，它应该是实现 session factory 接口。如果传递了非默认值，则 session_factory 将用于在以下情况下创建会话对象： request.session 被访问。请注意，通过调用 pyramid.config.Configurator.set_session_factory() . 默认情况下，此参数为 None ，表示不会配置会话工厂（因此访问 request.session 将引发错误），除非 set_session_factory 稍后在配置过程中调用。

如果 autocommit 是 True ，在配置器上调用的每个方法都将导致立即操作，并且不会使用配置冲突检测。如果 autocommit 是 False ，配置器的大多数方法都将其操作推迟到 pyramid.config.Configurator.commit() 被称为。什么时候？ pyramid.config.Configurator.commit() 调用时，将检查被调用方法所隐含的操作是否存在配置冲突，除非 autocommit 是 True . 如果检测到冲突，则 ConfigurationConflictError 将被提升。打电话 pyramid.config.Configurator.make_wsgi_app() 总是意味着最后的承诺。

如果 default_view_mapper 已通过，将用作默认值 view mapper 工厂查看未另行指定的视图配置（请参见 pyramid.interfaces.IViewMapperFactory ）如果 default_view_mapper 未传递，将使用超默认视图映射器。

如果 exceptionresponse_view 通过了，必须是 view callable 或 None . 如果它是可调用的视图，则当 exception response 提高了。如果 exceptionresponse_view 是 None ，不会注册任何异常响应视图，所有引发的异常响应都将冒泡到Pyramid的调用方。默认情况下， pyramid.httpexceptions.default_exceptionresponse_view 函数用作 exceptionresponse_view .

如果 route_prefix 已通过，所有路由都添加了 pyramid.config.Configurator.add_route() 将为其模式预先指定路径。

如果 introspection 传递时，它必须是布尔值。如果是 True ，操作期间的自省值将保留，以供调试工具栏等工具使用。如果是 False ，将忽略注册提供的自省值。默认情况下，它是 True .

在 1.1 版本加入: 这个 exceptionresponse_view 参数。

在 1.2 版本加入: 这个 route_prefix 参数。

在 1.3 版本加入: 这个 introspection 参数。

在 1.6 版本加入: 这个 root_package 参数。这个 response_factory 参数。

在 1.9 版本加入: 使用配置器作为上下文管理器的能力 with -语句使threadlocal配置可用于隐式提交的进一步配置。

Controlling Configuration State

commit()

提交任何挂起的配置操作。如果在挂起的配置操作中检测到配置冲突，此方法将引发 ConfigurationConflictError ；在该错误的追溯过程中，将提供有关冲突源的信息，通常包括配置冲突原因的文件名和行号。

警告

在手动调用之前，您应该仔细考虑 commit() . 尤其是不能作为任何可重用配置方法的一部分。通常情况下，它只应由应用程序作者在配置结束时完成，以便覆盖插件的某些方面。

begin(request=<object object>)[源代码]

指示应用程序或测试配置已开始。这将推送包含 application registry 隐含的 registry 此配置器的属性和 request 隐含的 request 关于 thread local 堆栈由不同的 pyramid.threadlocal API函数。

如果 request 未指定，并且配置程序拥有的注册表已作为当前线程本地注册表推送，则此方法将保持当前线程本地请求不变。

在 1.8 版本发生变更: 如果当前的ThreadLocal注册表保持不变，则传播当前的ThreadLocal请求。

end()[源代码]

指示应用程序或测试配置已结束。这将弹出推送到 thread local 堆栈（通常由 begin 方法）并返回该值。

include(callable, route_prefix=None)[源代码]

包括一个可调用的配置，以支持必需的应用程序扩展性。

警告

在版本中 Pyramid 在1.2之前，此功能被接受 *callables ，但这已更改为仅支持单个可调用。

配置可调用应为接受名为 config ，它将是 Configurator . 但是，请注意，它不会是调用此方法的同一个配置器实例。由于调用可调用文件而运行的代码应该在传递给它的配置程序上调用方法，该配置程序会添加配置状态。可调用文件的返回值将被忽略。

允许通过 callable 此方法的参数：任何可调用的python对象或 dotted Python name 它解析为可调用的python对象。它也可能是一条 Python module ，在这种情况下，将搜索模块以查找名为 includeme ，将被视为可调用的配置。

例如，如果 includeme 下面的函数存在于名为 myapp.myconfig ：

1# myapp.myconfig module
2
3def my_view(request):
4    from pyramid.response import Response
5    return Response('OK')
6
7def includeme(config):
8    config.add_view(my_view)

您可能会导致它包含在Pyramid应用程序中，如下所示：

1from pyramid.config import Configurator
2
3def main(global_config, **settings):
4    config = Configurator()
5    config.include('myapp.myconfig.includeme')

因为函数是命名的 includeme ，函数名也可以从点式名称引用中省略：

1from pyramid.config import Configurator
2
3def main(global_config, **settings):
4    config = Configurator()
5    config.include('myapp.myconfig')

如果包含的可调用项通过使用相同的配置参数注册某个内容而导致配置冲突，则包含的配置语句将被本地配置语句覆盖。

如果 route_prefix ，则它必须是字符串，并且与使用 pyramid.config.Configurator.route_prefix_context() 。任何呼叫 pyramid.config.Configurator.add_route() 在包含的可调用对象中，它们的模式将具有前缀 route_prefix 。这可用于帮助将一组路由挂载到与包含的可调用对象的作者预期的位置不同的位置，同时仍保持相同的路由名称。例如：

1from pyramid.config import Configurator
2
3def included(config):
4    config.add_route('show_users', '/show')
5
6def main(global_config, **settings):
7    config = Configurator()
8    config.include(included, route_prefix='/users')

在上述配置中， show_users 路线将有一个有效的路线模式 /users/show ，而不是 /show 因为 route_prefix 参数将在模式前面。

在 1.2 版本加入: 这个 route_prefix 参数。

在 1.9 版本发生变更: 包含的函数被包装为调用 pyramid.config.Configurator.begin() 和 pyramid.config.Configurator.end() 在执行过程中。

make_wsgi_app()[源代码]

提交任何挂起的配置语句，发送 pyramid.events.ApplicationCreated 事件，将此配置的注册表添加到 pyramid.config.global_registries 并返回一个 Pyramid 表示已提交配置状态的wsgi应用程序。

route_prefix_context(route_prefix)

将此配置器与 route prefix 临时设置。

当上下文退出时， route_prefix 重置为原始。

route_prefix 字符串是否适合用作路由前缀，或者 None .

示例用法：

config = Configurator()
with config.route_prefix_context('foo'):
    config.add_route('bar', '/bar')

在 1.10 版本加入.

scan(package=None, categories=('pyramid',), onerror=None, ignore=None, **kw)[源代码]

扫描python包及其任何子包中标记有 configuration decoration 如 pyramid.view.view_config . 找到的任何装饰对象都将影响当前配置状态。

这个 package 参数应为python package 或模块对象（或 dotted Python name 指这样的一个包或模块）。如果 package 是 None ，的包 呼叫者 使用。

这个 categories 参数(如果提供)应为 Venusian “扫描类别”，以便在扫描期间使用。通常不需要提供此参数；指定扫描类别是一种非常高级的用法。默认情况下， categories 是 ['pyramid'] 它将仅执行 Pyramid -相关的金星装饰器回调，如来自 pyramid.view.view_config 。请参阅 Venusian 文档，了解有关使用显式类别集限制扫描的详细信息。经过 None 接电话，接电话 all 金星人的装饰师。

这个 onerror 如果提供的话，论点应该是金星人。 onerror 回调函数。OnError函数传递给 venusian.Scanner.scan() 在扫描过程中引发异常时影响错误行为。见 Venusian 有关更多信息的文档 onerror 回调。

这个 ignore 如果提供的话，论点应该是金星人。 ignore 价值。提供一个 ignore 参数允许扫描在扫描期间忽略特定模块、包或全局对象。 ignore 可以是字符串或可调用的，也可以是包含字符串或可调用的列表。最简单的用法 ignore 是通过提供模块或包的点式名称的完整路径来提供模块或包。例如： config.scan(ignore='my.module.subpackage') 会忽略 my.module.subpackage 在扫描期间打包，这将阻止子包及其任何子模块被导入和扫描。见 Venusian 有关 ignore 参数。

表演 scan ，Pyramid创造了一个金星人 Scanner 对象。这个 kw 参数表示要传递给金星人的一组关键字参数 Scanner 对象的构造函数。见 venusian 文件 Scanner 类）获取有关构造函数的更多信息。默认情况下，传递给scanner构造函数的唯一关键字参数是 {{'config':self}} 在哪里？ self 这是配置器对象。这满足了所有内置Pyramid装饰器的需求，但是扩展系统可能需要额外的参数。提供这个参数通常是不必要的；这是一个高级用法。

在 1.1 版本加入: 这个 **kw 参数。

在 1.3 版本加入: 这个 ignore 参数。

在 2.0 版本发生变更: 这个 categories 参数现在默认为 ['pyramid'] 而不是 None 来控制执行哪些装饰器回调。

Adding Routes and Views

add_route(name, pattern=None, factory=None, for_=None, header=None, xhr=None, accept=None, path_info=None, request_method=None, request_param=None, traverse=None, custom_predicates=(), use_global_views=False, path=None, pregenerator=None, static=False, inherit_slash=None, **predicates)

添加 route configuration 设置为当前配置状态。参数至 add_route 分为以下几个部分 谓语 和 non-predicate 类型。 Route predicate 参数缩小了路由与请求匹配的情况；非谓词参数是信息性的。

非谓词参数

名称

路线的名称，例如 myroute . 此属性是必需的。它必须在给定应用程序中所有定义的路由中是唯一的。

工厂

python对象（通常是函数或类）或 dotted Python name 它引用将生成 Pyramid 此路由匹配时的根资源对象。例如， mypackage.resources.MyFactory . 如果未指定此参数，将使用默认根工厂。见 资源树 有关根工厂的更多信息。

导线

如果你想 context 成为其他人 root 对象当此路由匹配时，可以将遍历模式拼写为 traverse 参数。此遍历模式将用作遍历路径：遍历将从该路由所隐含的根对象（全局根或由返回的对象）开始。 factory 与此路由关联）。

的语法 traverse 论点与之相同 pattern . 例如，如果 pattern 提供给 add_route 是 articles/{{article}}/edit 和 traverse 参数提供给 add_route 是 /{{article}} ，当一个请求出现，导致路由匹配时， article 匹配值为 '1' （当请求URI为 /articles/1/edit ）遍历路径将生成为 /1 . 这意味着根对象 __getitem__ 将用名称调用 '1' 在穿越阶段。如果 '1' 对象存在，它将成为 context 请求的。 遍历 有更多关于遍历的信息。

如果遍历路径包含不在 pattern 参数，将发生运行时错误。这个 traverse 模式不应包含不存在于 pattern 参数。

当匹配包含 *traverse 其图案中的余数标记（请参见 使用 *traverse 以路线模式 ）这个 traverse 添加路由的参数允许您将路由模式与任意遍历路径关联，而不使用 *traverse 余数标记；相反，您可以使用其他匹配信息。

请注意 traverse 参数 add_route 当连接到具有 *traverse 图案中的余数标记。

前置发生器

此选项应该是实现 pyramid.interfaces.IRoutePregenerator 接口。一 pregenerator 是由 pyramid.request.Request.route_url() 函数来增加或替换在为路由生成URL时传递的参数。这是一个不经常被应用程序直接使用的特性，它被使用 Pyramid 作为基地。

use_global_views

当请求与此路由匹配，并且视图查找找不到具有 route_name 谓词参数与路由匹配，请尝试使用与上下文、请求和视图名称（但与路由名称谓词不匹配）匹配的视图。

静止的

如果 static 是 True ，此路由永远不会与传入请求匹配；它只对生成URL有用。默认情况下， static 是 False . 见 静态路由 .

在 1.1 版本加入.

inherit_slash

此参数只能在以下情况下使用 pattern 是空字符串 ('' )。缺省情况下，合成的路由模式将始终包括尾随的劈开，但此参数提供了一种在两者都存在的情况下选择退出的方法，即您(开发人员调用 add_route )和集成商(开发人员设置 route prefix )，同意模式不应包含尾随的劈开。例如：

with config.route_prefix_context('/users'):
    config.add_route('users', '', inherit_slash=True)

在此示例中，生成的路由模式将为 /users 。或者，如果路由前缀是 /users/ ，则生成的路由模式将为 /users/ 。

在 2.0 版本加入.

谓词参数

模式

路线的模式，例如 ideas/{{idea}} . 此参数是必需的。见 路由模式语法 有关路由模式语法的信息。如果模式与当前URL不匹配，路由匹配将继续。

备注

为了向后兼容的目的（从 Pyramid 1） path 传递给此函数的关键字参数将用于表示模式值，如果 pattern 论证是 None . 如果两者 path 和 pattern 通过， pattern 胜利。

XHR

该值应为 True 或 False . 如果指定了此值并且 True , the request 必须拥有 HTTP_X_REQUESTED_WITH （阿卡 X-Requested-With ）要匹配的此路由的标题。这对于检测jquery、原型和其他javascript库发出的Ajax请求很有用。如果此谓词返回 False ，路由匹配继续。

request_method

表示HTTP方法名的字符串，例如 GET ， POST ， HEAD ， DELETE ， PUT 或者包含HTTP方法名的元素的元组。如果未指定此参数，则如果请求 any 请求方法。如果此谓词返回 False ，路由匹配继续。

在 1.2 版本发生变更: 将一组项传递为 request_method . 以前的版本只允许字符串。

path_info

此值表示将根据 PATH_INFO wsgi环境变量。如果regex匹配，则此谓词将返回 True . 如果此谓词返回 False ，路由匹配继续。

request_param

该值可以是任何字符串，也可以是字符串的可迭代。带有此参数的视图声明可确保只有当请求的 request.params 字典(HTTP GET 或 POST 变量)，该变量的名称与提供的值匹配。如果作为参数提供的值具有 = 在上面签名，例如： request_param="foo=123" ，那么这两个密钥 (foo )必须存在于 request.params 字典，并且该值必须与表达式的右侧匹配 (123 )，以使路由“匹配”当前请求。如果此谓词返回 False ，路由匹配将继续。

页眉

此参数可以是HTTP标头的字符串或字符串的可迭代。匹配确定如下：

  • 如果字符串不包含 : (冒号)，它将被视为标头名称(例如 If-Modified-Since )。在这种情况下，名称指定的标头必须出现在请求中，此字符串才能匹配。案例并不重要。

  • 如果字符串包含冒号，它将被视为名称/值对(例如 User-Agent:Mozilla/.* 或 Host:localhost )，其中值部分是正则表达式。名称指定的标头必须出现在请求中 and 指定为值部分的正则表达式必须与请求标头的值匹配。大小写对于标头名称并不重要，但对于值却很重要。

所有字符串都必须匹配，此谓词才能返回 True 。如果此谓词返回 False ，路由匹配将继续。

接受

A media type 这将与 Accept HTTP请求头。如果指定了此值，则它可能是特定的媒体类型，例如 text/html 或相同的列表。如果媒体类型被 Accept 请求的标题，或者如果 Accept 请求中根本没有设置头，该谓词将匹配。如果这与 Accept 请求的头，路由匹配继续。

如果 accept 未指定，则 HTTP_ACCEPT 在决定是否选择路由时，不考虑HTTP头。

不像 accept 参数 pyramid.config.Configurator.add_view() ，此值strict为谓词并支持 pyramid.config.not_() .

在 1.10 版本发生变更: 由于WebOB中的更改和尝试将范围与中的范围匹配时出现的模糊性，不推荐指定媒体范围。 Accept 标题。支架将在 Pyramid 2。使用特定媒体类型的列表来匹配多个类型。

在 2.0 版本发生变更: 已删除对媒体范围的支持。

is_authenticated

如果指定此值，则必须为 True 或 False 。如果指定了它，并且 True ，只有来自经过身份验证的用户的请求，由 security policy 在使用中，将满足谓词。如果指定了它，并且 False ，则只有来自未经身份验证的用户的请求才会满足谓词。

在 2.0 版本加入.

effective_principals

如果指定，则此值应为 principal 标识符或主体标识符序列。如果 pyramid.request.Request.effective_principals 属性指示参数列表中指定的每个主体都出现在当前请求中，则此谓词将返回True；否则将返回False。例如： effective_principals=pyramid.authorization.Authenticated 或 effective_principals=('fred', 'group:admins') 。

在 1.4a4 版本加入.

自 2.0 版本弃用: 使用 is_authenticated 或自定义谓词。

custom_predicates

自 1.5 版本弃用: 该值应该是对自定义谓词可调用文件的引用序列。当没有一组预定义谓词满足您的需要时，请使用自定义谓词。根据需要，自定义谓词可以与预定义谓词组合。每个自定义谓词可调用应接受两个参数： info 和 request 并且应该返回 True 或 False 在对信息和/或请求进行任意评估之后。如果所有自定义和非自定义谓词可调用文件都返回 True 对于给定的请求，相关的路由将被认为是可行的。如果任何谓词可调用返回 False ，路由匹配继续。注意这个值 info 传递给自定义路由谓词的是一个包含匹配信息的字典；请参见 自定义路由谓词 有关的详细信息 info .

** 谓语

传递额外的关键字参数以使用通过 pyramid.config.Configurator.add_route_predicate() 。可以同时使用多个自定义谓词。看见 查看和路由谓词 有关自定义谓词的详细信息，请参阅。

在 1.4 版本加入.

add_static_view(name, path, cache_max_age=3600, permission=NO_PERMISSION_REQUIRED)

添加用于呈现Static Assets（如图像和CSS文件）的视图。

这个 name 参数是表示应用程序相对本地URL前缀的字符串。它也可以是完整的URL。

这个 path 参数是静态文件所在磁盘上的路径。这可以是绝对路径、包相对路径或 asset specification .

这个 cache_max_age 输入关键字参数以设置 Expires 和 Cache-Control 已提供Static Assets的头。注意，当 name 是一个 URL前缀 . 默认情况下，此参数为 None ，表示响应中没有设置任何特定的过期或缓存控制头。

这个 content_encodings 关键字参数是 Accept-Encoding HTTP标头。使用中定义的文件扩展名可以找到替代文件 mimetypes.encodings_map 。编码的资产将随 Content-Encoding 设置为选定编码的标头。如果资源包含替代编码，则 Accept-Encoding 值将添加到响应的 Vary 标题。默认情况下，该列表为空，不支持任何备选方案。

这个 permission 关键字参数用于指定 permission 用户执行静态视图所必需的。默认情况下，它是字符串 pyramid.security.NO_PERMISSION_REQUIRED 一个特别的哨兵，表示即使 default permission 对于当前应用程序，静态视图应呈现给完全匿名的用户。这个默认值是允许的，因为在大多数Web应用程序中，Static Assets很少需要查看保护。如果 permission 如果指定，将对默认根工厂ACL执行安全检查。

发送到的任何其他关键字参数 add_static_view 被传给 pyramid.config.Configurator.add_route() （例如） factory ，可能是为该静态视图定义带有自定义ACL的自定义工厂）。

使用

这个 add_static_view 函数通常与 pyramid.request.Request.static_url() 方法。 add_static_view 添加在访问某个URL时呈现Static Assets的视图； pyramid.request.Request.static_url() 生成该资产的URL。

这个 name 参数 add_static_view 通常是一个简单的URL前缀（例如 'images' ）在这种情况下， pyramid.request.Request.static_url() API将生成一个指向Pyramid视图的URL，这个Pyramid视图将为包本身中的一组资产提供服务。例如：

add_static_view('images', 'mypackage:images/')

注册此类视图的代码可以通过 pyramid.request.Request.static_url() ：

request.static_url('mypackage:images/logo.png')

什么时候？ add_static_view 是用 name 表示URL前缀的参数，如上所述，随后调用 pyramid.request.Request.static_url() 以开头的路径 path 参数传递给 add_static_view 将生成类似于 http://<Pyramid app URL>/images/logo.png ，这将导致 logo.png 文件中 images 的子目录 mypackage 提供包。

add_static_view 可与 name 是一个 URL ，导致从外部Web服务器提供Static Assets。当 name 参数是完全限定的URL（例如以 http:// 或类似的）。在这种模式下， name 在使用生成URL时用作完整URL的前缀 pyramid.request.Request.static_url() . 此外，如果协议相关的URL（例如 //example.com/images ）用作 name 参数，生成的URL将使用请求的协议（分别是http或https）。

例如，如果 add_static_view 是这样叫的：

add_static_view('http://example.com/images', 'mypackage:images/')

随后，生成的URL pyramid.request.Request.static_url() 对于该静态视图，前缀为 http://example.com/images （正在侦听的外部Web服务器 example.com 必须将其自身配置为正确响应此类请求。）：

static_url('mypackage:images/logo.png', request)

见 服务静态资产 更多信息。

在 2.0 版本发生变更: 添加了 content_encodings 论点。

add_view(view=None, name='', for_=None, permission=None, request_type=None, route_name=None, request_method=None, request_param=None, containment=None, attr=None, renderer=None, wrapper=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), context=None, decorator=None, mapper=None, http_cache=None, match_param=None, require_csrf=None, exception_only=False, **view_options)

添加 view configuration 到当前配置状态。论据 add_view 被分解成 谓语 参数和 non-predicate 参数。谓词参数缩小了当请求提交给 Pyramid ；非谓词参数是信息性的。

非谓词参数

看法

A view callable 或A dotted Python name 它引用了一个可调用的视图。此参数是必需的，除非 renderer 参数也存在。如果A renderer 参数被传递，并且 view 未提供参数，视图可调用默认为返回空字典的可调用（请参见 正在写入使用渲染器的视图可调用文件 ）

许可

A permission 用户必须拥有才能调用 view callable . 见 配置视图安全性 有关查看安全性和权限的详细信息。这通常是一根绳子 view 或 edit .

如果 permission 被省略，A 违约 如果将此视图注册命名为 pyramid.config.Configurator 构造函数 default_permission 参数，或 pyramid.config.Configurator.set_default_permission() 在此视图注册之前使用。传递价值 pyramid.security.NO_PERMISSION_REQUIRED 作为权限参数来显式地指示视图应该始终由完全匿名的用户执行，而不管默认权限是什么，都绕过任何 authorization policy 这可能是有效的。

阿特尔

当视图定义是类时，此旋钮最有用。

视图机械默认使用 __call__ 方法 view callable （或者函数本身，如果视图可调用是函数）以获取响应。这个 attr 值允许您更改用于获取响应的方法属性。例如，如果视图是一个类，并且该类有一个名为 index 你想用这个方法而不是类 __call__ 你会说，返回响应的方法 attr="index" 在视图的视图配置中。

渲染器

这是一个单字符串项（例如 json ）或表示路径或 asset specification （例如） templates/views.pt ）命名为 renderer 实施。如果 renderer 值不包含点 . ，指定的字符串将用于查找呈现器实现，该呈现器实现将用于从视图返回值构造响应。如果 renderer 值包含一个点 (. ，指定的术语将被视为路径，路径中最后一个元素的文件扩展名将用于查找渲染器实现，该实现将传递完整路径。渲染器实现将用于构造 response 从视图返回值。

注意，如果视图本身返回 response （见 查看可调用响应 ，则从不调用指定的呈现器实现。

当渲染器是路径时，尽管路径通常只是一个简单的相对路径名（例如 templates/foo.pt ，表示名为“foo.pt”的模板位于相对于当前目录的“templates”目录中。 package 对于配置程序），路径可以是绝对路径，从UNIX上的斜线或Windows上的驱动器号前缀开始。路径可以是 asset specification 形式上 some.dotted.package_name:relative/path ，使其能够处理位于单独包中的模板资产。

这个 renderer 属性是可选的。如果未定义，则假定为“空”渲染器（不执行渲染并将值传递回上游 Pyramid 机械未修改）。

http_cache

在 1.1 版本加入.

当你提供一个 http_cache 视图配置的值， Expires 和 Cache-Control 由关联视图可调用生成的响应的头将被修改。价值 http_cache 可能是下列之一：

  • 非零整数。如果它是一个非零整数，它被视为秒数。此秒数将用于计算 Expires 报头和 Cache-Control: max-age 调用此视图的请求的响应参数。例如： http_cache=3600 指示请求浏览器“将此响应缓存一小时”。

  • A datetime.timedelta 实例。如果是 datetime.timedelta 例如，它将被转换为秒数，该秒数将用于计算 Expires 报头和 Cache-Control: max-age 调用此视图的请求的响应参数。例如： http_cache=datetime.timedelta(days=1) 指示请求浏览器“将此响应缓存一天”。

  • 零 (0 ）如果值为零，则 Cache-Control 和 Expires 来自此视图的所有响应中存在的头将被组成，这样客户端浏览器缓存（以及任何中间缓存）将被指示从不缓存响应。

  • 一个二元组。如果是两元组（例如 http_cache=(1, {{'public':True}}) ，元组中的第一个值可以是非零整数或 datetime.timedelta 实例；无论哪种情况，此值都将用作缓存响应的秒数。元组中的第二个值必须是字典。字典中的值将用作 Cache-Control 响应头。例如： http_cache=(3600, {{'public':True}}) 表示“缓存一小时，然后添加” public 到响应“”的缓存控制头。支持的所有键和值 webob.cachecontrol.CacheControl 接口可以添加到字典中。供应 {{'public':True}} 等于调用 response.cache_control.public = True .

提供非元组值作为 http_cache 等于调用 response.cache_expires(value) 在你的视野内。

提供两元组值作为 http_cache 等于调用 response.cache_expires(value[0], **value[1]) 在你的视野内。

如果你想避免影响，那么 Expires 标题，而只希望影响 Cache-Control 头，传递元组为 http_cache 第一个元素是 None ，例如： (None, {{'public':True}}) .

如果希望阻止使用 http_cache 在其配置中，通过此机器更改其缓存响应头，设置 response.cache_control.prevent_auto = True 在从视图返回响应之前。这有效地禁用了 http_cache 为了这个回应。

require_csrf

在 1.7 版本加入.

布尔选项或 None . 违约： None .

如果此选项设置为 True 然后将为此视图的请求启用CSRF检查。所需的令牌或头默认为 csrf_token 和 X-CSRF-Token ，分别。

CSRF检查仅影响由RFC2616定义的“不安全”方法。默认情况下，这些方法是除 GET ， HEAD ， OPTIONS 和 TRACE .

此处的默认值可能被覆盖 pyramid.config.Configurator.set_default_csrf_options() .

此功能需要配置 session factory .

如果此选项设置为 False 那么不管默认情况如何，CSRF检查都将被禁用。 require_csrf 设置传递给 set_default_csrf_options .

见 自动检查CSRF令牌 更多信息。

包装器

这个 view name 不同的 view configuration 将接收此视图的响应正文作为 request.wrapped_body 它自己的属性 request 和 response 此视图作为 request.wrapped_response 其自身请求的属性。使用包装器可以将视图“链接”在一起以形成复合响应。最外层包装视图的响应将返回给用户。将在找到任何视图时找到包装视图：请参阅 查看配置 . “最佳”包装视图将根据查找顺序找到：“在引擎盖下”此包装视图通过 pyramid.view.render_view_to_response(context, request, 'wrapper_viewname') . 包装视图的上下文和请求与内部视图的上下文和请求相同。如果未指定此属性，则不会进行视图换行。

装饰者

A dotted Python name 用于装饰注册的 view callable . 将使用可调用视图作为单个参数调用decorator函数。传递的可调用视图将接受 (context, request) . decorator必须返回一个可调用的替换视图，该视图也接受 (context, request) .

如果decorator是一个iterable，那么可调用文件将按照作为decorator提供的顺序进行组合和使用。例如：：

@view_config(...,
    decorator=(decorator2,
               decorator1))
def myview(request):
    ....

类似于做：

@view_config(...)
@decorator2
@decorator1
def myview(request):
    ...

除了现有的好处 decorator= （对于所有视图调用约定都有一个通用的修饰语法，并且不必考虑保留函数属性，例如 __name__ 和 __module__ 在装饰逻辑中）。

一个重要的区别是每个修饰符将接收一个响应对象实现 pyramid.interfaces.IResponse 而不是从视图可调用返回的原始值。链中的所有修饰符都必须返回响应对象或引发异常：

def log_timer(wrapped):
    def wrapper(context, request):
        start = time.time()
        response = wrapped(context, request)
        duration = time.time() - start
        response.headers['X-View-Time'] = '%.3f' % (duration,)
        log.info('view took %.3f seconds', duration)
        return response
    return wrapper

在 1.4a4 版本发生变更: 通过一个不可更改的。

映射器

python对象或 dotted Python name 指的是 view mapper 或 None . 默认情况下是 None 指示视图应使用默认视图映射器。这个插件对于Pyramid扩展开发人员很有用，但是对于那些只开发股票Pyramid应用程序的“平民”来说，它并不是很有用。别理窗帘后面的那个人。

接受

A media type 这将与 Accept HTTP请求头。如果指定了此值，则它必须是特定的媒体类型，例如 text/html 或 text/html;level=1 . 如果媒体类型被 Accept 请求的标题，或者如果 Accept 请求中根本没有设置头，该谓词将匹配。如果这与 Accept 请求的头，视图匹配继续。

如果 accept 未指定，则 HTTP_ACCEPT 在决定是否调用关联的视图可调用时，不考虑HTTP头。

这个 accept 从技术上讲，参数不是谓词，不支持包装 pyramid.config.not_() .

见 接受标题内容协商 更多信息。

在 1.10 版本发生变更: 指定媒体范围已弃用，将在中删除 Pyramid 2。使用显式媒体类型以避免内容协商中的任何含糊不清。

在 2.0 版本发生变更: 已删除对媒体范围的支持。

exception_only

在 1.8 版本加入.

当该值为 True , the context 参数必须是的子类 Exception . 此标志表示只有 exception view 应该创建，并且如果遍历 context 匹配 context 参数。如果 context 是的子类 Exception 这个值是 False （默认），然后将注册一个视图以匹配遍历 context 也。

谓词参数

名称

这个 view name . 读 遍历 了解视图名称的概念。

语境

物体或物体 dotted Python name 引用接口或类对象 context 必须是的实例， or 这个 interface 那 context 必须提供才能找到和调用此视图。当 context 是表示类的实例，或者如果 context 提供表示的接口；否则为假。此论点也可提供给 add_view 作为 for_ （旧的，仍然支持的拼写）。如果视图应该 only 处理异常时匹配，然后设置 exception_only 到 True .

route_name

此值必须与 name A的 route configuration 声明（见 URL调度 ）必须匹配才能调用此视图。

request_type

此值应为 interface 那 request 必须提供才能找到和调用此视图。此值的存在只是为了向后兼容。

request_method

该值可以是字符串（例如 "GET" ， "POST" ， "PUT" ， "DELETE" ， "HEAD" 或 "OPTIONS" ）表示HTTP REQUEST_METHOD 或包含一个或多个这些字符串的元组。带有此参数的视图声明确保只有在 method 请求的属性（即 REQUEST_METHOD 与提供的值匹配。注意使用 GET 也意味着这个观点将对 HEAD 从Pyramid1.4开始。

在 1.2 版本发生变更: 将一组项传递为 request_method . 以前的版本只允许字符串。

request_param

该值可以是任何字符串或任何字符串序列。带有此参数的视图声明确保只有在 request 有一把钥匙在 request.params 字典（HTTP GET 或 POST 变量）具有与提供的值（如果值是字符串）或值（如果值是元组）匹配的名称。如果提供的任何值具有 = 登录它，例如 request_param="foo=123" 然后是钥匙 (foo ）必须同时存在于 request.params 词典， and 该值必须与表达式的右侧匹配 (123 ）使视图与当前请求“匹配”。

match_param

在 1.2 版本加入.

这个值可以是格式为“key=value”的字符串，也可以是包含一个或多个字符串的元组。

带有此参数的视图声明确保只有在 request 其中有键/值对 matchdict 等于谓词中提供的值。例如 match_param="action=edit" 需要 action 中的参数 matchdict 匹配表达式的右侧 (edit ）使视图与当前请求“匹配”。

如果 match_param 是一个元组，每个键/值对必须匹配才能传递谓词。

遏制

该值应为python类或 interface （或） dotted Python name ）一个物体在 lineage 必须提供上下文的，才能找到和调用此视图。对象图中的节点必须“位置感知”才能使用此功能。见 位置感知资源 有关位置感知的更多信息。

XHR

该值应为 True 或 False . 如果指定了此值并且 True , the request 必须拥有 HTTP_X_REQUESTED_WITH （阿卡 X-Requested-With ）具有值的标题 XMLHttpRequest 以便找到并调用此视图。这对于检测jquery、原型和其他javascript库发出的Ajax请求很有用。

页眉

此参数可以是HTTP标头的字符串或字符串的可迭代。匹配确定如下：

  • 如果字符串不包含 : (冒号)，它将被视为标头名称(例如 If-Modified-Since )。在这种情况下，名称指定的标头必须出现在请求中，此字符串才能匹配。案例并不重要。

  • 如果字符串包含冒号，它将被视为名称/值对(例如 User-Agent:Mozilla/.* 或 Host:localhost )，其中值部分是正则表达式。名称指定的标头必须出现在请求中 and 指定为值部分的正则表达式必须与请求标头的值匹配。大小写对于标头名称并不重要，但对于值却很重要。

所有字符串都必须匹配，此谓词才能返回 True 。如果此谓词返回 False ，视图匹配将继续。

path_info

此值表示将根据 PATH_INFO wsgi环境变量。如果regex匹配，则此谓词将 True .

physical_path

如果指定，则此值应为表示 physical path 通过遍历找到的该谓词匹配为真的上下文。例如： physical_path='/' 或 physical_path='/a/b/c' 或 physical_path=('', 'a', 'b', 'c') . 这不是路径前缀匹配或regex，而是整个路径匹配。当某个对象被遍历到某个视图时，如果您希望始终潜在地显示该视图，这很有用，但是您不能确定它将是哪种类型的对象，因此不能使用 context 谓语。斜杠字符之间或元组元素中的单个path元素应为资源名称的Unicode表示形式，不应以任何方式进行编码。

在 1.4a3 版本加入.

is_authenticated

如果指定此值，则必须为 True 或 False 。如果指定了它，并且 True ，只有来自经过身份验证的用户的请求，由 security policy 在使用中，将满足谓词。如果指定了它，并且 False ，则只有来自未经身份验证的用户的请求才会满足谓词。

在 2.0 版本加入.

effective_principals

如果指定，则此值应为 principal 标识符或主体标识符序列。如果 pyramid.request.Request.effective_principals 属性指示参数列表中指定的每个主体都出现在当前请求中，则此谓词将返回True；否则将返回False。例如： effective_principals=pyramid.authorization.Authenticated 或 effective_principals=('fred', 'group:admins') 。

在 1.4a4 版本加入.

自 2.0 版本弃用: 使用 is_authenticated 或自定义谓词。

custom_predicates

自 1.5 版本弃用: 该值应该是对自定义谓词可调用的引用序列。每个自定义谓词Callable应该接受两个参数： context 和 request 并且应该返回 True 或 False 在对上下文和/或请求进行任意评估之后。能够通过以下方式注册自定义视图谓词 pyramid.config.Configurator.add_view_predicate() 此参数已过时，但为了向后兼容而保留。

**view_options

传递额外的关键字参数以使用自定义谓词或设置视图派生程序的值。看见 pyramid.config.Configurator.add_view_predicate() 和 pyramid.config.Configurator.add_view_deriver() 。看见 查看和路由谓词 有关自定义谓词和 视图推导程序 有关视图分流器的信息，请参见。

在 2.0 版本发生变更: 删除了对 check_csrf 谓语。

add_notfound_view(view=None, attr=None, renderer=None, wrapper=None, route_name=None, request_type=None, request_method=None, request_param=None, containment=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), decorator=None, mapper=None, match_param=None, append_slash=False, **view_options)

添加默认值 Not Found View 到当前配置状态。当Pyramid或应用程序代码引发 pyramid.httpexceptions.HTTPNotFound 异常（例如，当找不到请求的视图时）。最简单的例子是：

def notfound(request):
    return Response('Not Found', status='404 Not Found')

config.add_notfound_view(notfound)

如果 view 未提供参数，视图可调用默认为 default_exceptionresponse_view() .

所有参数，除了 append_slash 含义与 pyramid.config.Configurator.add_view() 而每个谓词参数都限制了调用NotFound视图的环境集。不像 pyramid.config.Configurator.add_view() ，此方法将在传递时引发异常 name ， permission ， require_csrf ， context ， for_ 或 exception_only 关键字参数。在未找到视图的上下文中，这些参数值没有意义。

如果 append_slash 是 True ，当调用此未找到视图，并且当前路径信息没有以斜线结尾时，NotFound逻辑将尝试查找 route 匹配请求的路径信息，并用斜杠后缀。如果存在这样的路由，Pyramid将发出一个重定向到路由所隐含的URL；如果不存在，Pyramid将返回可调用视图的结果，如 view ，正常情况下。

如果提供的参数为 append_slash 不是布尔值，而是实现 IResponse ，追加斜杠逻辑的行为将类似于 append_slash=True 已传递，但提供的类将用作响应类，而不是默认的 HTTPTemporaryRedirect 执行重定向时的响应类。例如：

from pyramid.httpexceptions import HTTPMovedPermanently
config.add_notfound_view(append_slash=HTTPMovedPermanently)

上面的意思是将尝试重定向到斜线附加的路由，但不是 HTTPTemporaryRedirect 被使用， HTTPMovedPermanently will be used 如果找到斜线追加的路由，则返回重定向响应。

HTTPTemporaryRedirect 类用作默认响应，相当于 HTTPFound 使用相同的HTTP方法添加重定向（在执行POST请求时很有用）。

在 1.3 版本加入.

在 1.6 版本发生变更: 这个 append_slash 参数被修改为允许实现 IResponse 用于指定执行重定向时使用的响应类的接口。

在 1.8 版本发生变更: 视图是使用 exception_only=True .

add_forbidden_view(view=None, attr=None, renderer=None, wrapper=None, route_name=None, request_type=None, request_method=None, request_param=None, containment=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), decorator=None, mapper=None, match_param=None, **view_options)

将禁止的视图添加到当前配置状态。当Pyramid或应用程序代码引发 pyramid.httpexceptions.HTTPForbidden 异常和所提供谓词所隐含的一组情况是匹配的。最简单的例子是：

def forbidden(request):
    return Response('Forbidden', status='403 Forbidden')

config.add_forbidden_view(forbidden)

如果 view 未提供参数，视图可调用默认为 default_exceptionresponse_view() .

所有论点的含义与 pyramid.config.Configurator.add_view() 而每个谓词参数都限制了在何种情况下调用禁止的视图。不像 pyramid.config.Configurator.add_view() ，此方法将在传递时引发异常 name ， permission ， require_csrf ， context ， for_ 或 exception_only 关键字参数。这些参数值在禁止的上下文中没有意义 exception view .

在 1.3 版本加入.

在 1.8 版本发生变更: 视图是使用 exception_only=True .

add_exception_view(view=None, context=None, **view_options)

添加一个 exception view 对于指定的 exception 到当前配置状态。当Pyramid或应用程序代码引发给定的异常时，将调用该视图。

此方法接受几乎所有与 pyramid.config.Configurator.add_view() 除了 name ， permission ， for_ ， require_csrf 和 exception_only .

默认情况下，此方法将设置 context=Exception 从而注册大多数默认的python异常。任何子类 Exception 可以指定。

在 1.8 版本加入.

Adding an Event Subscriber

add_subscriber(subscriber, iface=None, **predicates)

添加事件 subscriber 对于所提供的 iface 接口。

这个 subscriber 参数表示可调用对象（或 dotted Python name 它标识一个可调用的）；它将用一个对象调用 event 无论何时 Pyramid 发射一个 event 与 iface ，可能是 interface 或者一个类或一个类 dotted Python name 表示接口或类的全局对象。

使用默认值 iface 价值， None 将导致订阅服务器注册所有事件类型。见 使用事件 有关事件和订阅服务器的详细信息。

可以传入任意数量的谓词关键字参数 **predicates . 名为的每个谓词都将缩小将调用订阅服务器的环境集。每个已命名的谓词都必须通过 pyramid.config.Configurator.add_subscriber_predicate() 才能使用。见 订阅服务器谓词 更多信息。

在 1.4 版本加入: 这个 **predicates 参数。

Using Security

set_security_policy(policy)

重写 Pyramid security policy 在当前配置中。这个 policy 参数必须是安全策略的实例或 dotted Python name 它指向安全策略的一个实例。

备注

使用 security_policy 参数设置为 pyramid.config.Configurator 构造函数可以实现相同的目的。

set_authentication_policy(policy)

自 2.0 版本弃用: 身份验证策略已被安全策略取代。看见 升级身份验证/授权 了解更多信息。

重写 Pyramid authentication policy 在当前配置中。这个 policy 参数必须是身份验证策略或 dotted Python name 它指向一个身份验证策略的实例。

备注

使用 authentication_policy 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

set_authorization_policy(policy)

自 2.0 版本弃用: 身份验证策略已被安全策略取代。看见 升级身份验证/授权 了解更多信息。

重写 Pyramid authorization policy 在当前配置中。这个 policy 参数必须是授权策略的实例或 dotted Python name 它指向授权策略的一个实例。

备注

使用 authorization_policy 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

set_default_csrf_options(require_csrf=True, token='csrf_token', header='X-CSRF-Token', safe_methods=('GET', 'HEAD', 'OPTIONS', 'TRACE'), check_origin=True, allow_no_origin=False, callback=None)

设置后续视图注册使用的默认CSRF选项。

require_csrf 控制是否在应用程序中的每个视图上自动启用CSRF检查。当 require_csrf 默认为 None 在 pyramid.config.Configurator.add_view() .

token 是请求主体中使用的CSRF令牌的名称，通过访问 request.POST[token] . 违约： csrf_token .

header 是包含CSRF令牌的头的名称，通过访问 request.headers[header] . 违约： X-CSRF-Token .

如果 token 或 header 设置为 None 它们不会用于检查CSRF令牌。

safe_methods 是HTTP方法的一个ITable，该方法不包含由rfc2616定义的副作用。不会自动检查CSRF令牌的安全方法。违约： ('GET', 'HEAD', 'OPTIONS', TRACE') .

check_origin 是一个布尔值。如果 False ，即 Origin 和 Referer 标头不会作为自动CSRF检查的一部分进行验证。

allow_no_origin 是一个布尔值。如果 True ，则该请求既缺少 Origin 和 Referer 报头将通过CSRF检查。在以下情况下，此选项无效 check_origin 是 False 。

如果 callback 已设置，它必须是可调用接受 (request) 归还 True 如果应该检查请求是否有有效的CSRF令牌。此回调允许应用程序支持不依赖于不受CSRF攻击的cookie的备用身份验证方法。例如，如果使用 Authorization 头而不是cookie，这可能返回 False 以便客户端不需要发送 X-CSRF-Token 标题。仅对由定义的非安全方法测试回调 safe_methods .

在 1.7 版本加入.

在 1.8 版本发生变更: 增加了 callback 选择权。

在 2.0 版本发生变更: 添加了 allow_no_origin 和 check_origin 选项。

set_csrf_storage_policy(policy)

设置 CSRF storage policy 由后续视图注册使用。

policy 是实现 pyramid.interfaces.ICSRFStoragePolicy() 接口并定义如何生成和持久化CSRF令牌。

set_default_permission(permission)

设置所有后续用户使用的默认权限 view configuration 注册。 permission 应该是 permission 用作默认权限的字符串。权限字符串的示例：“view”。添加默认权限会使您不必使用显式权限保护每个视图配置，除非应用程序策略要求对特定视图进行某些异常。

如果默认权限是 not 集合，由未显式声明权限的视图配置注册表示的视图将完全由匿名用户执行（忽略任何授权策略）。

稍后对此方法重写的调用将与以前的调用冲突；应用程序中一次只能有一个默认权限处于活动状态。

警告

如果默认权限生效，视图配置将创建真正匿名访问的视图（甚至 exception view 视图） must 将可导入权限的值用作 pyramid.security.NO_PERMISSION_REQUIRED . 当此字符串用作 permission 对于视图配置，将忽略默认权限，并注册视图，使其对所有调用方都可用，而不考虑其凭据。

参见

也见 设置默认权限 .

备注

使用 default_permission 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

add_permission(permission_name)

一种配置程序指令，它注册一个独立的权限，而不将其与可调用的视图相关联。这可用于使权限显示在 permissions 类别（通过 add_view 已经结束了）。例如：：

config = Configurator()
config.add_permission('view')

Extending the Request Object

add_request_method(callable=None, name=None, property=False, reify=False)

向请求对象添加属性或方法。

向请求添加方法时， callable 可以是作为第一个参数接收请求对象的任何函数。如果 name 是 None 然后根据 callable .

向请求添加属性时， callable 可以是接受请求作为其单个位置参数的可调用文件，也可以是属性描述符。如果 callable 是属性描述符，它必须是属于 property .如果 name 是 None ，属性的名称将根据 callable .

如果 callable 是属性描述符A ValueError 如果 name 是 None 或 reify 是 True .

见 pyramid.request.Request.set_property() 有关更多详细信息 property VS reify . 什么时候？ reify 是 True 的价值 property 假设也 True .

在所有情况下， callable 也可能是 dotted Python name 它引用可调用或属性描述符。

如果 callable 是 None 然后，该方法仅用于帮助检测请求对象上请求相同属性的不同加载项之间的冲突。

这是扩展请求对象的推荐方法，应该用于通过 pyramid.config.Configurator.set_request_factory() .

在 1.4 版本加入.

Using I18N

add_translation_dirs(*specs, **kw)

添加一个或多个 translation directory 当前配置状态的路径。这个 specs 参数是一个序列，它可能包含绝对目录路径（例如 /usr/share/locale 或 asset specification 命名目录路径的名称（例如 some.package:locale ）或者两者的结合。

例子：

config.add_translation_dirs('/usr/share/locale',
                            'some.package:locale')

翻译目录定义为一个列表，其中稍后定义的翻译优先于先前定义的翻译。

默认情况下，连续调用 add_translation_dirs 将目录添加到列表的开头。这意味着以后打电话给 add_translation_dirs 他们的翻译会被早先的电话抢先。如果您明确需要此呼叫胜过先前的呼叫，则可以设置 override 到 True .

如果在一次调用中提供多个规范 add_translation_dirs ，目录将按提供的顺序插入（早期的项目由后期的项目决定）。

在 1.8 版本发生变更: 这个 override 添加了参数以允许稍后调用 add_translation_dirs 要覆盖先前的调用，请在翻译目录列表的开头插入文件夹。

set_locale_negotiator(negotiator)

设置 locale negotiator 对于此应用程序。这个 locale negotiator 是接受 request 对象并返回 locale name . 这个 negotiator 参数应该是区域设置协商器实现或 dotted Python name 指的是这种实现。

稍后对此方法的调用将覆盖以前的调用；应用程序中一次只能有一个活动的区域设置协商器。见 激活翻译 更多信息。

备注

使用 locale_negotiator 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

Overriding Assets

override_asset(to_override, override_with)

添加 Pyramid 资产覆盖到当前配置状态。

to_override 是一个 asset specification 覆盖的资产。

override_with 是一个 asset specification 执行覆盖的资产。这也可能是一条绝对路径。

见 静态资产 有关资产替代的详细信息。

Getting and Adding Settings

add_settings(settings=None, **kw)

增补 deployment settings 具有一个或多个键/值对。

你可以通过字典：

config.add_settings({'external_uri':'http://example.com'})

或一组键/值对：

config.add_settings(external_uri='http://example.com')

当需要测试访问 pyramid.registry.Registry.settings API（或 pyramid.config.Configurator.get_settings() 以及使用该API中的值。

get_settings()

返回A deployment settings 当前应用程序的对象。部署设置对象是一个类似字典的对象，它包含基于作为 settings 论据 pyramid.config.Configurator 建造师。

备注

这个 pyramid.registry.Registry.settings API执行相同的任务。

Hooking Pyramid Behavior

add_accept_view_order(value, weighs_more_than=None, weighs_less_than=None)

为指定排序首选项 accept 查看期间使用的选项 view lookup .

默认情况下，如果两个视图有不同 accept 选项和请求指定 Accept: */* 或者完全忽略标题，那么将随机选择哪个视图。此方法提供了一种在接受媒体类型之间指定服务器端相对顺序的方法。

value 应该是 media type 按规定 RFC 7231#section-5.3.2 . 例如， text/plain;charset=utf8 ， application/json 或 text/html .

weighs_more_than 和 weighs_less_than 控制媒体类型的顺序。每个值可以是字符串或字符串列表。如果所有选项 weighs_more_than （或） weighs_less_than ）找不到，这是一个错误。

提前打电话给 add_accept_view_order 它们比以后的调用具有更高的优先级，假定有类似的约束，但是可以使用标准的冲突解决机制来覆盖约束。

见 接受标题内容协商 更多信息。

在 1.10 版本加入.

add_renderer(name, factory)

添加 Pyramid renderer 工厂到当前配置状态。

这个 name 参数是渲染器名称。使用 None 表示默认渲染器（除非指定了其他渲染器，否则将用于所有视图的渲染器）。

这个 factory 参数是对 renderer 工厂或 dotted Python name 一样。

add_resource_url_adapter(adapter, resource_iface=None)

在 1.3 版本加入.

如中所述添加遍历器时 更改遍历器 ，继续使用 pyramid.request.Request.resource_url() 应用程序编程接口。但是，由于遍历的方式可能已被修改，因此 resource_url 当自定义遍历器返回资源时，默认情况下生成可能不正确。

如果添加了遍历器，则可以更改 resource_url() 通过调用此方法为特定类型的资源生成URL。

这个 adapter 参数表示实现 IResourceURL 接口。类构造函数应在其构造函数（资源和请求）中接受两个参数，并且生成的实例应提供该接口中详细说明的属性。 (virtual_path 和 physical_path 尤其是）。

这个 resource_iface 参数表示资源应拥有的类或接口，以便在此URL适配器使用时 pyramid.request.Request.resource_url() 查找资源URL适配器。如果 resource_iface 未通过，或作为 None ，URL适配器将用于每种类型的资源。

见 如何改变 pyramid.request.Request.resource_url() 生成URL 更多信息。

add_response_adapter(adapter, type_or_iface)

当类型（或接口）的对象 type_or_iface 从可调用的视图返回，Pyramid将使用适配器 adapter 将其转换为实现 pyramid.interfaces.IResponse 接口。如果 adapter 为“无”，返回的对象类型（或接口） type_or_iface 将自身用作响应对象。

adapter 和 type_or_interface 可以是python对象，也可以是表示可导入的python全局对象的点名称的字符串。

见 更改金字塔处理视图响应的方式 更多信息。

add_traverser(adapter, iface=None)

超级违约 traversal 算法 Pyramid 使用说明见 遍历算法 . 尽管很少有必要，但可以通过配置有选择地将此默认算法换成不同的遍历模式。标题为 更改遍历器 详细说明如何创建遍历器类。

例如，要覆盖Pyramid使用的超默认遍历器，可以执行如下操作：

from myapp.traversal import MyCustomTraverser
config.add_traverser(MyCustomTraverser)

这将导致永远不使用Pyramid超默认遍历器；相反，所有遍历都将使用 MyCustomTraverser 类，无论 root factory 此应用程序的。注意，我们没有向 iface 关键字参数。默认值为 iface ， None 表示当根工厂返回的对象没有其他更具体的遍历器可用时，应使用注册的遍历器。

但是，可以同时激活多个遍历算法。所用的遍历器可以取决于 root factory . 例如，如果根工厂有条件地返回多个对象类型，则可以声明应针对根工厂返回的特定类或接口使用备用遍历器适配器。当根工厂返回实现该类或接口的对象时，将使用自定义遍历器。否则，将使用默认的遍历器。这个 iface 参数表示根工厂可能返回的对象的类，或者 interface 对象可能实现的。

要仅在根工厂返回特定类时使用特定的遍历器，请执行以下操作：

config.add_traverser(MyCustomTraverser, MyRootClass)

当多个遍历器处于活动状态时，将使用“最具体”的遍历器（与根工厂返回的值的类或接口最匹配的遍历器）。

请注意 adapter 或 iface 可以是 dotted Python name 或者一个python对象。

见 更改遍历器 更多信息。

add_tween(tween_factory, under=None, over=None)

在 1.2 版本加入.

增加一个“吐温工厂”。一 tween （between的缩写）是位于Pyramid路由器的主请求处理函数和上游使用的wsgi组件之间的一点代码。 Pyramid 作为它的“应用程序”。Tweens是一种特性，可以由Pyramid框架扩展使用，例如提供Pyramid特定的视图计时支持、在返回上游WSGi应用程序之前检查异常的簿记代码，或者其他各种特性。吐温的表现有点像 WSGI “中间件”，但它们的好处是在可以访问Pyramid的上下文中运行 application registry 以及Pyramid渲染设备。

备注

您可以使用 ptweens 命令。见 ptweens ：显示“Tweens” .

这个 tween_factory 参数必须是 dotted Python name 到表示Tween工厂的全局对象。

这个 under 和 over 参数允许调用 add_tween 为提示吐温链中的位置，当使用隐式吐温链时，应将吐温工厂放置在哪里。这些提示仅在不使用显式tween链时使用（当 pyramid.tweens 未设置配置值）。允许值 under 或 over （或两者兼而有之）：

under 表示“比主Pyramid应用程序更接近”， over 意思是“接近请求入口比”。

例如，调用 add_tween('myapp.tfactory', over=pyramid.tweens.MAIN) 将尝试放置以虚线名称表示的Tween工厂 myapp.tfactory 直接“高于”（in ptweens order）主Pyramid请求处理程序。同样，打电话 add_tween('myapp.tfactory', over=pyramid.tweens.MAIN, under='mypkg.someothertween') 将尝试将此tween工厂置于“主处理程序”之上，而置于“主处理程序”之下（虚构的）“mypkg.someothertween”tween工厂。

如果所有选项 under （或） over )在当前配置中找不到，这是一个错误。如果某些选项纯粹是为了与其他tween兼容而指定的，只需添加MAIN或ingres的回退。例如， under=('mypkg.someothertween', 'mypkg.someothertween2', INGRESS) . 这一限制要求吐温位于“mypkg.somethertween”吐温、“mypkg.somethertween2”吐温和入口下方。如果其中任何一个不在当前配置中，那么这个约束将只根据存在的中间层组织自己。

两者都不指定 over 也不 under 相当于指定 under=INGRESS .

显然，隐式二元排序只是最好的工作。Pyramid将尽可能地呈现出一个隐含的吐温顺序，但唯一可靠的获得任何特定顺序的方法是使用一个明确的吐温顺序。用户可以通过使用显式 pyramid.tweens 配置值设置。

under 和 over 当使用 pyramid.tweens 配置值。

有关详细信息，请参阅 登记吐温 .

add_route_predicate(name, factory, weighs_more_than=None, weighs_less_than=None)

添加路由谓词工厂。视图谓词稍后可以作为关键字参数命名为 pyramid.config.Configurator.add_route() .

name 应该是谓词的名称。它必须是有效的python标识符（它将用作 add_route ）

factory 应该是 predicate factory 或 dotted Python name 它指的是谓词工厂。

见 查看和路由谓词 更多信息。

在 1.4 版本加入.

add_subscriber_predicate(name, factory, weighs_more_than=None, weighs_less_than=None)

在 1.4 版本加入.

添加订阅服务器谓词工厂。以后可以将关联的订阅服务器谓词命名为 pyramid.config.Configurator.add_subscriber() 在 **predicates 匿名关键字参数字典。

name 应该是谓词的名称。它必须是有效的python标识符（它将用作 **predicates 关键字参数 add_subscriber() ）

factory 应该是 predicate factory 或 dotted Python name 它指的是谓词工厂。

见 订阅服务器谓词 更多信息。

add_view_predicate(name, factory, weighs_more_than=None, weighs_less_than=None)

在 1.4 版本加入.

添加视图谓词工厂。关联的视图谓词稍后可以作为关键字参数命名为 pyramid.config.Configurator.add_view() 在 predicates 任意关键字参数字典。

name 应该是谓词的名称。它必须是有效的python标识符（它将用作 add_view 其他人）。

factory 应该是 predicate factory 或 dotted Python name 它指的是谓词工厂。

见 查看和路由谓词 更多信息。

add_view_deriver(deriver, name=None, under=None, over=None)

在 1.7 版本加入.

添加 view deriver 到视图管道。视图派生器是扩展作者用来将视图包装在自定义代码中的一个特性，这些自定义代码由视图特定的选项控制。

deriver 应该是符合 pyramid.interfaces.IViewDeriver 接口。

name 应为视图派生器的名称。视图派生器的名称没有限制。如果未指定，则将使用 deriver .

这个 under 和 over 通过提供有关在视图管道中使用派生器的位置的提示，可以使用选项控制视图派生器的顺序。每个选项可以是字符串或字符串列表。在每个视图中，必须至少存在一个“上”和“下”方向的视图派生器，才能完全满足约束条件。

under 意味着更接近用户定义 view callable 和 over 意味着靠近管道入口。

的默认值 over 是 rendered_view 和 under 是 decorated_view . 这会将派生器放在视图管道中的两个之间。如果衍生工具应该放在管道的其他地方，如上面 decorated_view ，则还必须指定 under 订单中较早的内容，或 CyclicDependencyError 在尝试对派生词排序时将引发。

见 视图推导程序 更多信息。

set_execution_policy(policy)

重写 Pyramid execution policy 在当前配置中。这个 policy 参数必须是 pyramid.interfaces.IExecutionPolicy 或A dotted Python name 指向执行策略的实例。

set_request_factory(factory)

对象作为 factory 应该是一个对象（或 dotted Python name 指的是一个对象），它将被 Pyramid 路由器创建所有请求对象。此工厂对象必须具有与 pyramid.request.Request 等级（尤其是 __call__ 和 blank ）

见 pyramid.config.Configurator.add_request_method() 以一种更不具侵入性的方式使用自定义方法和属性扩展请求对象。

备注

使用 request_factory 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

set_root_factory(factory)

添加 root factory 到当前配置状态。如果 factory 论证是 None 将注册默认根工厂。

备注

使用 root_factory 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

set_session_factory(factory)

使用配置应用程序 session factory . 如果调用此方法，则 factory 参数必须是可调用的会话工厂或 dotted Python name 去那个工厂。

备注

使用 session_factory 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

set_view_mapper(mapper)

设置一个 view mapper 使利用 view callable 实现不同于支持的调用签名的对象 Pyramid 如其叙述性文件所述。

这个 mapper 参数应为实现 pyramid.interfaces.IViewMapperFactory 或A dotted Python name 对这样一个物体。提供的 mapper 将成为所有后续视图映射器使用的默认视图映射器 view configuration 注册。

参见

也见 使用视图映射器 .

备注

使用 default_view_mapper 论据 pyramid.config.Configurator 构造函数可用于实现相同的目的。

Extension Author APIs

action(discriminator, callable=None, args=(), kw=None, order=0, introspectables=(), **extra)

注册将在以下情况下执行的操作： pyramid.config.Configurator.commit() 被调用（或立即执行，如果 autocommit 是 True ）

警告

此方法通常仅用于 Pyramid 框架扩展作者，而不是 Pyramid 应用程序开发人员。

这个 discriminator 唯一标识操作。必须给出，但可以 None ，以指示操作从不冲突。它必须是可哈希值。

这个 callable 是一个可调用对象，在执行操作时执行与该操作关联的任务。这是可选的。

args 和 kw 分别是tuple和dict对象，传递给 callable 执行此操作时。两者都是可选的。

order 是一种分组机制；具有较低顺序的操作将在具有较高顺序的操作之前执行（当autocommit为 True ）

introspectables 是一个序列 introspectable 对象（如果没有可内省的对象与此操作关联，则为空序列）。如果这个配置器 introspection 属性是 False ，这些自省将被忽略。

extra 提供将额外键和值插入动作字典的功能。

add_directive(name, directive, action_wrap=True)[源代码]

向配置器添加一个指令方法。

警告

此方法通常仅用于 Pyramid 框架扩展作者，而不是 Pyramid 应用程序开发人员。

框架扩展器可以通过指示其用户调用向配置器添加指令方法 config.add_directive('somename', 'some.callable') . 这将使 some.callable 可访问的 config.somename . some.callable 应该是一个接受 config 作为第一个参数，然后是任意位置和关键字参数。它应该根据需要使用config.action来执行操作。然后可以像“内置”指令一样调用指令方法，例如 add_view ， add_route 等。

这个 action_wrap 参数应为 True 用于执行的指令 config.action 有潜在冲突的鉴别器。 action_wrap 将导致指令包装在提供更准确冲突原因信息的装饰器中。

add_directive 不参与冲突检测，稍后调用 add_directive 将覆盖以前的呼叫。

with_package(package)[源代码]

返回与此配置程序具有相同注册表的新配置程序实例。 package 可能是实际的python包对象或 dotted Python name 表示一个包。

derive_view(view, attr=None, renderer=None)

创建一个 view callable 使用函数、实例或类（或 dotted Python name 参考相同）提供如下： view 对象。

警告

此方法通常仅用于 Pyramid 框架扩展作者，而不是 Pyramid 应用程序开发人员。

对于创建可插入系统的框架扩展器来说，这是一个有用的API，这些系统需要为满足 Pyramid 查看可调用。例如，A some_other_framework 另一个框架中的函数可能希望允许用户提供可调用视图，但他可能希望在将包装器注册为 Pyramid 查看可调用。因为A Pyramid 视图可调用对象可以是许多有效对象中的任何一个，框架扩展程序将不知道如何调用用户提供的对象。运行它 derive_view 将其规范化为可调用的，可接受两个参数： context 和 request .

例如：

def some_other_framework(user_supplied_view):
    config = Configurator(reg)
    proxy_view = config.derive_view(user_supplied_view)
    def my_wrapper(context, request):
        do_something_that_mutates(request)
        return proxy_view(context, request)
    config.add_view(my_wrapper)

这个 view 提供的对象应为以下对象之一：

  • 接受 request 作为单个位置参数返回 response 对象。

  • 接受两个位置参数的函数或其他非类可调用对象， context, request 它返回一个 response 对象。

  • 在名为的构造函数中接受单个位置参数的类 request ，它有一个 __call__ 不接受返回 response 对象。

  • 接受两个名为 context, request ，它有一个 __call__ 不接受返回 response 对象。

  • A dotted Python name 指上述任何一种物体。

此API返回接受参数的可调用 context, request 并返回调用所提供的 view 对象。

这个 attr 当视图对象是类时，关键字参数最有用。它命名了应该用作可调用的方法。如果 attr 未提供，该属性有效地默认为 __call__ . 见 将可调用视图定义为类 更多信息。

这个 renderer 关键字参数应为呈现器名称。如果提供，它将导致返回的Callable使用 renderer 将用户提供的视图结果转换为 response 对象。如果A renderer 未提供参数，用户提供的视图本身必须返回 response 对象。

Utility Methods

absolute_asset_spec(relative_spec)[源代码]

解决潜在的亲属关系 asset specification 字符串作为 relative_spec 转换为绝对资产规格字符串并返回该字符串。使用 package 在生成绝对资产规格时，将资产规格视为相对的配置程序包。如果提供 relative_spec 参数已经是绝对的，或者如果 relative_spec 不是字符串，只是返回。

maybe_dotted(dotted)[源代码]

解决 dotted Python name dotted 到全局python对象。如果 dotted 不是字符串，返回它时不尝试进行任何名称解析。如果 dotted 是相对虚线名称（例如 .foo.bar ，考虑它相对于 package 提供给此配置器的构造函数的参数。

ZCA-Related APIs

hook_zca()

呼叫 zope.component.getSiteManager.sethook() 有了参数 pyramid.threadlocal.get_current_registry 导致 Zope Component Architecture “全局”API，例如 zope.component.getSiteManager() ， zope.component.getAdapter() 和其他人使用 Pyramid application registry 而不是Zope的“全局”注册表。

unhook_zca()

呼叫 zope.component.getSiteManager.reset() 撤消 pyramid.config.Configurator.hook_zca() .

setup_registry(settings=None, root_factory=None, security_policy=None, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, response_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, exceptionresponse_view=<function default_exceptionresponse_view>)[源代码]

当你通过一个非``无`` registry 论据 Configurator 构造函数，没有对注册表执行初始设置。这是因为您传入的注册表可能已经初始化，以便在下使用 Pyramid 通过不同的配置器。但是，在某些情况下（例如，当您希望使用全局注册表而不是配置器构造函数创建的注册表时），或者当您希望重置注册表的初始设置时，您可以 do 希望显式初始化与配置程序关联的注册表，以便在下使用 Pyramid . 使用 setup_registry 进行初始化。

setup_registry 根据配置器构造函数中的描述，使用配置器的当前注册表配置设置、根工厂、安全策略、渲染器、调试记录器、区域设置协商器和各种其他设置。

Testing Helper APIs

testing_add_renderer(path, renderer=None)

单元/集成测试助手：在处注册渲染器 path （通常是相对文件名ala templates/foo.pt 或者资产规格）并返回渲染器对象。如果 renderer 参数为“无”，将使用“虚拟”呈现器。此函数在测试调用 pyramid.renderers.render() 功能或 pyramid.renderers.render_to_response() 功能或任何其他 render_* 或 get_* API pyramid.renderers 模块。

请注意，使用 path 表示渲染器工厂类型的参数（例如 foo.pt 通常意味着 chameleon_zpt 渲染器工厂）删除为该类型注册的任何现有渲染器工厂。

备注

此方法在别名下也可用 testing_add_template （它的旧名称）。

testing_add_subscriber(event_iface=None)

单元/集成测试助手：寄存器A subscriber 它监听这种类型的事件 event_iface . 此方法返回一个列表对象，每当捕获事件时，订阅服务器都会将其附加到该列表对象。

当调度的事件与 event_iface 参数，该事件将附加到列表中。然后可以将列表中的值与预期的事件通知进行比较。此方法在测试要调用的代码时很有用 pyramid.registry.Registry.notify() 或 zope.component.event.dispatch() .

默认值为 event_iface (None ）表示为注册的订阅服务器 any 一类事件。

testing_resources(resources)

单元/集成测试助手：注册 resource 可以通过 pyramid.traversal.find_resource() 应用程序编程接口。

这个 pyramid.traversal.find_resource() 使用路径作为参数之一调用API。如果在调用此方法时注册的字典将该路径作为字符串键（例如 /foo/bar 或 foo/bar ）将返回相应的值 find_resource （以及你的代码）什么时候 pyramid.traversal.find_resource() 使用等效的路径字符串或元组调用。

testing_securitypolicy(userid=None, identity=None, permissive=True, remember_result=None, forget_result=None)

单元/集成测试帮助器。登记的是假的 security policy 。

此函数在测试使用安全API的代码时最有用，例如 pyramid.request.Request.identity() ， pyramid.request.Request.authenticated_userid ，或 pyramid.request.Request.has_permission() ，

注册人的行为 security policy 取决于传递给此方法的参数。

参数:

  • userid (str) -- 如果提供，保单的 authenticated_userid 方法将返回此值。结果, pyramid.request.Request.authenticated_userid 也会有这个值。

  • identity (object) -- 如果提供，保单的 identity 方法将返回此值。结果, pyramid.request.Request.identity `将具有此值。

  • permissive (bool) -- 如果为true，则该策略将允许任何用户访问任何权限。如果为False，则策略将拒绝所有访问。

  • remember_result (list) -- 如果提供，保单的 remember 方法将返回此值。否则， remember 将返回一个空列表。

  • forget_result (list) -- 如果提供，保单的 forget 方法将返回此值。否则， forget 将返回一个空列表。

在 1.4 版本加入: 这个 remember_result 参数。

在 1.4 版本加入: 这个 forget_result 参数。

在 2.0 版本发生变更: 已删除 groupids 参数和加法 identity 论点。

Attributes

introspectable

指向 pyramid.registry.Introspectable 类（在指令期间用于对操作进行自省）。

在 1.3 版本加入.

introspector

这个 introspector 与此配置相关。它是实现 pyramid.interfaces.IIntrospector 接口。

在 1.3 版本加入.

registry

这个 application registry 它保存与此配置器关联的配置。

global_registries

为创建的注册表集 Pyramid 应用程序，每次调用一个 pyramid.config.Configurator.make_wsgi_app() 在当前进程中。对象本身支持迭代，并且具有 last 包含上次加载的注册表的属性。

此对象中包含的注册表存储为weakrefs，因此它们仅在实际应用程序的生命周期内存在。

class not_(value)[源代码]

通过将任何谓词值包装在调用中，可以颠倒其含义。 pyramid.config.not_ .

1from pyramid.config import not_
2
3config.add_view(
4    'mypackage.views.my_view',
5    route_name='ok',
6    request_method=not_('POST')
7    )

上面的示例将确保如果请求方法是 not POST ，至少在没有其他视图更具体的情况下。

将谓词值包装在 not_ 可以在接受谓词值的任何位置使用：

在 1.5 版本加入.

PHASE0_CONFIG
PHASE1_CONFIG
PHASE2_CONFIG
PHASE3_CONFIG