repoze.bfg 1.3

The repoze.bfg web application framework

Support and Documentation

See the repoze.bfg website to view documentation, report bugs, and obtain support.

License

repoze.bfg is offered under the BSD-derived Repoze Public License.

Authors

repoze.bfg is made available by Agendaless Consulting and a team of contributors.

Features

• Raise more understandable error when a Jython application attempts to use a

Chameleon template.

Bug Fixes

• When a default permission was in effect, and a "static view" had

been registered (via repoze.bfg.configuration.Configurator.add_static_view, or via the static ZCML directiveq), the static view, was, by default, protected by the default permission, without a way to indicate that it was anonymously viewable. As of this release, a static view is registered using the permission sentinel __no_permission_required__ as the permission by default, making its resources viewable by completely anonymous users.

Features

• A permission argument has been added to the

repoze.bfg.configuration.Configurator.add_static_view method and a permission attribute is now available on the static ZCML directive.

Documentation

• A "default permission" glossary entry was added to the glossary.

Bug Fixes

• The repoze.bfg.security.view_execution_permitted API could

return the wrong boolean result due to a bug in the configurator, leading to inappropriate view execution by persons without permission when it was imported and used directly. Thanks to Shane Hathaway for a bug report and a patch.

Backwards Incompatibilities

• Previously, the sentinel to register a view as explicitly "no

permission required" (most useful when a default permission is in effect) was to register it explicitly with the value None as an argument to the permission parameter of the repoze.bfg.configuration.Configurator.add_view. Using None as a sentinel meaning "no permission required" in that location, however, was incompatible with the expectations of both the view ZCML directive and the bfg_view decorator, which both passed None explicitly to add_view, overriding any default permission. The symptom was that any "default permission" configured appeared to not work if either ZCML or the bfg_view directive was used to register a view (although using add_view directly did work). The None value as a sentinel could also not be spelled using ZCML.

Now, the sentinel meaning "no permission required" is the string __no_permission_required__, which satisfies the expectation of the view ZCML directive and the bfg_view decorator, and, since it's a string, it can be spelled in both Python and within ZCML.

Thanks to Wichert Akkerman for the bug report.

Features

• The paster template named bfg_routesalchemy has been updated

to use SQLAlchemy declarative syntax. Thanks to Ergo^.

Bug Fixes

• When a renderer factory could not be found, a misleading error

message was raised if the renderer name was not a string.

Documentation

• The ""bfgwiki2" (SQLAlchemy + url dispatch) tutorial has been

updated slightly. In particular, the source packages no longer attempt to use a private index, and the recommended Python version is now 2.6. It was also updated to take into account the changes to the bfg_routesalchemy template used to set up an environment.

• The "bfgwiki" (ZODB + traversal) tutorial has been updated slightly.

In particular, the source packages no longer attempt to use a private index, and the recommended Python version is now 2.6.

Features

• The repoze.bfg.traversal.traversal_path API now eagerly attempts

to encode a Unicode path into ASCII before attempting to split it and decode its segments. This is for convenience, effectively to allow a (stored-as-Unicode-in-a-database, or retrieved-as-Unicode-from-a-request-parameter) Unicode path to be passed to find_model, which eventually internally uses the traversal_path function under the hood. In version 1.2 and prior, if the path was Unicode, that Unicode was split on slashes and each resulting segment value was Unicode. An inappropriate call to the decode() method of a resulting Unicode path segment could cause a UnicodeDecodeError to occur even if the Unicode representation of the path contained no 'high order' characters (it effectively did a "double decode"). By converting the Unicode path argument to ASCII before we attempt to decode and split, genuine errors will occur in a more obvious place while also allowing us to handle (for convenience) the case that it's a Unicode representation formed entirely from ASCII-compatible characters.

Bug Fixes

• If an exception view was registered through the legacy

set_notfound_view or set_forbidden_view APIs, the context sent to the view was incorrect (could be None inappropriately).

Features

• Compatibility with WebOb 1.0.

Requirements

• Now requires WebOb >= 1.0.

Backwards Incompatibilities

• Due to changes introduced WebOb 1.0, the

repoze.bfg.request.make_request_ascii event subscriber no longer works, so it has been removed. This subscriber was meant to be used in a deployment so that code written before BFG 0.7.0 could run unchanged. At this point, such code will need to be rewritten to expect Unicode from request.GET, request.POST and request.params or it will need to be changed to use request.str_POST, request.str_GET and/or request.str_params instead of the non-str versions of same, as the non-str versions of the same APIs always now perform decoding to Unicode.

