repoze.bfg 1.3

支持和文档

请访问 repoze.bfg 网站 查看文档、报告错误和获取支持。

许可

repoze.bfg 在BSD衍生 Repoze公共许可证 下提供。

作者

repoze.bfg 由 Agendaless Consulting 和一组贡献者提供。

错误修复

• 当存在默认权限并且已注册“静态视图”（通过 repoze.bfg.configuration.Configurator.add_static_view 或通过 static ZCML指令），默认情况下，静态视图受到默认权限的保护，没有方法表明它是匿名可查看的。从这次发布开始，使用权限哨兵 __no_permission_required__ 作为默认权限注册静态视图，使其资源可由完全匿名的用户查看。

功能

• 在 repoze.bfg.configuration.Configurator.add_static_view 方法中添加了 permission 参数，并且现在在 static ZCML 指令中也有一个 permission 属性。

文档

• 在词汇表中添加了一个“默认权限”条目。

错误修复

• 由于配置器中的错误，repoze.bfg.security.view_execution_permitted API 可能返回错误的布尔结果，导致在没有权限的人导入和使用时，视图执行不适当。感谢 Shane Hathaway 提交的错误报告和补丁。

向后不兼容性

• 以前，将视图显式注册为“无需权限”的哨兵（在默认权限生效时最有用）是将它显式地注册为 permission 参数的值 None，作为 repoze.bfg.configuration.Configurator.add_view 的参数。然而，在那种位置使用 None 作为“无需权限”的哨兵与 view ZCML 指令和 bfg_view 装饰器的期望不符，它们都将 None 明确传递给 add_view，覆盖了任何默认权限。症状是，如果使用 ZCML 或 bfg_view 指令注册视图，则配置的任何“默认权限”似乎不起作用（尽管直接使用 add_view 是可行的）。在 ZCML 中也无法使用 None 值作为哨兵。

  现在，“无需权限”的哨兵是字符串 __no_permission_required__，它满足 view ZCML 指令和 bfg_view 装饰器的期望，并且由于它是一个字符串，它可以在 Python 和 ZCML 中表示。

  感谢 Wichert Akkerman 提交的错误报告。

功能

• 名为 bfg_routesalchemy 的 paster 模板已被更新，以使用 SQLAlchemy 声明式语法。感谢 Ergo^。

错误修复

• 当找不到渲染器工厂时，如果渲染器名称不是字符串，则会引发误导性的错误消息。

文档

• “bfgwiki2”（SQLAlchemy + url dispatch）教程已略微更新。特别是，源包不再尝试使用私有索引，推荐的 Python 版本现在是 2.6。它还被更新以考虑用于设置环境的 bfg_routesalchemy 模板的变化。

• “bfgwiki”（ZODB + traversal）教程已略微更新。特别是，源包不再尝试使用私有索引，推荐的 Python 版本现在是 2.6。

错误修复

• 如果通过旧版set_notfound_view或set_forbidden_view API注册了异常视图，传递给视图的上下文是不正确的（可能不恰当地为None）。

功能

• 与WebOb 1.0的兼容性。

需求

• 现在需要WebOb >= 1.0。

向后不兼容性

• 由于WebOb 1.0引入的更改，repoze.bfg.request.make_request_ascii事件订阅者不再工作，因此已被删除。此订阅者旨在在部署中使用，以便在BFG 0.7.0之前编写的代码可以不变地运行。此时，此类代码需要重写以期望从request.GET、request.POST和request.params接收Unicode，或者需要将其更改以使用request.str_POST、request.str_GET和/或request.str_params代替相同的非str版本，因为这些非str版本的相同API现在始终执行解码到Unicode。

勘误

• 先前的变更日志条目声称，如果响应不是“有效”的（如果一个视图或渲染器返回了一个没有状态/标题/app_iter的响应对象），则不会向监听器发送INewResponse事件。在本版本中并非如此，在1.3a13版本中也是如此。

错误修复

• traverse路由谓词无法成功生成遍历路径。

功能

• 为了使配置“默认安全”的应用程序更容易，添加了一个默认权限功能。如果提供，则默认权限用作未指定权限的所有视图注册的权限字符串。这些API支持该功能。

  • 到配置器中添加了一个新的构造函数参数：default_permission。

  • 到配置器中添加了一个新方法：set_default_permission。

  • 添加了一个新的ZCML指令：default_permission。

• 添加一个新请求API：request.add_finished_callback。完成回调在请求处理即将结束时无条件地由路由器调用。有关更多信息，请参阅文档“挂钩”章节中的“使用完成回调”部分。

• 当路由匹配时，现在会在请求中添加一个 request.matched_route 属性。它的值是匹配的“route”对象（有关路由对象的API，请参阅 repoze.bfg.interfaces API文档中的IRoute 接口）。

• 请求的 exception 属性现在设置得稍早一些，并在一组略有不同的场景中设置，以利于“完成回调”和“响应回调”。在以前的版本中，如果找不到异常视图，请求的 exception 属性根本不会被设置。在这个版本中，当路由器捕获到异常时，即使找不到异常视图，也会立即设置 request.exception 属性。

• 配置器的 add_route 方法现在接受一个 pregenerator 参数。生成的路由的pregenerator将由 route_url 调用，以便根据特殊目的调整用户传递给它的参数集，例如 Pylons 的 'subdomain' 支持。这将影响 route_url 返回的URL。有关更多信息，请参阅 repoze.bfg.interfaces.IRoutePregenerator 接口。

向后不兼容性

• 当路由匹配时，路由器不再将值 wsgiorg.routing_args 设置到 environ 中。之前使用的值类似于 ((), matchdict)。这个功能在变更日志中只是间接提到，从未作为API进行文档记录。

• 请求的 exception 属性现在默认为 None。在先前版本中，如果在请求处理过程中用户代码没有引发异常，则请求的 request.exception 属性不存在；只有在找到异常视图后，它才开始存在。

弃用

• 事件接口 repoze.bfg.interfaces.IWSGIApplicationCreatedEvent 被重命名为 repoze.bfg.interfaces.IApplicationCreated。同样，类 repoze.bfg.events.WSGIApplicationCreatedEvent 被重命名为 repoze.bfg.events.ApplicationCreated。旧的别名将无限期继续使用。

• 事件接口 repoze.bfg.interfaces.IAfterTraversal 被重命名为 repoze.bfg.interfaces.IContextFound。同样，类 repoze.bfg.events.AfterTraversal 被重命名为 repoze.bfg.events.ContextFound。旧的别名将无限期继续使用。

• 从文档中删除了对WSGI环境值 bfg.routes.matchdict 和 bfg.routes.route 的引用。这些将在内部保留几期，但现在 request.matchdict 和 request.matched_route 是获取匹配的matchdict和路由对象的“官方”方法。

文档

• 为 default_permission ZCML指令添加了文档。

• 在配置器API文档中为 default_permission 构造函数值和 set_default_permission 方法添加了文档。

• 在“安全”章节中添加了一个名为“设置默认权限”的新部分。

• 记录了配置器构造函数的 renderer_globals_factory 和 request_factory 参数。

• 在文档的“钩子”章节中添加了两个部分：“使用响应回调”和“使用完成回调”。

• 在 repoze.bfg.request.Request API文档中添加了对 request.exception 属性的文档。

• 为“响应回调”和“完成回调”添加了词汇表条目。

• “请求处理”章节已更新，以记录完成和响应回调步骤。

• 接口API文档中新增了新接口：IRoutePregenerator。

• 在URL分配文档章节中添加了“匹配的路径”部分，详细说明了matched_route属性。

错误修复

• 修复了repoze.bfg.url.static_url URL生成中的bug：如果使用两个资源规范创建了两个不同的静态视图，但它们共享一个公共前缀，则static_url可能会生成一个错误的URL。

• 修复了repoze.bfg.static_url URL生成中的另一个bug：生成的URL中斜杠太多。