Errata

• A prior changelog entry asserted that the INewResponse event was

not sent to listeners if the response was not "valid" (if a view or renderer returned a response object that did not have a status/headers/app_iter). This is not true in this release, nor was it true in 1.3a13.

Bug Fixes

• The traverse route predicate could not successfully generate a

traversal path.

Features

• In support of making it easier to configure applications which are

"secure by default", a default permission feature was added. If supplied, the default permission is used as the permission string to all view registrations which don't otherwise name a permission. These APIs are in support of that:

• A new constructor argument was added to the Configurator:

default_permission.

• A new method was added to the Configurator:

set_default_permission.

• A new ZCML directive was added: default_permission.
• Add a new request API: request.add_finished_callback. Finished

callbacks are called by the router unconditionally near the very end of request processing. See the "Using Finished Callbacks" section of the "Hooks" narrative chapter of the documentation for more information.

• A request.matched_route attribute is now added to the request

when a route has matched. Its value is the "route" object that matched (see the IRoute interface within repoze.bfg.interfaces API documentation for the API of a route object).

• The exception attribute of the request is now set slightly

earlier and in a slightly different set of scenarios, for benefit of "finished callbacks" and "response callbacks". In previous versions, the exception attribute of the request was not set at all if an exception view was not found. In this version, the request.exception attribute is set immediately when an exception is caught by the router, even if an exception view could not be found.

• The add_route method of a Configurator now accepts a

pregenerator argument. The pregenerator for the resulting route is called by route_url in order to adjust the set of arguments passed to it by the user for special purposes, such as Pylons 'subdomain' support. It will influence the URL returned by route_url. See the repoze.bfg.interfaces.IRoutePregenerator interface for more information.

Backwards Incompatibilities

• The router no longer sets the value wsgiorg.routing_args into

the environ when a route matches. The value used to be something like ((), matchdict). This functionality was only ever obliquely referred to in change logs; it was never documented as an API.

• The exception attribute of the request now defaults to None.

In prior versions, the request.exception attribute did not exist if an exception was not raised by user code during request processing; it only began existence once an exception view was found.

Deprecations

• The repoze.bfg.interfaces.IWSGIApplicationCreatedEvent event

interface was renamed to repoze.bfg.interfaces.IApplicationCreated. Likewise, the repoze.bfg.events.WSGIApplicationCreatedEvent class was renamed to repoze.bfg.events.ApplicationCreated. The older aliases will continue to work indefinitely.

• The repoze.bfg.interfaces.IAfterTraversal event interface was

renamed to repoze.bfg.interfaces.IContextFound. Likewise, the repoze.bfg.events.AfterTraversal class was renamed to repoze.bfg.events.ContextFound. The older aliases will continue to work indefinitely.

• References to the WSGI environment values bfg.routes.matchdict

and bfg.routes.route were removed from documentation. These will stick around internally for several more releases, but it is request.matchdict and request.matched_route are now the "official" way to obtain the matchdict and the route object which resulted in the match.

Documentation

• Added documentation for the default_permission ZCML directive.
• Added documentation for the default_permission constructor value

and the set_default_permission method in the Configurator API documentation.

• Added a new section to the "security" chapter named "Setting a

Default Permission".

• Document renderer_globals_factory and request_factory

arguments to Configurator constructor.

• Added two sections to the "Hooks" chapter of the documentation:

"Using Response Callbacks" and "Using Finished Callbacks".

• Added documentation of the request.exception attribute to the

repoze.bfg.request.Request API documentation.

• Added glossary entries for "response callback" and "finished

callback".

• The "Request Processing" narrative chapter has been updated to note

finished and response callback steps.

• New interface in interfaces API documentation: IRoutePregenerator.
• Added a "The Matched Route" section to the URL Dispatch narrative

docs chapter, detailing the matched_route attribute.

Bug Fixes

• Fix a bug in repoze.bfg.url.static_url URL generation: if two

resource specifications were used to create two separate static views, but they shared a common prefix, it was possible that static_url would generate an incorrect URL.

• Fix another bug in repoze.bfg.static_url URL generation: too

many slashes in generated URL.

• Prevent a race condition which could result in a RuntimeError

when rendering a Chameleon template that has not already been rendered once. This would usually occur directly after a restart, when more than one person or thread is trying to execute the same view at the same time: https://bugs.launchpad.net/karl3/+bug/621364

Features

• The argument to repoze.bfg.configuration.Configurator.add_route