• 防止了在渲染尚未渲染过的Chameleon模板时可能导致的RuntimeError竞争条件。这种情况通常发生在重启后，当多人或线程同时尝试执行相同的视图时：[https://bugs.launchpad.net/karl3/+bug/621364](https://bugs.launchpad.net/karl3/+bug/621364)

功能

• repoze.bfg.configuration.Configurator.add_route的参数以前称为path，现在称为pattern以增强可解释性。出于向后兼容性目的，将名为path的键参数传递给add_route将无限期地工作。

• 用于ZCML route指令的path属性现在命名为pattern以增强可解释性。较旧的path属性将继续无限期地工作。

文档

• 所有指称路径模式为path的叙述、API和教程文档都已更新，现在指称它们为pattern。

• repoze.bfg.interfaces API文档页面现在通过repoze.sphinx.autointerface渲染。

• URL分配叙述章节现在引用了interfaces章节，以解释IRoute对象的API。

paste模板

• routesalchemy模板已更新，在路由声明中使用pattern而不是path。

依赖关系

• tests_require现在包括repoze.sphinx.autointerface作为依赖项。

内部

• 为Configurator添加了一个名为get_routes_mapper的API。它返回一个实现IRoutesMapper接口的对象。

• repoze.bfg.urldispatch.RoutesMapper对象现在有一个名为get_route的方法，它返回一个单个路由对象或None。

• 添加了一个新的接口repoze.bfg.interfaces.IRoute。repoze.bfg.urldispatch.Route对象实现了此接口。

• 用于从路由对象访问路由模式的规范属性现在是pattern而不是path。

• 在计算自定义路由/视图谓词的“phash”时使用hash()而不是id()，以允许自定义谓词对哪些谓词是“相等”的有些控制。

• 在repoze.bfg.request.add_global_response_headers中使用response.headerlist.append而不是response.headers.add，以防响应不是WebOb响应。

• 现在，《repoze.bfg.urldispatch.Route》构造函数（非API）接受不同的参数顺序。之前它是(pattern, name, factory=None, predicates=())。现在它是(name, pattern, factory=None, predicates=())。这是为了与configurator.add_route保持一致性。

• 现在，《repoze.bfg.urldispatch.RoutesMapper.connect》方法（非API）也接受不同的参数顺序。之前它是(pattern, name, factory=None, predicates=())。现在它是(name, pattern, factory=None, predicates=())。这是为了与configurator.add_route保持一致性。

功能

• 新增了《repoze.bfg.request.Request.add_response_callback》API。该方法在新的《repoze.bfg.request》API章节中进行了说明。它可以在创建具体的响应对象之前影响响应值。

• 《repoze.bfg.interfaces.INewResponse》接口现在包含一个request属性；因此，INewResponse的处理程序现在可以访问导致响应的请求。

• Configurator的以下方法现在允许以下命名的参数作为“点名称字符串”（例如，“foo.bar.baz”）传递，而不是作为必须导入的实际实现对象：

  setup_registry

  root_factory, authentication_policy, authorization_policy, debug_logger, locale_negotiator, request_factory, renderer_globals_factory

  add_subscriber

  subscriber, iface

  derive_view

  view

  add_view

  view, for_, context, request_type, containment

  add_route()

  view, view_for, factory, for_, view_context

  scan

  package

  add_renderer

  factory

  set_forbidden_view

  view

  set_notfound_view

  view

  set_request_factory

  factory

  set_renderer_globals_factory()

  factory

  set_locale_negotiator

  negotiator

  testing_add_subscriber

  event_iface

错误修复

• 内部注册的本地“静态视图”的路由模式（无论是通过ZCML中的“static”指令还是通过configurator的“add_static_view”方法）是错误的。它被注册为例如“static*traverse”，而它应该注册为“static/*traverse”。症状：当两个静态视图共享相同的路径前缀（例如“/static”和“/static2”）时，无法可靠地添加到系统中。

向后不兼容性

• 如果视图代码（或渲染器）返回的响应不是“真实”的响应（例如，如果没有.status，.headerlist和.app_iter属性），则现在不会向监听器发送INewResponse事件。

文档

• 为《repoze.bfg.request》模块添加API章节，其中包括《repoze.bfg.request.Request》类的文档（“请求对象”）。

• 修改“请求和响应”叙事章节，以引用新的《repoze.bfg.request》API章节。一些内容已从该章节移动到API文档本身。

• 各种更改以表示现在允许Python点名称作为Configurator方法的输入。

内部

• 使请求能够附加一个global_response_headers属性的功能（该属性假设包含一个序列的键值对，这些键值对将在稍后由路由器添加到响应中），已被删除。现在使用《repoze.bfg.request.Request.add_response_callback》的功能来替代。

• 《repoze.bfg.events.NewResponse》类的构造方式已更改：现在必须使用(request, response)来创建，而不是简单地使用(response)。

功能

• 配置器现在接受一个包的package构造参数的点分名称字符串。之前要求package参数必须是一个包对象（而不是点分名称字符串）。

• 新增了《repoze.bfg.configuration.Configurator.with_package》方法。此方法返回一个新的配置器，它使用与调用它的配置器对象相同的应用程序注册表。新的配置器将被重新创建，其package构造参数设置为传递给with_package的值。这个特性将使未来BFG版本的实现变得更加容易，允许在当前仅允许对象引用的地方使用点分名称作为参数（然而，将点分名称代替对象引用的工作尚未完成）。

• 新的《repoze.bfg.configuration.Configurator.maybe_dotted》方法将其dotted参数提供的Python点分名称字符串解析为全局Python对象。如果无法解析值，将引发一个《repoze.bfg.configuration.ConfigurationError》。如果提供的dotted值不是字符串，则无条件地返回值，而不尝试任何解析。

• 新的《repoze.bfg.configuration.Configurator.absolute_resource_spec》方法将可能相对的“资源规范”字符串解析为一个绝对版本。如果提供的relative_spec值不是字符串，则无条件地返回值，而不尝试任何解析。

向后不兼容性

• 在1.3a6中引入的、名为《repoze.bfg.renderers》中render和render_to_response的函数之前接受了一组**values参数，用于传递给渲染器的值。这是错误的，因为渲染器不需要只接受字典（它们可以接受任何类型的对象）。现在，传递给渲染器的值必须作为名为value的位置参数提供。但是，request参数仍然是一个关键字参数。

• 名为《repoze.bfg.renderers》中render和render_to_response的函数现在接受一个额外的关键字参数，名为package。

• 《repoze.bfg.renderers》中的《get_renderer》API现在接受一个package参数。

文档

• 《ZCML include》指令文档不正确：它们指定了filename而不是（正确的）file作为允许的属性。

内部

• 《repoze.bfg.resource.resolve_resource_spec》函数现在可以接受一个包对象作为其pname参数，而不是只接受包名。

• 配置器的《_renderer_factory_from_name》和《_renderer_from_name》方法已被删除。这些方法从未是API。

• 《repoze.bfg.render》中新增的《_render》、《_render_to_response》和《_make_response》函数（在1.3a6中添加）已被删除。

• 新增了一个辅助类《repoze.bfg.renderers.RendererHelper》。

• 《repoze.bfg.configuration》中的《_map_view》函数现在只接受一个renderer_name参数，而不是同时接受一个renderer和一个renderer_name参数。它现在还接受一个package参数。

• 使用 imp.get_suffixes 间接引用在 repoze.bfg.path.package_name 中，而不是硬编码的 .py、.pyc 和 .pyo 来比较，以决定一个目录是否为包。

• 使测试在 Jython 下再次可运行（尽管目前并非所有测试都通过）。

• 现在 reify 装饰器会维护其包装的函数的文档字符串。

功能

• 新的公共接口：repoze.bfg.exceptions.IExceptionResponse。此接口由所有内部异常类提供，例如 repoze.bfg.exceptions.NotFound 和 repoze.bfg.exceptions.Forbidden，其实例既是异常对象，又可以作为 WSGI 响应对象。此接口是公开的，以便异常类（也是有效的 WSGI 响应工厂）可以配置以实现它们，或者异常实例（也是或响应实例）可以配置以提供它们。

• 新的 API 类：repoze.bfg.view.AppendSlashNotFoundViewFactory。

  任何 repoze.bfg 应用程序中只能有一个“未找到”视图。即使您使用 repoze.bfg.view.append_slash_notfound_view 作为“未找到”视图，repoze.bfg 在无法重定向到带有斜杠的 URL 时仍必须生成一个 404 Not Found 响应；此未找到响应将可见于网站用户。

  如果您不关心此 404 响应的外观，并且只需要重定向到带有斜杠的路由 URL，则可以使用 repoze.bfg.view.append_slash_notfound_view 对象作为“未找到”视图。但是，如果您希望在 URL 无法重定向到带有斜杠的 URL 时使用 自定义 的 notfound 视图可调用项，则可能希望使用 repoze.bfg.view.AppendSlashNotFoundViewFactory 类的实例作为“未找到”视图，将 notfound 视图可调用项作为其构造函数的第一个参数提供。例如

  from repoze.bfg.exceptions import NotFound
  from repoze.bfg.view import AppendSlashNotFoundViewFactory
  
  def notfound_view(context, request):
      return HTTPNotFound('It aint there, stop trying!')
  
  custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
  config.add_view(custom_append_slash, context=NotFound)

  提供的 notfound_view 必须遵循 (context, request)（context 将是异常对象）的具有两个参数的视图可调用项调用约定。

文档

• 扩展了 URL 分发叙事章节中的“请求后清理”部分。

• 扩展了 URL 分发叙事章节中的“重定向到带有斜杠的路由”部分。

内部

• 以前，在配置器设置时注册了两个默认视图函数（一个名为 default_notfound_view 的用于 repoze.bfg.exceptions.NotFound，一个名为 default_forbidden_view 的用于 repoze.bfg.exceptions.Forbidden），用于渲染内部异常响应。这些默认视图函数已被删除，替换为一个通用的默认视图函数，该函数在配置器设置时注册为 repoze.bfg.interfaces.IExceptionResponse 接口，它仅返回异常实例；现在 NotFound 和 Forbidden 类仍然是异常工厂，但它们也是响应工厂，生成实现新 repoze.bfg.interfaces.IExceptionResponse 接口的实例。

功能

• repoze.bfg.configuration.Configurator.add_route API 现在返回添加的路由对象。

• 添加了 repoze.bfg.events.subscriber 装饰器。此装饰器装饰模块范围函数，然后在这些函数执行 scan() 后将它们视为事件监听器。有关更多信息，请参阅事件叙事文档章节和 repoze.bfg.events 模块文档。

错误修复

• 在添加一个尚未存在（“尚未存在”意味着，在时间上，添加了一个具有通过 add_route 添加的路线名称的视图）的路线视图时，add_view 函数的 custom_predicate 参数值丢失了。症状：在使用 URL 分派和自定义视图谓词时，视图匹配错误。

• 现在，URL 分派路由模式中的 :segment 标记的模式匹配始终至少匹配一个字符。请参阅以下更改日志中的“向后不兼容性”。

向后不兼容性

• 在 URL 匹配的正则表达式中存在一个错误。例如，URL 匹配机制会导致模式 /{foo} 匹配根 URL /，导致匹配字典为 {'foo':u''}，或者模式 /{fud}/edit 可能匹配 URL ``//edit，导致匹配字典为 {'fud':u''}。我们始终的意图是在模式中的 :segment 标记需要至少匹配 一个 字符，而不是空字符串。然而，这意味着在某些情况下，应用程序意外依赖的某些路由匹配可能不再发生。

文档

• 将 repoze.bfg.events.subscriber 装饰器的描述添加到事件章节中。

• 将 repoze.bfg.events.subscriber API 文档添加到 repoze.bfg.events API 文档中。

• 将名为“Zope 3 默认执行 'TTW' 授权检查；BFG 不执行”的章节添加到“设计防御”章节中。

功能

• repoze.bfg.configuration.Configurator.add_route 函数和 route ZCML 指令添加了新的参数：traverse。如果您希望当此路线匹配时，使 context 不是 root 对象，您可以使用 traverse 参数指定一个遍历模式。此遍历模式将用作遍历路径：遍历将从此路线隐含的根对象（全局根或与此路线关联的 factory 返回的对象）开始。

  traverse 参数的语法与 path 相同。例如，如果提供的 path 是 articles/:article/edit，并且提供的 traverse 参数是 /:article，则当请求到达并导致路线以这种方式匹配，使得 article 匹配值为 '1'（当请求 URI 是 /articles/1/edit）时，遍历路径将生成为 /1。这意味着在遍历阶段将使用名称 1 调用根对象的 __getitem__。如果 1 对象存在，它将成为请求的 context。Traversal 叙事中有更多关于遍历的信息。

  如果遍历路径包含不在路径参数中出现的段标记名称，将发生运行时错误。遍历模式不应包含不存在的段标记。

  当匹配包含路径中的 *traverse 后缀标记的路线时，也提供了类似的路由和遍历组合。遍历参数允许您在不使用 *traverse 后缀标记的情况下将路线模式与任意遍历路径关联；相反，您可以使用其他匹配信息。

  请注意，当 traverse 参数附加到一个具有 *traverse 路径剩余标记的路由时，该参数将被忽略。

• 存在一个 Configurator 的新方法： set_request_factory。如果使用该方法，则将设置由 repoze.bfg 路由器使用的工厂，以创建所有请求对象。

• Configurator 构造函数接受一个额外的参数： request_factory。如果使用该参数，则将设置由 repoze.bfg 路由器使用的工厂，以创建所有请求对象。

• Configurator 构造函数接受一个额外的参数： request_factory。如果使用该参数，则将设置由 repoze.bfg 路由器使用的工厂，以创建所有请求对象。

• 存在一个 Configurator 的新方法： set_renderer_globals_factory。如果使用该方法，则将设置由 repoze.bfg 路由器使用的工厂，以创建渲染全局变量。

• 存在一个 Configurator 的新方法： get_settings。如果使用该方法，则将返回当前的设置对象（执行与 repoze.bfg.settings.get_settings API 相同的任务）。

• Configurator 构造函数接受一个额外的参数： renderer_globals_factory。如果使用该参数，则将设置由 repoze.bfg 路由器使用的工厂，以创建渲染全局变量。

• 添加了 repoze.bfg.renderers.render、repoze.bfg.renderers.render_to_response 和 repoze.bfg.renderers.get_renderer 函数。这些是命令式 API，它们将使用与具有 renderer= 属性/参数的视图配置相同的渲染机制来生成渲染或渲染器。由于这些 API 为所有渲染提供了一个中心 API，因此它们现在成为执行命令式模板渲染的首选方式。现在不再建议使用来自 repoze.bfg.chameleon_zpt 和 repoze.bfg.chameleon_text 等模块的名为 render_* 的函数（尽管没有弃用）。现在，旧模板系统特定 API 的后端代码现在调用新的 repoze.bfg.renderer 代码。

• repoze.bfg.configuration.Configurator.testing_add_template 已重命名为 testing_add_renderer。存在一个使用旧名称的向后兼容别名。

文档

• 混合叙述章节现在包含了对 traverse 路由参数的描述。

• 钩子叙述章节现在包含有关更改请求工厂和添加渲染全局工厂的部分。

• API 文档包括一个新模块： repoze.bfg.renderers。

• 模板章节已更新；所有在示例中使用特定于模板的 API 执行渲染的叙述（例如，repoze.bfg.chameleon_zpt.render_template_to_response 方法）已更改为使用 repoze.bfg.renderers.render_* 函数。

错误修复

• 当使用名称/正则表达式对指定时，header 谓词（用作视图谓词或路由谓词）存在问题。当头不存在于头字典中时，正则表达式匹配可以提供 None，导致它抛出 TypeError: expected string or buffer 异常。现在，谓词如预期返回 False。

弃用

• repoze.bfg.renderers.rendered_response 函数从未是官方 API，但可能已被野外的扩展导入。在本版本中，它已正式弃用。请使用 repoze.bfg.renderers.render_to_response 代替。

• 以下API在文档中已被弃用（意味着它们在文档中正式弃用，但使用时不会引发弃用错误，并且可能在不定的时间内继续工作）

  在repoze.bfg.chameleon_zpt模块中：get_renderer、get_template、render_template、render_template_to_response。建议的替代方案已在那些方法的文档字符串中记录（这些文档字符串仍然存在于文档中）。

  在repoze.bfg.chameleon_text模块中：get_renderer、get_template、render_template、render_template_to_response。建议的替代方案已在那些方法的文档字符串中记录（这些文档字符串仍然存在于文档中）。

  通常，要执行与模板相关的功能，现在应使用repoze.bfg.renderers模块中的各种方法。

向后不兼容性

• 现在存在一个新的内部异常类（不是 API）名为repoze.bfg.exceptions.PredicateMismatch。当无法调用多视图的一个组成部分（由于没有谓词匹配）时，当前会引发此异常。以前，在这种情况下，会引发一个repoze.bfg.exceptions.NotFound。我们通过使repoze.bfg.exceptions.PredicateMismatch从NotFound继承来为预期在无谓词匹配时引发NotFound的代码提供向后兼容性。这将导致在谓词不匹配时调用为NotFound注册的任何异常视图，就像之前的行为一样。

  然而，存在一种不寻常的情况，将暴露向后不兼容性。如果您1）有一个注册为多视图成员的视图2）该视图明确引发一个NotFound异常以继续进行多视图中的下一个谓词检查，那么该代码现在将表现不同：而不是跳转到下一个视图匹配，将引发一个NotFound到顶级异常处理机制。依赖于视图引发NotFound以继续下一个谓词匹配的代码将是悲剧性的，但并非不可能，因为NotFound是一个公共接口。repoze.bfg.exceptions.PredicateMismatch不是一个公共API，不能由应用程序代码依赖，因此您不应该更改视图代码以引发PredicateMismatch。相反，将引发NotFound异常的逻辑从视图中移动到自定义视图谓词中。

• 如果您在BFG 1.3下运行应用程序的单元测试套件时，会引发一个命名模板的KeyError或指示“渲染器工厂”未注册的ValueError（例如，ValueError: No factory for renderer named '.pt' when looking up karl.views:templates/snippets.pt），则您可能需要在测试代码中执行一些额外的设置。

  最佳解决方案是在每个单元测试套件的代码中使用repoze.bfg.configuration.Configurator.testing_add_renderer（或，作为替代的弃用repoze.bfg.testing.registerTemplateRenderer或registerDummyRenderer）API为测试代码中使用的每个模板和渲染器注册一个“虚拟”渲染器。例如

  config = Configurator()
  config.testing_add_renderer('karl.views:templates/snippets.pt')

  这将为此特定缺失模板注册一个基本的虚拟渲染器。实际上，testing_add_renderer API会返回渲染器，但如果您不关心渲染的用法，那么您也不需要关心对它的引用。

  存在一种更粗糙的解决问题的方式。这种做法在系统测试期间使用“真实”的模板实现，这是不理想的，因为测试将运行得更慢，单元测试实际上并不是单元测试，但它更简单。始终确保你调用配置器的 setup_registry() 方法。例如

  reg = MyRegistry()
  config = Configurator(registry=reg)
  config.setup_registry()

  只有在向配置器构造函数传递 registry 参数时，调用 setup_registry 才有效。setup_registry 无论如何都会在正常操作过程中被调用，如果你没有传递 registry。

  如果你的测试套件还没有使用配置器，仍然使用较旧的 repoze.bfg.testing API 中的 setUp 或 cleanUp，这些会代表你注册渲染器。

  对于这个主题存在一个症状的变体：你可能已经尽职尽责地使用 testing_register_renderer 或 registerTemplateRenderer 为你测试的代码使用的模板注册了一个虚拟模板或渲染器，但（可能你自己也不知道）被测试的代码期望能够使用一个“真实”的模板渲染器实现来检索或渲染你忘记作为调用你正在测试的代码副作用而被渲染的另一个模板。这之所以有效，是因为在系统之前测试时找到了“真实”的模板，而现在它无法做到了。解决方案是相同的。

  使用资源规范来指定测试套件和代码中的模板路径，而不是使用相对路径，也可能有助于减少混淆。资源规范是明确的，而相对路径需要相对于“这里”进行，而“这里”并不总是有明确定义（测试套件中的“这里”可能与被测试代码中的“这里”不同）。

功能

• 新内部异常：repoze.bfg.exceptions.URLDecodeError。这是一个名为 UnicodeDecodeError 的内置 Python 异常的子类。

• 当将 URL 段解码为 Unicode 失败时，现在抛出的异常是 repoze.bfg.exceptions.URLDecodeError 而不是 UnicodeDecodeError。这使得当 repoze.bfg 无法解码 URL 时注册异常视图成为可能。

错误修复

• 修复了 repoze.bfg.configuration.Configurator.add_static_view 的回归问题。在 1.3a4 之前，包含斜杠的视图名称被支持为路由前缀。1.3a4 通过尝试将它们视为完整 URL 来破坏了这一点。

文档

• repoze.bfg.exceptions.URLDecodeError 异常被添加到 API 文档的异常章节。

向后不兼容性

• 在之前的版本中，当在遍历过程中无法将 URL 从 UTF-8 解码时，会抛出 TypeError。现在抛出的错误是一个 repoze.bfg.exceptions.URLDecodeError。

功能

• 未记录的钩子：在端件可能干扰默认版本的情况下，使 repoze.bfg.paster.BFGShellCommand 钩子的 get_app 和 get_root 可用。

• 在早期版本中，与 URL 分派路由关联的自定义路由谓词（每个传递给 repoze.bfg.configuration.Configurator.add_route 的 custom_predicates 参数的谓词函数）始终需要一个 2 个位置的参数签名，例如 (context, request)。在此发布之前，context 参数始终为 None。

  从本次发布开始，传递给谓词的第一个参数现在是一个名为 info 的字典，它包含 route 和 match。 match 也是一个字典：它表示路由匹配到的 URL 参数。 route 是一个表示匹配到的路由的对象。

  这对于需要访问路由匹配的谓词来说很有用。例如

  def any_of(segment_name, *args):
      def predicate(info, request):
          if info['match'][segment_name] in args:
              return True
      return predicate
  
  num_one_two_or_three = any_of('num, 'one', 'two', 'three')
  
  add_route('num', '/:num', custom_predicates=(num_one_two_or_three,))

  route 对象具有两个有用的属性： name 和 path。 name 属性是路由名称。 path 属性是路由模式。以下是在一组路由谓词中使用路由的示例

  def twenty_ten(info, request):
      if info['route'].name in ('ymd', 'ym', 'y'):
          return info['match']['year'] == '2010'
  
  add_route('y', '/:year', custom_predicates=(twenty_ten,))
  add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,))
  add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,))

• repoze.bfg.url.route_url API 已更改。如果传递给 route_url 的参数中存在关键字 _app_url，则此值将用作生成的 URL 的协议/主机名/端口号/前缀路径。例如，使用 _app_url 为 http://example.com:8080/foo 时，如果与 route_name 关联的路由模式展开为 /fleeb/flub，则此函数将返回 URL http://example.com:8080/foo/fleeb/flub。

• 现在可以使用 URL 作为传递给 repoze.bfg.configuration.Configurator.add_static_view 的 name 参数。当名称参数是 URL 时，repoze.bfg.url.static_url API 将生成将此 URL（作为前缀）与包括静态文件名的路径连接的 URL。这使得在生产中将静态媒体放在单独的 Web 服务器上成为可能，同时在开发期间保持静态媒体在包内并由开发 Web 服务器提供服务。

文档

• ZODB Wiki 教程（docs/tutorials/bfgwiki）的授权章节已被修改，以通过组而不是直接通过用户名进行授权（感谢 Alex Marandon）。

• SQLAlchemy Wiki 教程（docs/tutorials/bfgwiki2）的授权章节已被修改，以通过组而不是直接通过用户名进行授权。

• 将教程源的重定向请求发送到 http://docs.repoze.org/bfgwiki-1.3 和 http://docs.repoze.org/bfgwiki2-1.3/ 分别。

• 在 URL 分发叙述章节中添加了一个名为 Custom Route Predicates 的部分。

• 已更新静态资源章节，以提及使用 static_url 生成指向外部 Web 服务器的 URL。

内部

• 已移除 repoze.bfg.static.StaticURLFactory，转而使用围绕（仍然内部的）repoze.bfg.static.StaticURLInfo 辅助类的新抽象。

paste模板

• 现在，bfg_alchemy 和 bfg_routesalchemy 模板不再注册一个调用 DBSession.remove 的 handle_teardown 事件监听器。这是由 Chris Withers 发现的，被认为是不必要的。

文档

• 将“bfgwiki2”（URL 分发 Wiki）教程代码和文档中的 handle_teardown 事件监听器调用 DBSession.remove 的修改。

• 从 URL 分发叙述章节中移除了有关使用 paster 模板中的 handle_teardown 事件监听器的任何提及。

• 在 i18n 叙述文档章节中添加了一个名为“检测可用语言”的部分。

功能

• 不再需要显式注册区域设置协商者。现在无条件使用位于 repoze.bfg.i18n.default_locale_negotiator 的默认区域设置协商者，作为……嗯，默认区域设置协商者。

• 默认区域设置协商者变得更加复杂。

  • 首先，谈判者查找请求对象中的 _LOCALE_ 属性（可能由视图或事件监听器设置）。

  • 然后它查找 request.params['_LOCALE_'] 的值。

  • 然后它查找 request.cookies['_LOCALE_'] 的值。

向后不兼容性

• 默认区域设置谈判者现在查找名为 _LOCALE_ 的参数，而不是在 request.params 中名为 locale 的参数。

行为变更

• 区域设置谈判者现在可能返回 None，表示应使用默认区域设置。

文档

• 有关国际化和本地化章节中区域设置谈判的文档已更新。

• 扩展了 i18n 叙述章节的文档部分，讨论了与 gettext 文件一起工作。

功能

• 添加了“异常视图”。当你将异常（任何继承自 Python Exception 内置的类）用作视图上下文参数时，例如。

  from repoze.bfg.view import bfg_view
  from repoze.bfg.exceptions import NotFound
  from webob.exc import HTTPNotFound
  
  @bfg_view(context=NotFound)
  def notfound_view(request):
      return HTTPNotFound()

  对于上述示例，当任何视图或任何根工厂引发 repoze.bfg.exceptions.NotFound 异常时，将调用 notfound_view 视图可调用对象，并返回其响应。

  其他正常视图谓词也可以与异常视图注册结合使用。

  from repoze.bfg.view import bfg_view
  from repoze.bfg.exceptions import NotFound
  from webob.exc import HTTPNotFound
  
  @bfg_view(context=NotFound, route_name='home')
  def notfound_view(request):
      return HTTPNotFound()

  上述异常视图命名了 home 的 route_name，这意味着它仅在有名称为 home 的路由匹配时被调用。因此，对于系统中的任何给定异常，您可以为它有多个异常视图：当请求环境与视图注册匹配时，将调用“最具体”的一个。唯一不能成功使用的谓词是 name。用于查找异常视图的名称始终是空字符串。

  针对继承自 Exception 的对象注册的现有（1.3之前的）正常视图将继续工作。用于用户定义异常和作为上下文使用的系统异常的异常视图也将工作。

  此功能可用于任何视图注册机制（@bfg_view 装饰器、ZCML 或 imperative config.add_view 风格）。

  此功能由 Andrey Popp 慷慨捐赠。

• 使用“Venusian”(http://docs.repoze.org/venusian) 执行 bfg_view 装饰器扫描，而不是依赖于 BFG 内置装饰器扫描器。（说实话，Venusian 实际上只是 BFG 内置装饰器扫描器的一般化）。

• 如“国际化和本地化”章节中所述的国际化和本地化功能。

• 添加了一个名为 default_locale_name 的新部署设置。如果此字符串作为 Paster .ini 文件选项存在，则它将被视为默认区域设置名称。默认区域设置名称在语言翻译等区域相关操作中使用。

• 现在可以通过设置名为 debug_templates 的 BFG 相关 Paster .ini 文件设置来为所有 Chameleon BFG 模板打开 Chameleon 模板“调试模式”。当渲染失败时，Chameleon 模板引发的异常有时不太有用。debug_templates 允许您配置应用程序开发环境，以便 Chameleon 在模板编译和执行期间生成的异常包含更多有用的调试信息。此模式在所有新项目中默认开启。

• 为配置器添加一个名为 derive_view 的新方法，该方法可以用于从用户提供的函数、实例或类中生成一个可调用的 BFG 视图。这对于希望封装用户提供的、遵循与直接作为视图可调用对象相同的调用约定和响应约定的外部框架和插件作者非常有用。请参阅 repoze.bfg.configuration.Configurator 文档中的 derive_view 方法。

ZCML

• 添加一个 translationdir ZCML 指令以支持本地化。

• 添加一个 localenegotiator ZCML 指令以支持本地化。

弃用

• 异常视图功能取代了 Configurator 的 set_notfound_view 和 set_forbidden_view 方法，以及 notfound 和 forbidden ZCML 指令的需求。这些方法和指令在可预见的未来将继续工作，但在文档中被弃用。

依赖关系

• 添加了 venusian 发行版的安装时依赖项。

• 添加了 translationstring 发行版的安装时依赖项。

• 现在需要 Chameleon 1.2.3 或更高版本（国际化和支持模板的调试设置）。

内部

• 视图注册和查找现在使用三个“requires”参数而不是两个，以适应异常视图的正交性。

• 移除了 repoze.bfg.interfaces.IForbiddenView 和 repoze.bfg.interfaces.INotFoundView 接口；它们不是 API，并且随着异常视图的添加而变得过时。

• 删除 repoze.bfg.compat.pkgutil_26.py 并导入别名 repoze.bfg.compat.walk_packages。这些仅由内部扫描机制需要；Venusian 替换了内部扫描机制，因此它们不再需要。

文档

• 在 Hooks 叙述章节中添加了异常视图文档。

• 添加了一个名为 Internationalization and Localization 的新叙述章节。

• 修改了“环境变量和 ini 文件设置”章节：添加了关于 default_locale_name 设置的文档。

• 为 repoze.bfg.i18n 模块添加了一个新的 API 章节。

• 添加了关于新的 translationdir 和 localenegotiator ZCML 指令的文档。

• 在模板章节中添加了一个名为“模板中的更友好的异常”的部分，描述了设置 debug_templates = true 的结果。

paste模板

• 所有 paster 模板现在都会创建一个 setup.cfg，其中包含与 nose 测试和 Babel 消息目录提取/编译相关的命令。

• 为每个现有的 paster 模板添加了 default_locale_name = en 设置。

• 为每个现有的 paster 模板添加了 debug_templates = true 设置。

许可

• 在 LICENSES.txt 文件中添加了 Edgewall (BSD) 许可证，因为 repoze.bfg.i18n 中的一些代码来自 Babel 源代码。