which was previously called path is now called pattern for better explicability. For backwards compatibility purposes, passing a keyword argument named path to add_route will still work indefinitely.

• The path attribute to the ZCML route directive is now named

pattern for better explicability. The older path attribute will continue to work indefinitely.

Documentation

• All narrative, API, and tutorial docs which referred to a route

pattern as a path have now been updated to refer to them as a pattern.

• The repoze.bfg.interfaces API documentation page is now rendered

via repoze.sphinx.autointerface.

• The URL Dispatch narrative chapter now refers to the interfaces

chapter to explain the API of an IRoute object.

Paster Templates

• The routesalchemy template has been updated to use pattern in

its route declarations rather than path.

Dependencies

• tests_require now includes repoze.sphinx.autointerface as a

dependency.

Internal

• Add an API to the Configurator named get_routes_mapper.

This returns an object implementing the IRoutesMapper interface.

• The repoze.bfg.urldispatch.RoutesMapper object now has a

get_route method which returns a single Route object or None.

• A new interface repoze.bfg.interfaces.IRoute was added. The

repoze.bfg.urldispatch.Route object implements this interface.

• The canonical attribute for accessing the routing pattern from a

route object is now pattern rather than path.

• Use hash() rather than id() when computing the "phash" of a

custom route/view predicate in order to allow the custom predicate some control over which predicates are "equal".

• Use response.headerlist.append instead of

response.headers.add in repoze.bfg.request.add_global_response_headers in case the response is not a WebOb response.

• The repoze.bfg.urldispatch.Route constructor (not an API) now

accepts a different ordering of arguments. Previously it was (pattern, name, factory=None, predicates=()). It is now (name, pattern, factory=None, predicates=()). This is in support of consistency with configurator.add_route.

• The repoze.bfg.urldispatch.RoutesMapper.connect method (not an

API) now accepts a different ordering of arguments. Previously it was (pattern, name, factory=None, predicates=()). It is now (name, pattern, factory=None, predicates=()). This is in support of consistency with configurator.add_route.

Bug Fixes

• Process the response callbacks and the NewResponse event earlier, to

enable mutations to the response to take effect.

Features

• A new repoze.bfg.request.Request.add_response_callback API has

been added. This method is documented in the new repoze.bfg.request API chapter. It can be used to influence response values before a concrete response object has been created.

• The repoze.bfg.interfaces.INewResponse interface now includes a

request attribute; as a result, a handler for INewResponse now has access to the request which caused the response.

• Each of the follow methods of the Configurator now allow the

below-named arguments to be passed as "dotted name strings" (e.g. "foo.bar.baz") rather than as actual implementation objects that must be imported:

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

Bug Fixes

• The route pattern registered internally for a a local "static view"

(either via the static ZCML directive or via the add_static_view method of the configurator) was incorrect. It was regsistered for e.g. static*traverse, while it should have been registered for static/*traverse. Symptom: two static views could not reliably be added to a system when they both shared the same path prefix (e.g. /static and /static2).

Backwards Incompatibilities

• The INewResponse event is now not sent to listeners if the response

returned by view code (or a renderer) is not a "real" response (e.g. if it does not have .status, .headerlist and .app_iter attribtues).

Documentation

• Add an API chapter for the repoze.bfg.request module, which

includes documentation for the repoze.bfg.request.Request class (the "request object").

• Modify the "Request and Response" narrative chapter to reference the

new repoze.bfg.request API chapter. Some content was moved from this chapter into the API documentation itself.

• Various changes to denote that Python dotted names are now allowed

as input to Configurator methods.

Internal

• The (internal) feature which made it possible to attach a

global_response_headers attribute to the request (which was assumed to contain a sequence of header key/value pairs which would later be added to the response by the router), has been removed. The functionality of repoze.bfg.request.Request.add_response_callback takes its place.

• The repoze.bfg.events.NewResponse class's construct has changed:

it now must be created with (request, response) rather than simply (response).

Features

• The Configurator now accepts a dotted name string to a package as

a package constructor argument. The package argument was previously required to be a package object (not a dotted name string).

• The repoze.bfg.configuration.Configurator.with_package method

was added. This method returns a new Configurator using the same application registry as the configurator object it is called upon. The new configurator is created afresh with its package constructor argument set to the value passed to with_package. This feature will make it easier for future BFG versions to allow dotted names as arguments in places where currently only object references are allowed (the work to allow dotted names isntead of object references everywhere has not yet been done, however).

• The new repoze.bfg.configuration.Configurator.maybe_dotted

method resolves a Python dotted name string supplied as its dotted argument to a global Python object. If the value cannot be resolved, a repoze.bfg.configuration.ConfigurationError is raised. If the value supplied as dotted is not a string, the value is returned unconditionally without any resolution attempted.

• The new

repoze.bfg.configuration.Configurator.absolute_resource_spec method resolves a potentially relative "resource specification" string into an absolute version. If the value supplied as relative_spec is not a string, the value is returned unconditionally without any resolution attempted.

Backwards Incompatibilities

• The functions in repoze.bfg.renderers named render and

render_to_response introduced in 1.3a6 previously took a set of **values arguments for the values to be passed to the renderer. This was wrong, as renderers don't need to accept only dictionaries (they can accept any type of object). Now, the value sent to the renderer must be supplied as a positional argument named value. The request argument is still a keyword argument, however.

• The functions in repoze.bfg.renderers named render and

render_to_response now accept an additonal keyword argument named package.

• The get_renderer API in repoze.bfg.renderers now accepts a

package argument.

Documentation

• The ZCML include directive docs were incorrect: they specified

filename rather than (the correct) file as an allowable attribute.

Internal

• The repoze.bfg.resource.resolve_resource_spec function can now

accept a package object as its pname argument instead of just a package name.

• The _renderer_factory_from_name and _renderer_from_name

methods of the Configurator were removed. These were never APIs.

• The _render, _render_to_response and _make_response

functions with repoze.bfg.render (added in 1.3a6) have been removed.

• A new helper class repoze.bfg.renderers.RendererHelper was

added.

• The _map_view function of repoze.bfg.configuration now takes

only a renderer_name argument instead of both a renderer and renderer``_name argument.  It also takes a ``package argument now.

• Use imp.get_suffixes indirection in

repoze.bfg.path.package_name instead of hardcoded .py .pyc and .pyo to use for comparison when attemtping to decide if a directory is a package.

• Make tests runnable again under Jython (although they do not all

pass currently).

• The reify decorator now maintains the docstring of the function it

wraps.

Features

• New public interface: repoze.bfg.exceptions.IExceptionResponse.

This interface is provided by all internal exception classes (such as repoze.bfg.exceptions.NotFound and repoze.bfg.exceptions.Forbidden), instances of which are both exception objects and can behave as WSGI response objects. This interface is made public so that exception classes which are also valid WSGI response factories can be configured to implement them or exception instances which are also or response instances can be configured to provide them.

• New API class: repoze.bfg.view.AppendSlashNotFoundViewFactory.

There can only be one Not Found view in any repoze.bfg application. Even if you use repoze.bfg.view.append_slash_notfound_view as the Not Found view, repoze.bfg still must generate a 404 Not Found response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users.

If you don't care what this 404 response looks like, and you only need redirections to slash-appended route URLs, you may use the repoze.bfg.view.append_slash_notfound_view object as the Not Found view. However, if you wish to use a custom notfound view callable when a URL cannot be redirected to a slash-appended URL, you may wish to use an instance of the repoze.bfg.view.AppendSlashNotFoundViewFactory class as the Not Found view, supplying the notfound view callable as the first argument to its constructor. For instance:

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)

The notfound_view supplied must adhere to the two-argument view callable calling convention of (context, request) (context will be the exception object).

Documentation

• Expanded the "Cleaning Up After a Request" section of the URL

Dispatch narrative chapter.

• Expanded the "Redirecting to Slash-Appended Routes" section of the

URL Dispatch narrative chapter.

Internal

• Previously, two default view functions were registered at

Configurator setup (one for repoze.bfg.exceptions.NotFound named default_notfound_view and one for repoze.bfg.exceptions.Forbidden named default_forbidden_view) to render internal exception responses. Those default view functions have been removed, replaced with a generic default view function which is registered at Configurator setup for the repoze.bfg.interfaces.IExceptionResponse interface that simply returns the exception instance; the NotFound and Forbidden classes are now still exception factories but they are also response factories which generate instances that implement the new repoze.bfg.interfaces.IExceptionResponse interface.

Features

• The repoze.bfg.configuration.Configurator.add_route API now

returns the route object that was added.

• A repoze.bfg.events.subscriber decorator was added. This

decorator decorates module-scope functions, which are then treated as event listeners after a scan() is performed. See the Events narrative documentation chapter and the repoze.bfg.events module documentation for more information.

Bug Fixes

• When adding a view for a route which did not yet exist ("did not yet

exist" meaning, temporally, a view was added with a route name for a route which had not yet been added via add_route), the value of the custom_predicate argument to add_view was lost. Symptom: wrong view matches when using URL dispatch and custom view predicates together.

• Pattern matches for a :segment marker in a URL dispatch route

pattern now always match at least one character. See "Backwards Incompatibilities" below in this changelog.

Backwards Incompatibilities

• A bug existed in the regular expression to do URL matching. As an

example, the URL matching machinery would cause the pattern /{foo} to match the root URL / resulting in a match dictionary of {'foo':u''} or the pattern /{fud}/edit might match the URL ``//edit resulting in a match dictionary of {'fud':u''}. It was always the intent that :segment markers in the pattern would need to match at least one character, and never match the empty string. This, however, means that in certain circumstances, a routing match which your application inadvertently depended upon may no longer happen.

Documentation

• Added description of the repoze.bfg.events.subscriber decorator

to the Events narrative chapter.

• Added repoze.bfg.events.subscriber API documentation to

repoze.bfg.events API docs.

• Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By

Default; BFG Does Not" to the "Design Defense" chapter.

Features

• New argument to repoze.bfg.configuration.Configurator.add_route

and the route ZCML directive: traverse. If you would like to cause the context to be something other than the root object when this route matches, you can spell a traversal pattern as the traverse argument. This traversal pattern will be used as the traversal path: traversal will begin at the root object implied by this route (either the global root, or the object returned by the factory associated with this route).

The syntax of the traverse argument is the same as it is for path. For example, if the path provided is articles/:article/edit, and the traverse argument provided is /:article, when a request comes in that causes the route to match in such a way that the article match value is '1' (when the request URI is /articles/1/edit), the traversal path will be generated as /1. This means that the root object's __getitem__ will be called with the name 1 during the traversal phase. If the 1 object exists, it will become the context of the request. The Traversal narrative has more information about traversal.

If the traversal path contains segment marker names which are not present in the path argument, a runtime error will occur. The traverse pattern should not contain segment markers that do not exist in the path.

A similar combining of routing and traversal is available when a route is matched which contains a *traverse remainder marker in its path. The traverse argument allows you to associate route patterns with an arbitrary traversal path without using a a *traverse remainder marker; instead you can use other match information.

Note that the traverse argument is ignored when attached to a route that has a *traverse remainder marker in its path.

• A new method of the Configurator exists:

set_request_factory. If used, this method will set the factory used by the repoze.bfg router to create all request objects.

• The Configurator constructor takes an additional argument:

request_factory. If used, this argument will set the factory used by the repoze.bfg router to create all request objects.

• The Configurator constructor takes an additional argument:

request_factory. If used, this argument will set the factory used by the repoze.bfg router to create all request objects.

• A new method of the Configurator exists:

set_renderer_globals_factory. If used, this method will set the factory used by the repoze.bfg router to create renderer globals.

• A new method of the Configurator exists: get_settings. If

used, this method will return the current settings object (performs the same job as the repoze.bfg.settings.get_settings API).

• The Configurator constructor takes an additional argument:

renderer_globals_factory. If used, this argument will set the factory used by the repoze.bfg router to create renderer globals.

• Add repoze.bfg.renderers.render,

repoze.bfg.renderers.render_to_response and repoze.bfg.renderers.get_renderer functions. These are imperative APIs which will use the same rendering machinery used by view configurations with a renderer= attribute/argument to produce a rendering or renderer. Because these APIs provide a central API for all rendering, they now form the preferred way to perform imperative template rendering. Using functions named render_* from modules such as repoze.bfg.chameleon_zpt and repoze.bfg.chameleon_text is now discouraged (although not deprecated). The code the backing older templating-system-specific APIs now calls into the newer repoze.bfg.renderer code.

• The repoze.bfg.configuration.Configurator.testing_add_template

has been renamed to testing_add_renderer. A backwards compatibility alias is present using the old name.

Documentation

• The Hybrid narrative chapter now contains a description of the

traverse route argument.

• The Hooks narrative chapter now contains sections about

changing the request factory and adding a renderer globals factory.

• The API documentation includes a new module:

repoze.bfg.renderers.

• The Templates chapter was updated; all narrative that used

templating-specific APIs within examples to perform rendering (such as the repoze.bfg.chameleon_zpt.render_template_to_response method) was changed to use repoze.bfg.renderers.render_* functions.

Bug Fixes

• The header predicate (when used as either a view predicate or a

route predicate) had a problem when specified with a name/regex pair. When the header did not exist in the headers dictionary, the regex match could be fed None, causing it to throw a TypeError: expected string or buffer exception. Now, the predicate returns False as intended.

Deprecations

• The repoze.bfg.renderers.rendered_response function was never an

official API, but may have been imported by extensions in the wild. It is officially deprecated in this release. Use repoze.bfg.renderers.render_to_response instead.

• The following APIs are documentation deprecated (meaning they are

officially deprecated in documentation but do not raise a deprecation error upon their usage, and may continue to work for an indefinite period of time):

In the repoze.bfg.chameleon_zpt module: get_renderer, get_template, render_template, render_template_to_response. The suggested alternatives are documented within the docstrings of those methods (which are still present in the documentation).

In the repoze.bfg.chameleon_text module: get_renderer, get_template, render_template, render_template_to_response. The suggested alternatives are documented within the docstrings of those methods (which are still present in the documentation).

In general, to perform template-related functions, one should now use the various methods in the repoze.bfg.renderers module.

Backwards Incompatibilities

• A new internal exception class (not an API) named

repoze.bfg.exceptions.PredicateMismatch now exists. This exception is currently raised when no constituent view of a multiview can be called (due to no predicate match). Previously, in this situation, a repoze.bfg.exceptions.NotFound was raised. We provide backwards compatibility for code that expected a NotFound to be raised when no predicates match by causing repoze.bfg.exceptions.PredicateMismatch to inherit from NotFound. This will cause any exception view registered for NotFound to be called when a predicate mismatch occurs, as was the previous behavior.

There is however, one perverse case that will expose a backwards incompatibility. If 1) you had a view that was registered as a member of a multiview 2) this view explicitly raised a NotFound exception in order to proceed to the next predicate check in the multiview, that code will now behave differently: rather than skipping to the next view match, a NotFound will be raised to the top-level exception handling machinery instead. For code to be depending upon the behavior of a view raising NotFound to proceed to the next predicate match, would be tragic, but not impossible, given that NotFound is a public interface. repoze.bfg.exceptions.PredicateMismatch is not a public API and cannot be depended upon by application code, so you should not change your view code to raise PredicateMismatch. Instead, move the logic which raised the NotFound exception in the view out into a custom view predicate.

• If, when you run your application's unit test suite under BFG 1.3, a

KeyError naming a template or a ValueError indicating that a 'renderer factory' is not registered may is raised (e.g. ValueError: No factory for renderer named '.pt' when looking up karl.views:templates/snippets.pt), you may need to perform some extra setup in your test code.

The best solution is to use the repoze.bfg.configuration.Configurator.testing_add_renderer (or, alternately the deprecated repoze.bfg.testing.registerTemplateRenderer or registerDummyRenderer) API within the code comprising each individual unit test suite to register a "dummy" renderer for each of the templates and renderers used by code under test. For example:

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

This will register a basic dummy renderer for this particular missing template. The testing_add_renderer API actually returns the renderer, but if you don't care about how the render is used, you don't care about having a reference to it either.

A more rough way to solve the issue exists. It causes the "real" template implementations to be used while the system is under test, which is suboptimal, because tests will run slower, and unit tests won't actually be unit tests, but it is easier. Always ensure you call the setup_registry() method of the Configurator . Eg:

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

Calling setup_registry only has an effect if you're passing in a registry argument to the Configurator constructor. setup_registry is called by the course of normal operations anyway if you do not pass in a registry.

If your test suite isn't using a Configurator yet, and is still using the older repoze.bfg.testing APIs name setUp or cleanUp, these will register the renderers on your behalf.

A variant on the symptom for this theme exists: you may already be dutifully registering a dummy template or renderer for a template used by the code you're testing using testing_register_renderer or registerTemplateRenderer, but (perhaps unbeknownst to you) the code under test expects to be able to use a "real" template renderer implementation to retrieve or render another template that you forgot was being rendered as a side effect of calling the code you're testing. This happened to work because it found the real template while the system was under test previously, and now it cannot. The solution is the same.

It may also help reduce confusion to use a resource specification to specify the template path in the test suite and code rather than a relative path in either. A resource specification is unambiguous, while a relative path needs to be relative to "here", where "here" isn't always well-defined ("here" in a test suite may or may not be the same as "here" in the code under test).

Features

• New internal exception: repoze.bfg.exceptions.URLDecodeError.

This URL is a subclass of the built-in Python exception named UnicodeDecodeError.

• When decoding a URL segment to Unicode fails, the exception raised

is now repoze.bfg.exceptions.URLDecodeError instead of UnicodeDecodeError. This makes it possible to register an exception view invoked specifically when repoze.bfg cannot decode a URL.

Bug Fixes

• Fix regression in

repoze.bfg.configuration.Configurator.add_static_view. Before 1.3a4, view names that contained a slash were supported as route prefixes. 1.3a4 broke this by trying to treat them as full URLs.

Documentation

• The repoze.bfg.exceptions.URLDecodeError exception was added to

the exceptions chapter of the API documentation.

Backwards Incompatibilities

• in previous releases, when a URL could not be decoded from UTF-8

during traversal, a TypeError was raised. Now the error which is raised is a repoze.bfg.exceptions.URLDecodeError.

Features

• Undocumented hook: make get_app and get_root of the

repoze.bfg.paster.BFGShellCommand hookable in cases where endware may interfere with the default versions.

• In earlier versions, a custom route predicate associated with a url

dispatch route (each of the predicate functions fed to the custom_predicates argument of repoze.bfg.configuration.Configurator.add_route) has always required a 2-positional argument signature, e.g. (context, request). Before this release, the context argument was always None.

As of this release, the first argument passed to a predicate is now a dictionary conventionally named info consisting of route, and match. match is a dictionary: it represents the arguments matched in the URL by the route. route is an object representing the route which was matched.

This is useful when predicates need access to the route match. For example:

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,))

The route object is an object that has two useful attributes: name and path. The name attribute is the route name. The path attribute is the route pattern. An example of using the route in a set of route predicates:

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,))

• The repoze.bfg.url.route_url API has changed. If a keyword

_app_url is present in the arguments passed to route_url, this value will be used as the protocol/hostname/port/leading path prefix of the generated URL. For example, using an _app_url of http://example.com:8080/foo would cause the URL http://example.com:8080/foo/fleeb/flub to be returned from this function if the expansion of the route pattern associated with the route_name expanded to /fleeb/flub.

• It is now possible to use a URL as the name argument fed to

repoze.bfg.configuration.Configurator.add_static_view. When the name argument is a URL, the repoze.bfg.url.static_url API will generate join this URL (as a prefix) to a path including the static file name. This makes it more possible to put static media on a separate webserver for production, while keeping static media package-internal and served by the development webserver during development.

Documentation

• The authorization chapter of the ZODB Wiki Tutorial

(docs/tutorials/bfgwiki) was changed to demonstrate authorization via a group rather than via a direct username (thanks to Alex Marandon).

• The authorization chapter of the SQLAlchemy Wiki Tutorial

(docs/tutorials/bfgwiki2) was changed to demonstrate authorization via a group rather than via a direct username.

• Redirect requests for tutorial sources to

http://docs.repoze.org/bfgwiki-1.3 and http://docs.repoze.org/bfgwiki2-1.3/ respectively.

• A section named Custom Route Predicates was added to the URL

Dispatch narrative chapter.

• The Static Resources chapter has been updated to mention using

static_url to generate URLs to external webservers.

Internal

• Removed repoze.bfg.static.StaticURLFactory in favor of a new

abstraction revolving around the (still-internal) repoze.bfg.static.StaticURLInfo helper class.

Paster Templates

• The bfg_alchemy and bfg_routesalchemy templates no longer

register a handle_teardown event listener which calls DBSession.remove. This was found by Chris Withers to be unnecessary.

Documentation

• The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation

was changed to remove the handle_teardown event listener which calls DBSession.remove.

• Any mention of the handle_teardown event listener as used by the

paster templates was removed from the URL Dispatch narrative chapter.

• A section entitled Detecting Available Languages was added to the

i18n narrative docs chapter.

Features

• A locale negotiator no longer needs to be registered explicitly. The

default locale negotiator at repoze.bfg.i18n.default_locale_negotiator is now used unconditionally as... um, the default locale negotiator.

• The default locale negotiator has become more complex.

• First, the negotiator looks for the _LOCALE_ attribute of

the request object (possibly set by a view or an event listener).

• Then it looks for the request.params['_LOCALE_'] value.
• Then it looks for the request.cookies['_LOCALE_'] value.

Backwards Incompatibilities

• The default locale negotiator now looks for the parameter named

_LOCALE_ rather than a parameter named locale in request.params.

Behavior Changes

• A locale negotiator may now return None, signifying that the

default locale should be used.

Documentation

• Documentation concerning locale negotiation in the

Internationalizationa and Localization chapter was updated.

• Expanded portion of i18n narrative chapter docs which discuss

working with gettext files.

Features

• Added "exception views". When you use an exception (anything that

inherits from the Python Exception builtin) as view context argument, e.g.:

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()

For the above example, when the repoze.bfg.exceptions.NotFound exception is raised by any view or any root factory, the notfound_view view callable will be invoked and its response returned.

Other normal view predicates can also be used in combination with an exception view registration:

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()

The above exception view names the route_name of home, meaning that it will only be called when the route matched has a name of home. You can therefore have more than one exception view for any given exception in the system: the "most specific" one will be called when the set of request circumstances which match the view registration. The only predicate that cannot be not be used successfully is name. The name used to look up an exception view is always the empty string.

Existing (pre-1.3) normal views registered against objects inheriting from Exception will continue to work. Exception views used for user-defined exceptions and system exceptions used as contexts will also work.

The feature can be used with any view registration mechanism (@bfg_view decorator, ZCML, or imperative config.add_view styles).

This feature was kindly contributed by Andrey Popp.

• Use "Venusian" (`http://docs.repoze.org/venusian

  System Message: WARNING/2 (<string>, line 1246); backlink

  Inline interpreted text or phrase reference start-string without end-string.

<http://docs.repoze.org/venusian>`_) to perform bfg_view decorator scanning rather than relying on a BFG-internal decorator scanner. (Truth be told, Venusian is really just a generalization of the BFG-internal decorator scanner).

• Internationalization and localization features as documented in the

narrative documentation chapter entitled Internationalization and Localization.

• A new deployment setting named default_locale_name was added.

If this string is present as a Paster .ini file option, it will be considered the default locale name. The default locale name is used during locale-related operations such as language translation.

• It is now possible to turn on Chameleon template "debugging mode"

for all Chameleon BFG templates by setting a BFG-related Paster .ini file setting named debug_templates. The exceptions raised by Chameleon templates when a rendering fails are sometimes less than helpful. debug_templates allows you to configure your application development environment so that exceptions generated by Chameleon during template compilation and execution will contain more helpful debugging information. This mode is on by default in all new projects.

• Add a new method of the Configurator named derive_view which can

be used to generate a BFG view callable from a user-supplied function, instance, or class. This useful for external framework and plugin authors wishing to wrap callables supplied by their users which follow the same calling conventions and response conventions as objects that can be supplied directly to BFG as a view callable. See the derive_view method in the repoze.bfg.configuration.Configurator docs.

ZCML

• Add a translationdir ZCML directive to support localization.
• Add a localenegotiator ZCML directive to support localization.

Deprecations

• The exception views feature replaces the need for the

set_notfound_view and set_forbidden_view methods of the Configurator as well as the notfound and forbidden ZCML directives. Those methods and directives will continue to work for the foreseeable future, but they are deprecated in the documentation.

Dependencies

• A new install-time dependency on the venusian distribution was

added.

• A new install-time dependency on the translationstring

distribution was added.

• Chameleon 1.2.3 or better is now required (internationalization and

per-template debug settings).

Internal

• View registrations and lookups are now done with three "requires"

arguments instead of two to accomodate orthogonality of exception views.

• The repoze.bfg.interfaces.IForbiddenView and

repoze.bfg.interfaces.INotFoundView interfaces were removed; they weren't APIs and they became vestigial with the addition of exception views.

• Remove repoze.bfg.compat.pkgutil_26.py and import alias

repoze.bfg.compat.walk_packages. These were only required by internal scanning machinery; Venusian replaced the internal scanning machinery, so these are no longer required.

Documentation

• Exception view documentation was added to the Hooks narrative

chapter.

• A new narrative chapter entitled ``Internationalization and

  System Message: WARNING/2 (<string>, line 1332); backlink

  Inline literal start-string without end-string.

Localization`` was added.

• The "Environment Variables and ini File Settings" chapter was

changed: documentation about the default_locale_name setting was added.

• A new API chapter for the repoze.bfg.i18n module was added.
• Documentation for the new translationdir and

localenegotiator ZCML directives were added.

• A section was added to the Templates chapter entitled "Nicer

Exceptions in Templates" describing the result of setting debug_templates = true.

Paster Templates

• All paster templates now create a setup.cfg which includes

commands related to nose testing and Babel message catalog extraction/compilation.

• A default_locale_name = en setting was added to each existing paster

template.

• A debug_templates = true setting was added to each existing

paster template.

Licensing

• The Edgewall (BSD) license was added to the LICENSES.txt file, as

some code in the repoze.bfg.i18n derives from Babel source.