Python 3 would use __len__ to find truthiness; this usually caused an instance of DummyResource to be “falsy” instead of “truthy”. See https://github.com/Pylons/pyramid/pull/1032
Small microspeed enhancement which anticipates that a pyramid.response.Response object is likely to be returned from a view. Some code is shortcut if the class of the object returned by a view is this class. A similar microoptimization was done to pyramid.request.Request.is_response.
Make it possible to use variable arguments on p* commands (pserve, pshell, pviews, etc) in the form a=1 b=2 so you can fill in values in parameterized .ini file, e.g. pshell etc/development.ini http_port=8080. See https://github.com/Pylons/pyramid/pull/714
A somewhat advanced and obscure feature of Pyramid event handlers is their ability to handle “multi-interface” notifications. These notifications have traditionally presented multiple objects to the subscriber callable. For instance, if an event was sent by code like this:
registry.notify(event, context)
In the past, in order to catch such an event, you were obligated to write and register an event subscriber that mentioned both the event and the context in its argument list:
@subscriber([SomeEvent, SomeContextType])
def asubscriber(event, context):
pass
In many subscriber callables registered this way, it was common for the logic in the subscriber callable to completely ignore the second and following arguments (e.g. context in the above example might be ignored), because they usually existed as attributes of the event anyway. You could usually get the same value by doing event.context or similar.
The fact that you needed to put an extra argument which you usually ignored in the subscriber callable body was only a minor annoyance until we added “subscriber predicates”, used to narrow the set of circumstances under which a subscriber will be executed, in a prior 1.4 alpha release. Once those were added, the annoyance was escalated, because subscriber predicates needed to accept the same argument list and arity as the subscriber callables that they were configured against. So, for example, if you had these two subscriber registrations in your code:
@subscriber([SomeEvent, SomeContextType])
def asubscriber(event, context):
pass
@subscriber(SomeOtherEvent)
def asubscriber(event):
pass
And you wanted to use a subscriber predicate:
@subscriber([SomeEvent, SomeContextType], mypredicate=True)
def asubscriber1(event, context):
pass
@subscriber(SomeOtherEvent, mypredicate=True)
def asubscriber2(event):
pass
If an existing mypredicate subscriber predicate had been written in such a way that it accepted only one argument in its __call__, you could not use it against a subscription which named more than one interface in its subscriber interface list. Similarly, if you had written a subscriber predicate that accepted two arguments, you couldn’t use it against a registration that named only a single interface type.
For example, if you created this predicate:
class MyPredicate(object):
# portions elided...
def __call__(self, event):
return self.val == event.context.foo
It would not work against a multi-interface-registered subscription, so in the above example, when you attempted to use it against asubscriber1, it would fail at runtime with a TypeError, claiming something was attempting to call it with too many arguments.
To hack around this limitation, you were obligated to design the mypredicate predicate to expect to receive in its __call__ either a single event argument (a SomeOtherEvent object) or a pair of arguments (a SomeEvent object and a SomeContextType object), presumably by doing something like this:
class MyPredicate(object):
# portions elided...
def __call__(self, event, context=None):
return self.val == event.context.foo
This was confusing and bad.
In order to allow people to ignore unused arguments to subscriber callables and to normalize the relationship between event subscribers and subscriber predicates, we now allow both subscribers and subscriber predicates to accept only a single event argument even if they’ve been subscribed for notifications that involve multiple interfaces. Subscribers and subscriber predicates that accept only one argument will receive the first object passed to notify; this is typically (but not always) the event object. The other objects involved in the subscription lookup will be discarded. You can now write an event subscriber that accepts only event even if it subscribes to multiple interfaces:
@subscriber([SomeEvent, SomeContextType])
def asubscriber(event):
# this will work!
This prevents you from needing to match the subscriber callable parameters to the subscription type unnecessarily, especially when you don’t make use of any argument in your subscribers except for the event object itself.
Note, however, that if the event object is not the first object in the call to notify, you’ll run into trouble. For example, if notify is called with the context argument first:
registry.notify(context, event)
You won’t be able to take advantage of the event-only feature. It will “work”, but the object received by your event handler won’t be the event object, it will be the context object, which won’t be very useful:
@subscriber([SomeContextType, SomeEvent])
def asubscriber(event):
# bzzt! you'll be getting the context here as ``event``, and it'll
# be useless
Existing multiple-argument subscribers continue to work without issue, so you should continue use those if your system notifies using multiple interfaces and the first interface is not the event interface. For example:
@subscriber([SomeContextType, SomeEvent])
def asubscriber(context, event):
# this will still work!
The event-only feature makes it possible to use a subscriber predicate that accepts only a request argument within both multiple-interface subscriber registrations and single-interface subscriber registrations. You needn’t make slightly different variations of predicates depending on the subscription type arguments. Instead, just write all your subscriber predicates so they only accept event in their __call__ and they’ll be useful across all registrations for subscriptions that use an event as their first argument, even ones which accept more than just event.
However, the same caveat applies to predicates as to subscriber callables: if you’re subscribing to a multi-interface event, and the first interface is not the event interface, the predicate won’t work properly. In such a case, you’ll need to match the predicate __call__ argument ordering and composition to the ordering of the interfaces. For example, if the registration for the subscription uses [SomeContext, SomeEvent], you’ll need to reflect that in the ordering of the parameters of the predicate’s __call__ method:
def __call__(self, context, event):
return event.request.path.startswith(self.val)
tl;dr: 1) When using multi-interface subscriptions, always use the event type as the first subscription registration argument and 2) When 1 is true, use only event in your subscriber and subscriber predicate parameter lists, no matter how many interfaces the subscriber is notified with. This combination will result in the maximum amount of reusability of subscriber predicates and the least amount of thought on your part. Drink responsibly.
Configurator.add_directive now accepts arbitrary callables like partials or objects implementing __call__ which dont have __name__ and __doc__ attributes. See https://github.com/Pylons/pyramid/issues/621 and https://github.com/Pylons/pyramid/pull/647.
Third-party custom view, route, and subscriber predicates can now be added for use by view authors via pyramid.config.Configurator.add_view_predicate, pyramid.config.Configurator.add_route_predicate and pyramid.config.Configurator.add_subscriber_predicate. So, for example, doing this:
config.add_view_predicate('abc', my.package.ABCPredicate)
Might allow a view author to do this in an application that configured that predicate:
@view_config(abc=1)
Similar features exist for add_route, and add_subscriber. See “Adding A Third Party View, Route, or Subscriber Predicate” in the Hooks chapter for more information.
Note that changes made to support the above feature now means that only actions registered using the same “order” can conflict with one another. It used to be the case that actions registered at different orders could potentially conflict, but to my knowledge nothing ever depended on this behavior (it was a bit silly).
Custom objects can be made easily JSON-serializable in Pyramid by defining a __json__ method on the object’s class. This method should return values natively serializable by json.dumps (such as ints, lists, dictionaries, strings, and so forth).
The JSON renderer now allows for the definition of custom type adapters to convert unknown objects to JSON serializations.
As of this release, the request_method predicate, when used, will also imply that HEAD is implied when you use GET. For example, using @view_config(request_method='GET') is equivalent to using @view_config(request_method=('GET', 'HEAD')). Using @view_config(request_method=('GET', 'POST') is equivalent to using @view_config(request_method=('GET', 'HEAD', 'POST'). This is because HEAD is a variant of GET that omits the body, and WebOb has special support to return an empty body when a HEAD is used.
config.add_request_method has been introduced to support extending request objects with arbitrary callables. This method expands on the previous config.set_request_property by supporting methods as well as properties. This method now causes less code to be executed at request construction time than config.set_request_property in version 1.3.
Don’t add a ? to URLs generated by request.resource_url if the query argument is provided but empty.
Don’t add a ? to URLs generated by request.route_url if the _query argument is provided but empty.
The static view machinery now raises (rather than returns) HTTPNotFound and HTTPMovedPermanently exceptions, so these can be caught by the NotFound view (and other exception views).
The Mako renderer now supports a def name in an asset spec. When the def name is present in the asset spec, the system will render the template def within the template and will return the result. An example asset spec is package:path/to/template#defname.mako. This will render the def named defname inside the template.mako template instead of rendering the entire template. The old way of returning a tuple in the form ('defname', {}) from the view is supported for backward compatibility,
The Chameleon ZPT renderer now accepts a macro name in an asset spec. When the macro name is present in the asset spec, the system will render the macro listed as a define-macro and return the result instead of rendering the entire template. An example asset spec: package:path/to/template#macroname.pt. This will render the macro defined as macroname within the template.pt template instead of the entire templae.
When there is a predicate mismatch exception (seen when no view matches for a given request due to predicates not working), the exception now contains a textual description of the predicate which didn’t match.
An add_permission directive method was added to the Configurator. This directive registers a free-standing permission introspectable into the Pyramid introspection system. Frameworks built atop Pyramid can thus use the permissions introspectable category data to build a comprehensive list of permissions supported by a running system. Before this method was added, permissions were already registered in this introspectable category as a side effect of naming them in an add_view call, this method just makes it possible to arrange for a permission to be put into the permissions introspectable category without naming it along with an associated view. Here’s an example of usage of add_permission:
config = Configurator()
config.add_permission('view')
The UnencryptedCookieSessionFactoryConfig now accepts signed_serialize and signed_deserialize hooks which may be used to influence how the sessions are marshalled (by default this is done with HMAC+pickle).
pyramid.testing.DummyRequest now supports methods supplied by the pyramid.util.InstancePropertyMixin class such as set_property.
Request properties and methods added via config.set_request_property or config.add_request_method are now available to tweens.
Request properties and methods added via config.set_request_property or config.add_request_method are now available in the request object returned from pyramid.paster.bootstrap.
request.context of environment request during bootstrap is now the root object if a context isn’t already set on a provided request.
The pyramid.decorator.reify function is now an API, and was added to the API documentation.
Added the pyramid.testing.testConfig context manager, which can be used to generate a configurator in a test, e.g. with testing.testConfig(...):.
Users can now invoke a subrequest from within view code using a new request.invoke_subrequest API.
The method pyramid.request.Request.partial_application_url is no longer in the API docs. It was meant to be a private method; its publication in the documentation as an API method was a mistake, and it has been renamed to something private.
When a static view was registered using an absolute filesystem path on Windows, the request.static_url function did not work to generate URLs to its resources. Symptom: “No static URL definition matching c:\foo\bar\baz”.
Make all tests pass on Windows XP.
Bug in ACL authentication checking on Python 3: the permits and principals_allowed_by_permission method of pyramid.authorization.ACLAuthenticationPolicy could return an inappropriate True value when a permission on an ACL was a string rather than a sequence, and then only if the ACL permission string was a substring of the permission value passed to the function.
This bug effects no Pyramid deployment under Python 2; it is a bug that exists only in deployments running on Python 3. It has existed since Pyramid 1.3a1.
This bug was due to the presence of an __iter__ attribute on strings under Python 3 which is not present under strings in Python 2.
The pyramid.interfaces.IContextURL interface has been deprecated. People have been instructed to use this to register a resource url adapter in the “Hooks” chapter to use to influence request.resource_url URL generation for resources found via custom traversers since Pyramid 1.0.
The interface still exists and registering such an adapter still works, but this interface will be removed from the software after a few major Pyramid releases. You should replace it with an equivalent pyramid.interfaces.IResourceURL adapter, registered using the new pyramid.config.Configurator.add_resource_url_adapter API. A deprecation warning is now emitted when a pyramid.interfaces.IContextURL adapter is found when request.resource_url is called.
The documentation of pyramid.events.subscriber indicated that using it as a decorator with no arguments like this:
@subscriber()
def somefunc(event):
pass
Would register somefunc to receive all events sent via the registry, but this was untrue. Instead, it would receive no events at all. This has now been fixed and the code matches the documentation. See also https://github.com/Pylons/pyramid/issues/386
Literal portions of route patterns were not URL-quoted when route_url or route_path was used to generate a URL or path.
The result of route_path or route_url might have been unicode or str depending on the input. It is now guaranteed to always be str.
URL matching when the pattern contained non-ASCII characters in literal parts was indeterminate. Now the pattern supplied to add_route is assumed to be either: a unicode value, or a str value that contains only ASCII characters. If you now want to match the path info from a URL that contains high order characters, you can pass the Unicode representation of the decoded path portion in the pattern.
When using a traverse= route predicate, traversal would fail with a URLDecodeError if there were any high-order characters in the traversal pattern or in the matched dynamic segments.
Using a dynamic segment named traverse in a route pattern like this:
config.add_route('trav_route', 'traversal/{traverse:.*}')
Would cause a UnicodeDecodeError when the route was matched and the matched portion of the URL contained any high-order characters. See https://github.com/Pylons/pyramid/issues/385 .
When using a *traverse stararg in a route pattern, a URL that matched that possessed a @@ in its name (signifying a view name) would be inappropriately quoted by the traversal machinery during traversal, resulting in the view not being found properly. See https://github.com/Pylons/pyramid/issues/382 and https://github.com/Pylons/pyramid/issues/375 .
String values passed to route_url or route_path that are meant to replace “remainder” matches will now be URL-quoted except for embedded slashes. For example:
config.add_route('remain', '/foo*remainder')
request.route_path('remain', remainder='abc / def')
# -> '/foo/abc%20/%20def'
Previously string values passed as remainder replacements were tacked on untouched, without any URL-quoting. But this doesn’t really work logically if the value passed is Unicode (raw unicode cannot be placed in a URL or in a path) and it is inconsistent with the rest of the URL generation machinery if the value is a string (it won’t be quoted unless by the caller).
Some folks will have been relying on the older behavior to tack on query string elements and anchor portions of the URL; sorry, you’ll need to change your code to use the _query and/or _anchor arguments to route_path or route_url to do this now.
If you pass a bytestring that contains non-ASCII characters to add_route as a pattern, it will now fail at startup time. Use Unicode instead.
The [pshell] section in an ini configuration file now treats a setup key as a dotted name that points to a callable that is passed the bootstrap environment. It can mutate the environment as necessary for great justice.
A new configuration setting named pyramid.includes is now available. It is described in the “Environment Variables and .ini Files Settings” narrative documentation chapter.
Added a route_prefix argument to the pyramid.config.Configurator.include method. This argument allows you to compose URL dispatch applications together. See the section entitled “Using a Route Prefix to Compose Applications” in the “URL Dispatch” narrative documentation chapter.
Added a pyramid.security.NO_PERMISSION_REQUIRED constant for use in permission= statements to view configuration. This constant has a value of the string __no_permission_required__. This string value was previously referred to in documentation; now the documentation uses the constant.
Added a decorator-based way to configure a response adapter: pyramid.response.response_adapter. This decorator has the same use as pyramid.config.Configurator.add_response_adapter but it’s declarative.
The pyramid.events.BeforeRender event now has an attribute named rendering_val. This can be used to introspect the value returned by a view in a BeforeRender subscriber.
New configurator directive: pyramid.config.Configurator.add_tween. This directive adds a “tween”. A “tween” is used to wrap the Pyramid router’s primary request handling function. This is a feature may be used by Pyramid framework extensions, to provide, for example, view timing support and as a convenient place to hang bookkeeping code.
Tweens are further described in the narrative docs section in the Hooks chapter, named “Registering Tweens”.
New paster command paster ptweens, which prints the current “tween” configuration for an application. See the section entitled “Displaying Tweens” in the Command-Line Pyramid chapter of the narrative documentation for more info.
The Pyramid debug logger now uses the standard logging configuration (usually set up by Paste as part of startup). This means that output from e.g. debug_notfound, debug_authorization, etc. will go to the normal logging channels. The logger name of the debug logger will be the package name of the caller of the Configurator’s constructor.
A new attribute is available on request objects: exc_info. Its value will be None until an exception is caught by the Pyramid router, after which it will be the result of sys.exc_info().
pyramid.testing.DummyRequest now implements the add_finished_callback and add_response_callback methods.
New methods of the pyramid.config.Configurator class: set_authentication_policy and set_authorization_policy. These are meant to be consumed mostly by add-on authors.
New Configurator method: set_root_factory.
Pyramid no longer eagerly commits some default configuration statements at Configurator construction time, which permits values passed in as constructor arguments (e.g. authentication_policy and authorization_policy) to override the same settings obtained via an “include”.
Better Mako rendering exceptions via pyramid.mako_templating.MakoRenderingException
New request methods: current_route_url, current_route_path, and static_path.
New functions in pyramid.url: current_route_path and static_path.
The pyramid.request.Request.static_url API (and its brethren pyramid.request.Request.static_path, pyramid.url.static_url, and pyramid.url.static_path) now accept an asbolute filename as a “path” argument. This will generate a URL to an asset as long as the filename is in a directory which was previously registered as a static view. Previously, trying to generate a URL to an asset using an absolute file path would raise a ValueError.
The RemoteUserAuthenticationPolicy ``, ``AuthTktAuthenticationPolicy, and SessionAuthenticationPolicy constructors now accept an additional keyword argument named debug. By default, this keyword argument is False. When it is True, debug information will be sent to the Pyramid debug logger (usually on stderr) when the authenticated_userid or effective_principals method is called on any of these policies. The output produced can be useful when trying to diagnose authentication-related problems.
New view predicate: match_param. Example: a view added via config.add_view(aview, match_param='action=edit') will be called only when the request.matchdict has a value inside it named action with a value of edit.
If a string is passed as the debug_logger parameter to a Configurator, that string is considered to be the name of a global Python logger rather than a dotted name to an instance of a logger.
The pyramid.config.Configurator.include method now accepts only a single callable argument (a sequence of callables used to be permitted). If you are passing more than one callable to pyramid.config.Configurator.include, it will break. You now must now instead make a separate call to the method for each callable. This change was introduced to support the route_prefix feature of include.
It may be necessary to more strictly order configuration route and view statements when using an “autocommitting” Configurator. In the past, it was possible to add a view which named a route name before adding a route with that name when you used an autocommitting configurator. For example:
config = Configurator(autocommit=True)
config.add_view('my.pkg.someview', route_name='foo')
config.add_route('foo', '/foo')
The above will raise an exception when the view attempts to add itself. Now you must add the route before adding the view:
config = Configurator(autocommit=True)
config.add_route('foo', '/foo')
config.add_view('my.pkg.someview', route_name='foo')
This won’t effect “normal” users, only people who have legacy BFG codebases that used an autommitting configurator and possibly tests that use the configurator API (the configurator returned by pyramid.testing.setUp is an autocommitting configurator). The right way to get around this is to use a non-autocommitting configurator (the default), which does not have these directive ordering requirements.
The pyramid.config.Configurator.add_route directive no longer returns a route object. This change was required to make route vs. view configuration processing work properly.
Fix corner case to ease semifunctional testing of views: create a new rendererinfo to clear out old registry on a rescan. See https://github.com/Pylons/pyramid/pull/234.
New API class: pyramid.static.static_view. This supersedes the deprecated pyramid.view.static class. pyramid.static.static_view by default serves up documents as the result of the request’s path_info, attribute rather than it’s subpath attribute (the inverse was true of pyramid.view.static, and still is). pyramid.static.static_view exposes a use_subpath flag for use when you want the static view to behave like the older deprecated version.
A new API function pyramid.paster.bootstrap has been added to make writing scripts that bootstrap a Pyramid environment easier, e.g.:
from pyramid.paster import bootstrap
info = bootstrap('/path/to/my/development.ini')
request = info['request']
print request.route_url('myroute')
A new API function pyramid.scripting.prepare has been added. It is a lower-level analogue of pyramid.paster.boostrap that accepts a request and a registry instead of a config file argument, and is used for the same purpose:
from pyramid.scripting import prepare
info = prepare(registry=myregistry)
request = info['request']
print request.route_url('myroute')
A new API function pyramid.scripting.make_request has been added. The resulting request will have a registry attribute. It is meant to be used in conjunction with pyramid.scripting.prepare and/or pyramid.paster.bootstrap (both of which accept a request as an argument):
from pyramid.scripting import make_request
request = make_request('/')
New API attribute pyramid.config.global_registries is an iterable object that contains references to every Pyramid registry loaded into the current process via pyramid.config.Configurator.make_app. It also has a last attribute containing the last registry loaded. This is used by the scripting machinery, and is available for introspection.
It is now possible to invoke paster pshell even if the paste ini file section name pointed to in its argument is not actually a Pyramid WSGI application. The shell will work in a degraded mode, and will warn the user. See “The Interactive Shell” in the “Creating a Pyramid Project” narrative documentation section.
paster pshell now offers more built-in global variables by default (including app and settings). See “The Interactive Shell” in the “Creating a Pyramid Project” narrative documentation section.
It is now possible to add a [pshell] section to your application’s .ini configuration file, which influences the global names available to a pshell session. See “Extending the Shell” in the “Creating a Pyramid Project” narrative documentation chapter.
The config.scan method has grown a **kw argument. kw argument represents a set of keyword arguments to pass to the Venusian Scanner object created by Pyramid. (See the Venusian documentation for more information about Scanner).
New request property: json_body. This property will return the JSON-decoded variant of the request body. If the request body is not well-formed JSON, this property will raise an exception.
A new value http_cache can be used as a view configuration parameter.
When you supply an http_cache value to a view configuration, the Expires and Cache-Control headers of a response generated by the associated view callable are modified. The value for http_cache may be one of the following:
Providing a non-tuple value as http_cache is equivalent to calling response.cache_expires(value) within your view’s body.
Providing a two-tuple value as http_cache is equivalent to calling response.cache_expires(value[0], **value[1]) within your view’s body.
If you wish to avoid influencing, the Expires header, and instead wish to only influence Cache-Control headers, pass a tuple as http_cache with the first element of None, e.g.: (None, {'public':True}).
pyramid.testing.DummyRequest now raises deprecation warnings when attributes deprecated for pyramid.request.Request are accessed (like response_content_type). This is for the benefit of folks running unit tests which use DummyRequest instead of a “real” request, so they know things are deprecated without necessarily needing a functional test suite.
The pyramid.events.subscriber directive behaved contrary to the documentation when passed more than one interface object to its constructor. For example, when the following listener was registered:
@subscriber(IFoo, IBar)
def expects_ifoo_events_and_ibar_events(event):
print event
The Events chapter docs claimed that the listener would be registered and listening for both IFoo and IBar events. Instead, it registered an “object event” subscriber which would only be called if an IObjectEvent was emitted where the object interface was IFoo and the event interface was IBar.
The behavior now matches the documentation. If you were relying on the buggy behavior of the 1.0 subscriber directive in order to register an object event subscriber, you must now pass a sequence to indicate you’d like to register a subscriber for an object event. e.g.:
@subscriber([IFoo, IBar])
def expects_object_event(object, event):
print object, event
The pyramid Router attempted to set a value into the key environ['repoze.bfg.message'] when it caught a view-related exception for backwards compatibility with applications written for repoze.bfg during error handling. It did this by using code that looked like so:
# "why" is an exception object
try:
msg = why[0]
except:
msg = ''
environ['repoze.bfg.message'] = msg
Use of the value environ['repoze.bfg.message'] was docs-deprecated in Pyramid 1.0. Our standing policy is to not remove features after a deprecation for two full major releases, so this code was originally slated to be removed in Pyramid 1.2. However, computing the repoze.bfg.message value was the source of at least one bug found in the wild (https://github.com/Pylons/pyramid/issues/199), and there isn’t a foolproof way to both preserve backwards compatibility and to fix the bug. Therefore, the code which sets the value has been removed in this release. Code in exception views which relies on this value’s presence in the environment should now use the exception attribute of the request (e.g. request.exception[0]) to retrieve the message instead of relying on request.environ['repoze.bfg.message'].
Add support for language fallbacks: when trying to translate for a specific territory (such as en_GB) fall back to translations for the language (ie en). This brings the translation behaviour in line with GNU gettext and fixes partially translated texts when using C extensions.
New authentication policy: pyramid.authentication.SessionAuthenticationPolicy, which uses a session to store credentials.
Accessing the response attribute of a pyramid.request.Request object (e.g. request.response within a view) now produces a new pyramid.response.Response object. This feature is meant to be used mainly when a view configured with a renderer needs to set response attributes: all renderers will use the Response object implied by request.response as the response object returned to the router.
request.response can also be used by code in a view that does not use a renderer, however the response object that is produced by request.response must be returned when a renderer is not in play (it is not a “global” response).
Integers and longs passed as elements to pyramid.url.resource_url or pyramid.request.Request.resource_url e.g. resource_url(context, request, 1, 2) (1 and 2 are the elements) will now be converted implicitly to strings in the result. Previously passing integers or longs as elements would cause a TypeError.
pyramid_alchemy paster template now uses query.get rather than query.filter_by to take better advantage of identity map caching.
pyramid_alchemy paster template now has unit tests.
Added pyramid.i18n.make_localizer API (broken out from get_localizer guts).
An exception raised by a NewRequest event subscriber can now be caught by an exception view.
It is now possible to get information about why Pyramid raised a Forbidden exception from within an exception view. The ACLDenied object returned by the permits method of each stock authorization policy (pyramid.interfaces.IAuthorizationPolicy.permits) is now attached to the Forbidden exception as its result attribute. Therefore, if you’ve created a Forbidden exception view, you can see the ACE, ACL, permission, and principals involved in the request as eg. context.result.permission, context.result.acl, etc within the logic of the Forbidden exception view.
Don’t explicitly prevent the timeout from being lower than the reissue_time when setting up an AuthTktAuthenticationPolicy (previously such a configuration would raise a ValueError, now it’s allowed, although typically nonsensical). Allowing the nonsensical configuration made the code more understandable and required fewer tests.
A new paster command named paster pviews was added. This command prints a summary of potentially matching views for a given path. See the section entitled “Displaying Matching Views for a Given URL” in the “View Configuration” chapter of the narrative documentation for more information.
The add_route method of the Configurator now accepts a static argument. If this argument is True, the added route will never be considered for matching when a request is handled. Instead, it will only be useful for URL generation via route_url and route_path. See the section entitled “Static Routes” in the URL Dispatch narrative chapter for more information.
A default exception view for the context pyramid.interfaces.IExceptionResponse is now registered by default. This means that an instance of any exception response class imported from pyramid.httpexceptions (such as HTTPFound) can now be raised from within view code; when raised, this exception view will render the exception to a response.
A function named pyramid.httpexceptions.exception_response is a shortcut that can be used to create HTTP exception response objects using an HTTP integer status code.
The Configurator now accepts an additional keyword argument named exceptionresponse_view. By default, this argument is populated with a default exception view function that will be used when a response is raised as an exception. When None is passed for this value, an exception view for responses will not be registered. Passing None returns the behavior of raising an HTTP exception to that of Pyramid 1.0 (the exception will propagate to middleware and to the WSGI server).
The pyramid.request.Request class now has a ResponseClass interface which points at pyramid.response.Response.
The pyramid.response.Response class now has a RequestClass interface which points at pyramid.request.Request.
It is now possible to return an arbitrary object from a Pyramid view callable even if a renderer is not used, as long as a suitable adapter to pyramid.interfaces.IResponse is registered for the type of the returned object by using the new pyramid.config.Configurator.add_response_adapter API. See the section in the Hooks chapter of the documentation entitled “Changing How Pyramid Treats View Responses”.
The Pyramid router will now, by default, call the __call__ method of WebOb response objects when returning a WSGI response. This means that, among other things, the conditional_response feature of WebOb response objects will now behave properly.
New method named pyramid.request.Request.is_response. This method should be used instead of the pyramid.view.is_response function, which has been deprecated.
Deprecated all assignments to request.response_* attributes (for example request.response_content_type = 'foo' is now deprecated). Assignments and mutations of assignable request attributes that were considered by the framework for response influence are now deprecated: response_content_type, response_headerlist, response_status, response_charset, and response_cache_for. Instead of assigning these to the request object for later detection by the rendering machinery, users should use the appropriate API of the Response object created by accessing request.response (e.g. code which does request.response_content_type = 'abc' should be changed to request.response.content_type = 'abc').
Passing view-related parameters to pyramid.config.Configurator.add_route is now deprecated. Previously, a view was permitted to be connected to a route using a set of view* parameters passed to the add_route method of the Configurator. This was a shorthand which replaced the need to perform a subsequent call to add_view. For example, it was valid (and often recommended) to do:
config.add_route('home', '/', view='mypackage.views.myview',
view_renderer='some/renderer.pt')
Passing view* arguments to add_route is now deprecated in favor of connecting a view to a predefined route via Configurator.add_view using the route’s route_name parameter. As a result, the above example should now be spelled:
config.add_route('home', '/')
config.add_view('mypackage.views.myview', route_name='home')
renderer='some/renderer.pt')
This deprecation was done to reduce confusion observed in IRC, as well as to (eventually) reduce documentation burden (see also https://github.com/Pylons/pyramid/issues/164). A deprecation warning is now issued when any view-related parameter is passed to Configurator.add_route.
Passing an environ dictionary to the __call__ method of a “traverser” (e.g. an object that implements pyramid.interfaces.ITraverser such as an instance of pyramid.traversal.ResourceTreeTraverser) as its request argument now causes a deprecation warning to be emitted. Consumer code should pass a request object instead. The fact that passing an environ dict is permitted has been documentation-deprecated since repoze.bfg 1.1, and this capability will be removed entirely in a future version.
The following (undocumented, dictionary-like) methods of the pyramid.request.Request object have been deprecated: __contains__, __delitem__, __getitem__, __iter__, __setitem__, get, has_key, items, iteritems, itervalues, keys, pop, popitem, setdefault, update, and values. Usage of any of these methods will cause a deprecation warning to be emitted. These methods were added for internal compatibility in repoze.bfg 1.1 (code that currently expects a request object expected an environ object in BFG 1.0 and before). In a future version, these methods will be removed entirely.
Deprecated pyramid.view.is_response function in favor of (newly-added) pyramid.request.Request.is_response method. Determining if an object is truly a valid response object now requires access to the registry, which is only easily available as a request attribute. The pyramid.view.is_response function will still work until it is removed, but now may return an incorrect answer under some (very uncommon) circumstances.
The Pyramid concept previously known as “model” is now known as “resource”. As a result:
The following API changes have been made:
pyramid.url.model_url ->
pyramid.url.resource_url
pyramid.traversal.find_model ->
pyramid.url.find_resource
pyramid.traversal.model_path ->
pyramid.traversal.resource_path
pyramid.traversal.model_path_tuple ->
pyramid.traversal.resource_path_tuple
pyramid.traversal.ModelGraphTraverser ->
pyramid.traversal.ResourceTreeTraverser
pyramid.config.Configurator.testing_models ->
pyramid.config.Configurator.testing_resources
pyramid.testing.registerModels ->
pyramid.testing.registerResources
pyramid.testing.DummyModel ->
pyramid.testing.DummyResource
- All documentation which previously referred to “model” now refers to “resource”.
- The starter and starter_zcml paster templates now have a resources.py module instead of a models.py module.
Backwards compatibility shims have been left in place in all cases. They will continue to work “forever”.
The Pyramid concept previously known as “resource” is now known as “asset”. As a result:
The (non-API) module previously known as pyramid.resource is now known as pyramid.asset.
All docs that previously referred to “resource specification” now refer to “asset specification”.
The following API changes were made:
pyramid.config.Configurator.absolute_resource_spec ->
pyramid.config.Configurator.absolute_asset_spec
pyramid.config.Configurator.override_resource ->
pyramid.config.Configurator.override_asset
The ZCML directive previously known as resource is now known as asset.
The setting previously known as BFG_RELOAD_RESOURCES (envvar) or reload_resources (config file) is now known, respectively, as PYRAMID_RELOAD_ASSETS and reload_assets.
Backwards compatibility shims have been left in place in all cases. They will continue to work “forever”.
pyramid.configuration.Configurator is now deprecated. Use pyramid.config.Configurator, passing its constructor autocommit=True instead. The pyramid.configuration.Configurator alias will live for a long time, as every application uses it, but its import now issues a deprecation warning. The pyramid.config.Configurator class has the same API as pyramid.configuration.Configurator class, which it means to replace, except by default it is a non-autocommitting configurator. The now-deprecated pyramid.configuration.Configurator will autocommit every time a configuration method is called.
The pyramid.configuration module remains, but it is deprecated. Use pyramid.config instead.
Mako templating renderer supports resource specification format for template lookups and within Mako templates. Absolute filenames must be used in Pyramid to avoid this lookup process.
Add pyramid.httpexceptions module, which is a facade for the webob.exc module.
Direct built-in support for the Mako templating language.
A new configurator method exists: add_handler. This method adds a Pylons-style “view handler” (such a thing used to be called a “controller” in Pylons 1.0).
New argument to configurator: session_factory.
New method on configurator: set_session_factory
Using request.session now returns a (dictionary-like) session object if a session factory has been configured.
The request now has a new attribute: tmpl_context for benefit of Pylons users.
The decorator previously known as pyramid.view.bfg_view is now known most formally as pyramid.view.view_config in docs and paster templates. An import of pyramid.view.bfg_view, however, will continue to work “forever”.
New API methods in pyramid.session: signed_serialize and signed_deserialize.
New interface: pyramid.interfaces.IRendererInfo. An object of this type is passed to renderer factory constructors (see “Backwards Incompatibilities”).
New event type: pyramid.interfaces.IBeforeRender. An object of this type is sent as an event before a renderer is invoked (but after the application-level renderer globals factory added via pyramid.configurator.configuration.set_renderer_globals_factory, if any, has injected its own keys). Applications may now subscribe to the IBeforeRender event type in order to introspect the and modify the set of renderer globals before they are passed to a renderer. The event object iself has a dictionary-like interface that can be used for this purpose. For example:
from repoze.events import subscriber
from pyramid.interfaces import IRendererGlobalsEvent
@subscriber(IRendererGlobalsEvent)
def add_global(event):
event['mykey'] = 'foo'
If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a KeyError is raised. This limitation is due to the fact that subscribers cannot be ordered relative to each other. The set of keys added to the renderer globals dictionary by all subscribers and app-level globals factories must be unique.
New class: pyramid.response.Response. This is a pure facade for webob.Response (old code need not change to use this facade, it’s existence is mostly for vanity and documentation-generation purposes).
All preexisting paster templates (except zodb) now use “imperative” configuration (starter, routesalchemy, alchemy).
A new paster template named pyramid_starter_zcml exists, which uses declarative configuration.
There is no longer an IDebugLogger registered as a named utility with the name repoze.bfg.debug.
The logger which used to have the name of repoze.bfg.debug now has the name pyramid.debug.
The deprecated API pyramid.testing.registerViewPermission has been removed.
The deprecated API named pyramid.testing.registerRoutesMapper has been removed.
The deprecated API named pyramid.request.get_request was removed.
The deprecated API named pyramid.security.Unauthorized was removed.
The deprecated API named pyramid.view.view_execution_permitted was removed.
The deprecated API named pyramid.view.NotFound was removed.
The bfgshell paster command is now named pshell.
The Venusian “category” for all built-in Venusian decorators (e.g. subscriber and view_config/bfg_view) is now pyramid instead of bfg.
pyramid.renderers.rendered_response function removed; use render_pyramid.renderers.render_to_response instead.
Renderer factories now accept a renderer info object rather than an absolute resource specification or an absolute path. The object has the following attributes: name (the renderer= value), package (the ‘current package’ when the renderer configuration statement was found), type: the renderer type, registry: the current registry, and settings: the deployment settings dictionary.
Third-party repoze.bfg renderer implementations that must be ported to Pyramid will need to account for this.
This change was made primarily to support more flexible Mako template rendering.
The presence of the key repoze.bfg.message in the WSGI environment when an exception occurs is now deprecated. Instead, code which relies on this environ value should use the exception attribute of the request (e.g. request.exception[0]) to retrieve the message.
The values bfg_localizer and bfg_locale_name kept on the request during internationalization for caching purposes were never APIs. These however have changed to localizer and locale_name, respectively.
The default cookie_name value of the authtktauthenticationpolicy ZCML now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).
The default cookie_name value of the pyramid.authentication.AuthTktAuthenticationPolicy constructor now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).
The request_type argument to the view ZCML directive, the pyramid.configuration.Configurator.add_view method, or the pyramid.view.view_config decorator (nee bfg_view) is no longer permitted to be one of the strings GET, HEAD, PUT, POST or DELETE, and now must always be an interface. Accepting the method-strings as request_type was a backwards compatibility strategy servicing repoze.bfg 1.0 applications. Use the request_method parameter instead to specify that a view a string request-method predicate.
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:
root_factory, authentication_policy, authorization_policy, debug_logger, locale_negotiator, request_factory, renderer_globals_factory
subscriber, iface
view
view, for_, context, request_type, containment
view, view_for, factory, for_, view_context
package
factory
view
view
factory
factory
negotiator
event_iface
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).
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 *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.
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.
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).
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.
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) 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.
The Configurator object now has two new methods: begin and end. The begin method is meant to be called before any “configuration” begins (e.g. before add_view, et. al are called). The end method is meant to be called after all “configuration” is complete.
Previously, before there was imperative configuration at all (1.1 and prior), configuration begin and end was invariably implied by the process of loading a ZCML file. When a ZCML load happened, the threadlocal data structure containing the request and registry was modified before the load, and torn down after the load, making sure that all framework code that needed get_current_registry for the duration of the ZCML load was satisfied.
Some API methods called during imperative configuration, (such as Configurator.add_view when a renderer is involved) end up for historical reasons calling get_current_registry. However, in 1.2a5 and below, the Configurator supplied no functionality that allowed people to make sure that get_current_registry returned the registry implied by the configurator being used. begin now serves this purpose. Inversely, end pops the thread local stack, undoing the actions of begin.
We make this boundary explicit to reduce the potential for confusion when the configurator is used in different circumstances (e.g. in unit tests and app code vs. just in initial app setup).
Existing code written for 1.2a1-1.2a5 which does not call begin or end continues to work in the same manner it did before. It is however suggested that this code be changed to call begin and end to reduce the potential for confusion in the future.
All paster templates which generate an application skeleton now make use of the new begin and end methods of the Configurator they use in their respective copies of run.py and tests.py.
An imperative configuration mode.
A repoze.bfg application can now begin its life as a single Python file. Later, the application might evolve into a set of Python files in a package. Even later, it might start making use of other configuration features, such as ZCML. But neither the use of a package nor the use of non-imperative configuration is required to create a simple repoze.bfg application any longer.
Imperative configuration makes repoze.bfg competetive with “microframeworks” such as Bottle and Tornado. repoze.bfg has a good deal of functionality that most microframeworks lack, so this is hopefully a “best of both worlds” feature.
The simplest possible repoze.bfg application is now:
from webob import Response
from wsgiref import simple_server
from repoze.bfg.configuration import Configurator
def hello_world(request):
return Response('Hello world!')
if __name__ == '__main__':
config = Configurator()
config.add_view(hello_world)
app = config.make_wsgi_app()
simple_server.make_server('', 8080, app).serve_forever()
A new class now exists: repoze.bfg.configuration.Configurator. This class forms the basis for sharing machinery between “imperatively” configured applications and traditional declaratively-configured applications.
The repoze.bfg.testing.setUp function now accepts three extra optional keyword arguments: registry, request and hook_zca.
If the registry argument is not None, the argument will be treated as the registry that is set as the “current registry” (it will be returned by repoze.bfg.threadlocal.get_current_registry) for the duration of the test. If the registry argument is None (the default), a new registry is created and used for the duration of the test.
The value of the request argument is used as the “current request” (it will be returned by repoze.bfg.threadlocal.get_current_request) for the duration of the test; it defaults to None.
If hook_zca is True (the default), the zope.component.getSiteManager function will be hooked with a function that returns the value of registry (or the default-created registry if registry is None) instead of the registry returned by zope.component.getGlobalSiteManager, causing the Zope Component Architecture API (getSiteManager, getAdapter, getUtility, and so on) to use the testing registry instead of the global ZCA registry.
The repoze.bfg.testing.tearDown function now accepts an unhook_zca argument. If this argument is True (the default), zope.component.getSiteManager.reset() will be called. This will cause the result of the zope.component.getSiteManager function to be the global ZCA registry (the result of zope.component.getGlobalSiteManager) once again.
The run.py module in various repoze.bfg paster templates now use a repoze.bfg.configuration.Configurator class instead of the (now-legacy) repoze.bfg.router.make_app function to produce a WSGI application.
The routes mapper is no longer a root factory wrapper. It is now consulted directly by the router.
The repoze.bfg.registry.make_registry callable has been removed.
The repoze.bfg.view.map_view callable has been removed.
The repoze.bfg.view.owrap_view callable has been removed.
The repoze.bfg.view.predicate_wrap callable has been removed.
The repoze.bfg.view.secure_view callable has been removed.
The repoze.bfg.view.authdebug_view callable has been removed.
The repoze.bfg.view.renderer_from_name callable has been removed. Use repoze.bfg.configuration.Configurator.renderer_from_name instead (still not an API, however).
The repoze.bfg.view.derive_view callable has been removed. Use repoze.bfg.configuration.Configurator.derive_view instead (still not an API, however).
The repoze.bfg.settings.get_options callable has been removed. Its job has been subsumed by the repoze.bfg.settings.Settings class constructor.
The repoze.bfg.view.requestonly function has been moved to repoze.bfg.configuration.requestonly.
The repoze.bfg.view.rendered_response function has been moved to repoze.bfg.configuration.rendered_response.
The repoze.bfg.view.decorate_view function has been moved to repoze.bfg.configuration.decorate_view.
The repoze.bfg.view.MultiView class has been moved to repoze.bfg.configuration.MultiView.
The repoze.bfg.zcml.Uncacheable class has been removed.
The repoze.bfg.resource.resource_spec function has been removed.
All ZCML directives which deal with attributes which are paths now use the path method of the ZCML context to resolve a relative name to an absolute one (imperative configuration requirement).
The repoze.bfg.scripting.get_root API now uses a ‘real’ WebOb request rather than a FakeRequest when it sets up the request as a threadlocal.
The repoze.bfg.traversal.traverse API now uses a ‘real’ WebOb request rather than a FakeRequest when it calls the traverser.
The repoze.bfg.request.FakeRequest class has been removed.
Most uses of the ZCA threadlocal API (the getSiteManager, getUtility, getAdapter, getMultiAdapter threadlocal API) have been removed from the core. Instead, when a threadlocal is necessary, the core uses the repoze.bfg.threadlocal.get_current_registry API to obtain the registry.
The internal ILogger utility named repoze.bfg.debug is now just an IDebugLogger unnamed utility. A named utility with the old name is registered for b/w compat.
The repoze.bfg.interfaces.ITemplateRendererFactory interface was removed; it has become unused.
Instead of depending on the martian package to do code scanning, we now just use our own scanning routines.
We now no longer have a dependency on repoze.zcml package; instead, the repoze.bfg package includes implementations of the adapter, subscriber and utility directives.
Relating to the following functions:
repoze.bfg.view.render_view
repoze.bfg.view.render_view_to_iterable
repoze.bfg.view.render_view_to_response
repoze.bfg.view.append_slash_notfound_view
repoze.bfg.view.default_notfound_view
repoze.bfg.view.default_forbidden_view
repoze.bfg.configuration.rendered_response
repoze.bfg.security.has_permission
repoze.bfg.security.authenticated_userid
repoze.bfg.security.effective_principals
repoze.bfg.security.view_execution_permitted
repoze.bfg.security.remember
repoze.bfg.security.forget
repoze.bfg.url.route_url
repoze.bfg.url.model_url
repoze.bfg.url.static_url
repoze.bfg.traversal.virtual_root
Each of these functions now expects to be called with a request object that has a registry attribute which represents the current repoze.bfg registry. They fall back to obtaining the registry from the threadlocal API.
Unit tests which use zope.testing.cleanup.cleanUp for the purpose of isolating tests from one another may now begin to fail due to lack of isolation between tests.
Here’s why: In repoze.bfg 1.1 and prior, the registry returned by repoze.bfg.threadlocal.get_current_registry when no other registry had been pushed on to the threadlocal stack was the zope.component.globalregistry.base global registry (aka the result of zope.component.getGlobalSiteManager()). In repoze.bfg 1.2+, however, the registry returned in this situation is the new module-scope repoze.bfg.registry.global_registry object. The zope.testing.cleanup.cleanUp function clears the zope.component.globalregistry.base global registry unconditionally. However, it does not know about the repoze.bfg.registry.global_registry object, so it does not clear it.
If you use the zope.testing.cleanup.cleanUp function in the setUp of test cases in your unit test suite instead of using the (more correct as of 1.1) repoze.bfg.testing.setUp, you will need to replace all calls to zope.testing.cleanup.cleanUp with a call to repoze.bfg.testing.setUp.
If replacing all calls to zope.testing.cleanup.cleanUp with a call to repoze.bfg.testing.setUp is infeasible, you can put this bit of code somewhere that is executed exactly once (not for each test in a test suite; in the `` __init__.py`` of your package or your package’s tests subpackage would be a reasonable place):
import zope.testing.cleanup
from repoze.bfg.testing import setUp
zope.testing.cleanup.addCleanUp(setUp)
When there is no “current registry” in the repoze.bfg.threadlocal.manager threadlocal data structure (this is the case when there is no “current request” or we’re not in the midst of a r.b.testing.setUp-bounded unit test), the .get method of the manager returns a data structure containing a global registry. In previous releases, this function returned the global Zope “base” registry: the result of zope.component.getGlobalSiteManager, which is an instance of the zope.component.registry.Component class. In this release, however, the global registry returns a globally importable instance of the repoze.bfg.registry.Registry class. This registry instance can always be imported as repoze.bfg.registry.global_registry.
Effectively, this means that when you call repoze.bfg.threadlocal.get_current_registry when no request or setUp bounded unit test is in effect, you will always get back the global registry that lives in repoze.bfg.registry.global_registry. It also means that repoze.bfg APIs that call get_current_registry will use this registry.
This change was made because repoze.bfg now expects the registry it uses to have a slightly different API than a bare instance of zope.component.registry.Components.
View registration no longer registers a repoze.bfg.interfaces.IViewPermission adapter (it is no longer checked by the framework; since 1.1, views have been responsible for providing their own security).
The repoze.bfg.router.make_app callable no longer accepts the authentication_policy nor the authorization_policy arguments. This feature was deprecated in version 1.0 and has been removed.
Obscure: the machinery which configured views with a request_type and a route_name would ignore the request interface implied by route_name registering a view only for the interface implied by request_type. In the unlikely event that you were trying to use these two features together, the symptom would have been that views that named a request_type but which were also associated with routes were not found when the route matched. Now if a view is configured with both a request_type and a route_name, an error is raised.
The route ZCML directive now no longer accepts the request_type or view_request_type attributes. These attributes didn’t actually work in any useful way (see entry above this one).
Because the repoze.bfg package now includes implementations of the adapter, subscriber and utility ZCML directives, it is now an error to have <include package="repoze.zcml" file="meta.zcml"/> in the ZCML of a repoze.bfg application. A ZCML conflict error will be raised if your ZCML does so. This shouldn’t be an issue for “normal” installations; it has always been the responsibility of the repoze.bfg.includes ZCML to include this file in the past; it now just doesn’t.
The repoze.bfg.testing.zcml_configure API was removed. Use the Configurator.load_zcml API instead.
The repoze.bfg.router.make_app function is now nominally deprecated. Its import and usage does not throw a warning, nor will it probably ever disappear. However, using a repoze.bfg.configuration.Configurator class is now the preferred way to generate a WSGI application.
Note that make_app calls zope.component.getSiteManager.sethook( repoze.bfg.threadlocal.get_current_registry) on the caller’s behalf, hooking ZCA global API lookups, for backwards compatibility purposes. If you disuse make_app, your calling code will need to perform this call itself, at least if your application uses the ZCA global API (getSiteManager, getAdapter, etc).
Compound statements that used an assignment entered into in an interactive IPython session invoked via paster bfgshell no longer fail to mutate the shell namespace correctly. For example, this set of statements used to fail:
In [2]: def bar(x): return x
...:
In [3]: list(bar(x) for x in 'abc')
Out[3]: NameError: 'bar'
In this release, the bar function is found and the correct output is now sent to the console. Thanks to Daniel Holth for the patch.
The bfgshell command did not function properly; it was still expecting to be able to call the root factory with a bare environ rather than a request object.
Add a new event type: repoze.bfg.events.AfterTraversal. Events of this type will be sent after traversal is completed, but before any view code is invoked. Like repoze.bfg.events.NewRequest, This event will have a single attribute: request representing the current request. Unlike the request attribute of repoze.bfg.events.NewRequest however, during an AfterTraversal event, the request object will possess attributes set by the traverser, most notably context, which will be the context used when a view is found and invoked. The interface repoze.bfg.events.IAfterTraversal can be used to subscribe to the event. For example:
<subscriber for="repoze.bfg.interfaces.IAfterTraversal"
handler="my.app.handle_after_traverse"/>
Like any framework event, a subscriber function should expect one parameter: event.
More than one @bfg_view decorator may now be stacked on top of any number of others. Each invocation of the decorator registers a single view configuration. For instance, the following combination of decorators and a function will register two view configurations for the same view callable:
from repoze.bfg.view import bfg_view
@bfg_view(name='edit')
@bfg_view(name='change')
def edit(context, request):
pass
This makes it possible to associate more than one view configuration with a single callable without requiring any ZCML.
The @bfg_view decorator can now be used against a class method:
from webob import Response
from repoze.bfg.view import bfg_view
class MyView(object):
def __init__(self, context, request):
self.context = context
self.request = request
@bfg_view(name='hello')
def amethod(self):
return Response('hello from %s!' % self.context)
When the bfg_view decorator is used against a class method, a view is registered for the class (it’s a “class view” where the “attr” happens to be the name of the method it is attached to), so the class it’s defined within must have a suitable constructor: one that accepts context, request or just request.
We previously had a Unicode-aware wrapper for the urllib.urlencode function named repoze.bfg.url.urlencode which delegated to the stdlib function, but which marshalled all unicode values to utf-8 strings before calling the stdlib version. A newer replacement now lives in repoze.bfg.encode The replacement does not delegate to the stdlib.
The replacement diverges from the stdlib implementation and the previous repoze.bfg.url url implementation inasmuch as its doseq argument is now a decoy: it always behaves in the doseq=True way (which is the only sane behavior) for speed purposes.
The old import location (repoze.bfg.url.urlencode) still functions and has not been deprecated.
In 0.8a7, the return value expected from an object implementing ITraverserFactory was changed from a sequence of values to a dictionary containing the keys context, view_name, subpath, traversed, virtual_root, virtual_root_path, and root. Until now, old-style traversers which returned a sequence have continued to work but have generated a deprecation warning. In this release, traversers which return a sequence instead of a dictionary will no longer work.
The interfaces IPOSTRequest, IGETRequest, IPUTRequest, IDELETERequest, and IHEADRequest have been removed from the repoze.bfg.interfaces module. These were not documented as APIs post-1.0. Instead of using one of these, use a request_method ZCML attribute or request_method bfg_view decorator parameter containing an HTTP method name (one of GET, POST, HEAD, PUT, DELETE) instead of one of these interfaces if you were using one explicitly. Passing a string in the set (GET, HEAD, PUT, POST, DELETE) as a request_type argument will work too. Rationale: instead of relying on interfaces attached to the request object, BFG now uses a “view predicate” to determine the request type.
Views registered without the help of the ZCML view directive are now responsible for performing their own authorization checking.
The registry_manager backwards compatibility alias importable from “repoze.bfg.registry”, deprecated since repoze.bfg 0.9 has been removed. If you are tring to use the registry manager within a debug script of your own, use a combination of the “repoze.bfg.paster.get_app” and “repoze.bfg.scripting.get_root” APIs instead.
The INotFoundAppFactory interface has been removed; it has been deprecated since repoze.bfg 0.9. If you have something like the following in your configure.zcml:
<utility provides="repoze.bfg.interfaces.INotFoundAppFactory"
component="helloworld.factories.notfound_app_factory"/>
Replace it with something like:
<notfound
view="helloworld.views.notfound_view"/>
See “Changing the Not Found View” in the “Hooks” chapter of the documentation for more information.
The IUnauthorizedAppFactory interface has been removed; it has been deprecated since repoze.bfg 0.9. If you have something like the following in your configure.zcml:
<utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory"
component="helloworld.factories.unauthorized_app_factory"/>
Replace it with something like:
<forbidden
view="helloworld.views.forbidden_view"/>
See “Changing the Forbidden View” in the “Hooks” chapter of the documentation for more information.
ISecurityPolicy-based security policies, deprecated since repoze.bfg 0.9, have been removed. If you have something like this in your configure.zcml, it will no longer work:
<utility
provides="repoze.bfg.interfaces.ISecurityPolicy"
factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
/>
If ZCML like the above exists in your application, you will receive an error at startup time. Instead of the above, you’ll need something like:
<remoteuserauthenticationpolicy/>
<aclauthorizationpolicy/>
This is just an example. See the “Security” chapter of the repoze.bfg documentation for more information about configuring security policies.
Custom ZCML directives which register an authentication or authorization policy (ala “authtktauthenticationpolicy” or “aclauthorizationpolicy”) should register the policy “eagerly” in the ZCML directive instead of from within a ZCML action. If an authentication or authorization policy is not found in the component registry by the view machinery during deferred ZCML processing, view security will not work as expected.
A new ZCML directive exists named “resource”. This ZCML directive allows you to override Chameleon templates within a package (both directories full of templates and individual template files) with other templates in the same package or within another package. This allows you to “fake out” a view’s use of a template, causing it to retrieve a different template than the one actually named by a relative path to a call like render_template_to_response('templates/mytemplate.pt'). For example, you can override a template file by doing:
<resource
to_override="some.package:templates/mytemplate.pt"
override_with="another.package:othertemplates/anothertemplate.pt"
/>
The string passed to “to_override” and “override_with” is named a “specification”. The colon separator in a specification separates the package name from a package-relative directory name. The colon and the following relative path are optional. If they are not specified, the override attempts to resolve every lookup into a package from the directory of another package. For example:
<resource
to_override="some.package"
override_with="another.package"
/>
Individual subdirectories within a package can also be overridden:
<resource
to_override="some.package:templates/"
override_with="another.package:othertemplates/"
/>
If you wish to override a directory with another directory, you must make sure to attach the slash to the end of both the to_override specification and the override_with specification. If you fail to attach a slash to the end of a specification that points a directory, you will get unexpected results. You cannot override a directory specification with a file specification, and vice versa (a startup error will occur if you try).
You cannot override a resource with itself (a startup error will occur if you try).
Only individual package resources may be overridden. Overrides will not traverse through subpackages within an overridden package. This means that if you want to override resources for both some.package:templates, and some.package.views:templates, you will need to register two overrides.
The package name in a specification may start with a dot, meaning that the package is relative to the package in which the ZCML file resides. For example:
<resource
to_override=".subpackage:templates/"
override_with="another.package:templates/"
/>
Overrides for the same to_overrides specification can be named multiple times within ZCML. Each override_with path will be consulted in the order defined within ZCML, forming an override search path.
Resource overrides can actually override resources other than templates. Any software which uses the pkg_resources get_resource_filename, get_resource_stream or get_resource_string APIs will obtain an overridden file when an override is used. However, the only built-in facility which uses the pkg_resources API within BFG is the templating stuff, so we only call out template overrides here.
Use the pkg_resources API to locate template filenames instead of dead-reckoning using the os.path module.
The repoze.bfg.templating module now uses pkg_resources to locate and register template files instead of using an absolute path name.
A new ZCML directive was added named notfound. This ZCML directive can be used to name a view that should be invoked when the request can’t otherwise be resolved to a view callable. For example:
<notfound
view="helloworld.views.notfound_view"/>
A new ZCML directive was added named forbidden. This ZCML directive can be used to name a view that should be invoked when a view callable for a request is found, but cannot be invoked due to an authorization failure. For example:
<forbidden
view="helloworld.views.forbidden_view"/>
Allow views to be optionally defined as callables that accept only a request object, instead of both a context and a request (which still works, and always will). The following types work as views in this style:
functions that accept a single argument request, e.g.:
def aview(request):
pass
new and old-style classes that have an __init__ method that accepts self, request, e.g.:
def View(object):
__init__(self, request):
pass
Arbitrary callables that have a __call__ method that accepts self, request, e.g.:
def AView(object):
def __call__(self, request):
pass
view = AView()
This likely should have been the calling convention all along, as the request has context as an attribute already, and with views called as a result of URL dispatch, having the context in the arguments is not very useful. C’est la vie.
Cache the absolute path in the caller’s package globals within repoze.bfg.path to get rid of repeated (expensive) calls to os.path.abspath.
Add reissue_time and timeout parameters to repoze.bfg.authentication.AuthTktAuthenticationPolicy constructor. If these are passed, cookies will be reset every so often (cadged from the same change to repoze.who lately).
The matchdict related to the matching of a Routes route is available on the request as the matchdict attribute: request.matchdict. If no route matched, this attribute will be None.
Make 404 responses slightly cheaper by showing environ["PATH_INFO"] on the notfound result page rather than the fullly computed URL.
Move LRU cache implementation into a separate package (repoze.lru).
The concepts of traversal and URL dispatch have been unified. It is now possible to use the same sort of factory as both a traversal “root factory” and what used to be referred to as a urldispatch “context factory”.
When the root factory argument (as a first argument) passed to repoze.bfg.router.make_app is None, a default root factory is used. This is in support of using routes as “root finders”; it supplants the idea that there is a default IRoutesContextFactory.
The view` ZCML statement and the repoze.bfg.view.bfg_view decorator now accept an extra argument: route_name. If a route_name is specified, it must match the name of a previously defined route statement. When it is specified, the view will only be called when that route matches during a request.
It is now possible to perfom traversal after a route has matched. Use the pattern *traverse in a <route> path attribute within ZCML, and the path remainder which it matches will be used as a traversal path.
When any route defined matches, the WSGI environment will now contain a key bfg.routes.route (the Route object which matched), and a key bfg.routes.matchdict (the result of calling route.match).
A paster command has been added named “bfgshell”. This command can be used to get an interactive prompt with your BFG root object in the global namespace. E.g.:
bin/paster bfgshell /path/to/myapp.ini myapp
See the Project chapter in the BFG documentation for more information.
New API functions named forget and remember are available in the security module. The forget function returns headers which will cause the currently authenticated user to be logged out when set in a response. The remember function (when passed the proper arguments) will return headers which will cause a principal to be “logged in” when set in a response. See the Security API chapter of the docs for more info.
New keyword arguments to the repoze.bfg.router.make_app call have been added: authentication_policy and authorization_policy. These should, respectively, be an implementation of an authentication policy (an object implementing the repoze.bfg.interfaces.IAuthenticationPolicy interface) and an implementation of an authorization policy (an object implementing repoze.bfg.interfaces.IAuthorizationPolicy). Concrete implementations of authentication policies exist in repoze.bfg.authentication. Concrete implementations of authorization policies exist in repoze.bfg.authorization.
Both authentication_policy and authorization_policy default to None.
If authentication_policy is None, but authorization_policy is not None, then authorization_policy is ignored (the ability to do authorization depends on authentication).
If the authentication_policy argument is not None, and the authorization_policy argument is None, the authorization policy defaults to an authorization implementation that uses ACLs (repoze.bfg.authorization.ACLAuthorizationPolicy).
We no longer encourage configuration of “security policies” using ZCML, as previously we did for ISecurityPolicy. This is because it’s not uncommon to need to configure settings for concrete authorization or authentication policies using paste .ini parameters; the app entry point for your application is the natural place to do this.
Two new abstractions have been added in the way of adapters used by the system: an IAuthorizationPolicy and an IAuthenticationPolicy. A combination of these (as registered by the securitypolicy ZCML directive) take the place of the ISecurityPolicy abstraction in previous releases of repoze.who. The API functions in repoze.who.security (such as authentication_userid, effective_principals, has_permission, and so on) have been changed to try to make use of these new adapters. If you’re using an older ISecurityPolicy adapter, the system will still work, but it will print deprecation warnings when such a policy is used.
The way the (internal) IViewPermission utilities registered via ZCML are invoked has changed. They are purely adapters now, returning a boolean result, rather than returning a callable. You shouldn’t have been using these anyway. ;-)
New concrete implementations of IAuthenticationPolicy have been added to the repoze.bfg.authentication module: RepozeWho1AuthenticationPolicy which uses repoze.who identity to retrieve authentication data from and RemoteUserAuthenticationPolicy, which uses the REMOTE_USER value in the WSGI environment to retrieve authentication data.
A new concrete implementation of IAuthorizationPolicy has been added to the repoze.bfg.authorization module: ACLAuthorizationPolicy which uses ACL inheritance to do authorization.
It is now possible to register a custom repoze.bfg.interfaces.IForbiddenResponseFactory for a given application. This feature replaces the repoze.bfg.interfaces.IUnauthorizedAppFactory feature previously described in the Hooks chapter. The IForbiddenResponseFactory will be called when the framework detects an authorization failure; it should accept a context object and a request object; it should return an IResponse object (a webob response, basically). Read the below point for more info and see the Hooks narrative chapter of the BFG docs for more info.
Class objects may now be used as view callables (both via ZCML and via use of the bfg_view decorator in Python 2.6 as a class decorator). The calling semantics when using a class as a view callable is similar to that of using a class as a Zope “browser view”: the class’ __init__ must accept two positional parameters (conventionally named context, and request). The resulting instance must be callable (it must have a __call__ method). When called, the instance should return a response. For example:
from webob import Response
class MyView(object):
def __init__(self, context, request):
self.context = context
self.request = request
def __call__(self):
return Response('hello from %s!' % self.context)
See the "Views" chapter in the documentation and the
``repoze.bfg.view`` API documentation for more information.
Removed the pickling of ZCML actions (the code that wrote configure.zcml.cache next to configure.zcml files in projects). The code which managed writing and reading of the cache file was a source of subtle bugs when users switched between imperative (e.g. @bfg_view) registrations and declarative registrations (e.g. the view directive in ZCML) on the same project. On a moderately-sized project (535 ZCML actions and 15 ZCML files), executing actions read from the pickle was saving us only about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1 ZCML file and 4 actions), startup time was comparable, and sometimes even slower when reading from the pickle, and both ways were so fast that it really just didn’t matter anyway.
The RoutesMapper class in repoze.bfg.urldispatch has been removed, as well as its documentation. It had been deprecated since 0.6.3. Code in repoze.bfg.urldispatch.RoutesModelTraverser which catered to it has also been removed.
The semantics of the route ZCML directive have been simplified. Previously, it was assumed that to use a route, you wanted to map a route to an externally registered view. The new route directive instead has a view attribute which is required, specifying the dotted path to a view callable. When a route directive is processed, a view is registered using the name attribute of the route directive as its name and the callable as its value. The view_name and provides attributes of the route directive are therefore no longer used. Effectively, if you were previously using the route directive, it means you must change a pair of ZCML directives that look like this:
<route
name="home"
path=""
view_name="login"
factory=".models.root.Root"
/>
<view
for=".models.root.Root"
name="login"
view=".views.login_view"
/>
To a ZCML directive that looks like this:
<route
name="home"
path=""
view=".views.login_view"
factory=".models.root.Root"
/>
In other words, to make old code work, remove the view directives that were only there to serve the purpose of backing route directives, and move their view= attribute into the route directive itself.
This change also necessitated that the name attribute of the route directive is now required. If you were previously using route directives without a name attribute, you’ll need to add one (the name is arbitrary, but must be unique among all route and view statements).
The provides attribute of the route directive has also been removed. This directive specified a sequence of interface types that the generated context would be decorated with. Since route views are always generated now for a single interface (repoze.bfg.IRoutesContext) as opposed to being looked up arbitrarily, there is no need to decorate any context to ensure a view is found.
In version 0.6.3, passing a get_root callback (a “root factory”) to repoze.bfg.router.make_app became optional if any route declaration was made in ZCML. The intent was to make it possible to disuse traversal entirely, instead relying entirely on URL dispatch (Routes) to resolve all contexts. However a compound set of bugs prevented usage of a Routes-based root view (a view which responds to “/”). One bug existed in repoze.bfg.urldispatch`, another existed in Routes itself.
To resolve this issue, the urldispatch module was fixed, and a fork of the Routes trunk was put into the “dev” index named Routes-1.11dev-chrism-home. The source for the fork exists at http://bitbucket.org/chrism/routes-home/; its contents have been merged into the Routes trunk (what will be Routes 1.11).
The security policy previously named RepozeWhoIdentityACLSecurityPolicy now has the slightly saner name of WhoACLSecurityPolicy. A deprecation warning is emitted when this policy is imported under the “old” name; usually this is due to its use in ZCML within your application. If you’re getting this deprecation warning, change your ZCML to use the new name, e.g. change:
<utility
provides="repoze.bfg.interfaces.ISecurityPolicy"
factory="repoze.bfg.security.RepozeWhoIdentityACLSecurityPolicy"
/>
To:
<utility
provides="repoze.bfg.interfaces.ISecurityPolicy"
factory="repoze.bfg.security.WhoACLSecurityPolicy"
/>
This release of repoze.bfg is “C-free”. This means it has no hard dependencies on any software that must be compiled from C source at installation time. In particular, repoze.bfg no longer depends on the lxml package.
This change has introduced some backwards incompatibilities, described in the “Backwards Incompatibilities” section below.
This release was tested on Windows XP. It appears to work fine and all the tests pass.
Incompatibilities related to making repoze.bfg “C-free”:
Other backwards incompatibilities:
The “paster create” templates have been modified to use links to the new “bfg.repoze.org” and “docs.repoze.org” websites.
Added better documentation for virtual hosting at a URL prefix within the virtual hosting docs chapter.
The interface for repoze.bfg.interfaces.ITraverser and the built-in implementations that implement the interface (repoze.bfg.traversal.ModelGraphTraverser, and repoze.bfg.urldispatch.RoutesModelTraverser) now expect the __call__ method of an ITraverser to return 3 additional arguments: traversed, virtual_root, and virtual_root_path (the old contract was that the __call__ method of an ITraverser returned; three arguments, the contract new is that it returns six). traversed will be a sequence of Unicode names that were traversed (including the virtual root path, if any) or None if no traversal was performed, virtual_root will be a model object representing the virtual root (or the physical root if traversal was not performed), and virtual_root_path will be a sequence representing the virtual root path (a sequence of Unicode names) or None if traversal was not performed.
Six arguments are now returned from BFG ITraversers. They are returned in this order: context, view_name, subpath, traversed, virtual_root, and virtual_root_path.
Places in the BFG code which called an ITraverser continue to accept a 3-argument return value, although BFG will generate and log a warning when one is encountered.
The request object now has the following attributes: traversed (the sequence of names traversed or None if traversal was not performed), virtual_root (the model object representing the virtual root, including the virtual root path if any), and virtual_root_path (the seuquence of names representing the virtual root path or None if traversal was not performed).
A new decorator named wsgiapp2 was added to the repoze.bfg.wsgi module. This decorator performs the same function as repoze.bfg.wsgi.wsgiapp except it fixes up the SCRIPT_NAME, and PATH_INFO environment values before invoking the WSGI subapplication.
The repoze.bfg.testing.DummyRequest object now has default attributes for traversed, virtual_root, and virtual_root_path.
The RoutesModelTraverser now behaves more like the Routes “RoutesMiddleware” object when an element in the match dict is named path_info (usually when there’s a pattern like http://foo/*path_info). When this is the case, the PATH_INFO environment variable is set to the value in the match dict, and the SCRIPT_NAME is appended to with the prefix of the original PATH_INFO not including the value of the new variable.
The notfound debug now shows the traversed path, the virtual root, and the virtual root path too.
Speed up / clarify ‘traversal’ module’s ‘model_path’, ‘model_path_tuple’, and ‘_model_path_list’ functions.
In previous releases, the repoze.bfg.url.model_url, repoze.bfg.traversal.model_path and repoze.bfg.traversal.model_path_tuple functions always ignored the __name__ argument of the root object in a model graph ( effectively replacing it with a leading / in the returned value) when a path or URL was generated. The code required to perform this operation was not efficient. As of this release, the root object in a model graph must have a __name__ attribute that is either None or the empty string ('') for URLs and paths to be generated properly from these APIs. If your root model object has a __name__ argument that is not one of these values, you will need to change your code for URLs and paths to be generated properly. If your model graph has a root node with a string __name__ that is not null, the value of __name__ will be prepended to every path and URL generated.
The repoze.bfg.location.LocationProxy class and the repoze.bfg.location.ClassAndInstanceDescr class have both been removed in order to be able to eventually shed a dependency on zope.proxy. Neither of these classes was ever an API.
In all previous releases, the repoze.bfg.location.locate function worked like so: if a model did not explicitly provide the repoze.bfg.interfaces.ILocation interface, locate returned a LocationProxy object representing model with its __parent__ attribute assigned to parent and a __name__ attribute assigned to __name__. In this release, the repoze.bfg.location.locate function simply jams the __name__ and __parent__ attributes on to the supplied model unconditionally, no matter if the object implements ILocation or not, and it never returns a proxy. This was done because the LocationProxy behavior has now moved into an add-on package (repoze.bfg.traversalwrapper), in order to eventually be able to shed a dependency on zope.proxy.
In all previous releases, by default, if traversal was used (as opposed to URL-dispatch), and the root object supplied the``repoze.bfg.interfaces.ILocation`` interface, but the children returned via its __getitem__ returned an object that did not implement the same interface, repoze.bfg provided some implicit help during traversal. This traversal feature wrapped subobjects from the root (and thereafter) that did not implement ILocation in proxies which automatically provided them with a __name__ and __parent__ attribute based on the name being traversed and the previous object traversed. This feature has now been removed from the base repoze.bfg package for purposes of eventually shedding a dependency on zope.proxy.
In order to re-enable the wrapper behavior for older applications which cannot be changed, register the “traversalwrapper” ModelGraphTraverser as the traversal policy, rather than the default ModelGraphTraverser. To use this feature, you will need to install the repoze.bfg.traversalwrapper package (an add-on package, available at http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your application’s configure.zcml to include the following stanza:
- <adapter
factory=”repoze.bfg.traversalwrapper.ModelGraphTraverser” provides=”repoze.bfg.interfaces.ITraverserFactory” for=”*” />
When this ITraverserFactory is used instead of the default, no object in the graph (even the root object) must supply a __name__ or __parent__ attribute. Even if subobjects returned from the root do implement the ILocation interface, these will still be wrapped in proxies that override the object’s “real” __parent__ and __name__ attributes.
See also changes to the “Models” chapter of the documentation (in the “Location-Aware Model Instances”) section.
The default request charset encoding is now utf-8. As a result, the request machinery will attempt to decode values from the utf-8 encoding to Unicode automatically when they are obtained via request.params, request.GET, and request.POST. The previous behavior of BFG was to return a bytestring when a value was accessed in this manner. This change will break form handling code in apps that rely on values from those APIs being considered bytestrings. If you are manually decoding values from form submissions in your application, you’ll either need to change the code that does that to expect Unicode values from request.params, request.GET and request.POST, or you’ll need to explicitly reenable the previous behavior. To reenable the previous behavior, add the following to your application’s configure.zcml:
<subscriber for="repoze.bfg.interfaces.INewRequest"
handler="repoze.bfg.request.make_request_ascii"/>
See also the documentation in the “Views” chapter of the BFG docs entitled “Using Views to Handle Form Submissions (Unicode and Character Set Issues)”.
The repoze.bfg.traversal.model_path API now returns a quoted string rather than a string represented by series of unquoted elements joined via / characters. Previously it returned a string or unicode object representing the model path, with each segment name in the path joined together via / characters, e.g. /foo /bar. Now it returns a string, where each segment is a UTF-8 encoded and URL-quoted element e.g. /foo%20/bar. This change was (as discussed briefly on the repoze-dev maillist) necessary to accomodate model objects which themselves have __name__ attributes that contain the / character.
For people that have no models that have high-order Unicode __name__ attributes or __name__ attributes with values that require URL-quoting with in their model graphs, this won’t cause any issue. However, if you have code that currently expects model_path to return an unquoted string, or you have an existing application with data generated via the old method, and you’re too lazy to change anything, you may wish replace the BFG-imported model_path in your code with this function (this is the code of the “old” model_path implementation):
from repoze.bfg.location import lineage
def i_am_too_lazy_to_move_to_the_new_model_path(model, *elements):
rpath = []
for location in lineage(model):
if location.__name__:
rpath.append(location.__name__)
path = '/' + '/'.join(reversed(rpath))
if elements:
suffix = '/'.join(elements)
path = '/'.join([path, suffix])
return path
The repoze.bfg.traversal.find_model API no longer implicitly converts unicode representations of a full path passed to it as a Unicode object into a UTF-8 string. Callers should either use prequoted path strings returned by repoze.bfg.traversal.model_path, or tuple values returned by the result of repoze.bfg.traversal.model_path_tuple or they should use the guidelines about passing a string path argument described in the find_model API documentation.
repoze.bfg.traversal.split_path now also handles decoding path segments to unicode (for speed, because its results are cached).
ModelGraphTraverser.
Use “precooked” Request subclasses (e.g. repoze.bfg.request.GETRequest) that correspond to HTTP request methods within router.py when constructing a request object rather than using alsoProvides to attach the proper interface to an unsubclassed webob.Request. This pattern is purely an optimization (e.g. preventing calls to alsoProvides means the difference between 590 r/s and 690 r/s on a MacBook 2GHz).
Tease out an extra 4% performance boost by changing the Router; instead of using imported ZCA APIs, use the same APIs directly against the registry that is an attribute of the Router.
The registry used by BFG is now a subclass of zope.component.registry.Components (defined as repoze.bfg.registry.Registry); it has a notify method, a registerSubscriptionAdapter and a registerHandler method. If no subscribers are registered via registerHandler or registerSubscriptionAdapter, notify is a noop for speed.
The Allowed and Denied classes in repoze.bfg.security now are lazier about constructing the representation of a reason message for speed; repoze.bfg.view_execution_permitted takes advantage of this.
The is_response check was sped up by about half at the expense of making its code slightly uglier.
Rather than prepare the “stock” implementations of the ZCML directives from the zope.configuration package for use under repoze.bfg, repoze.bfg now makes available the implementations of directives from the repoze.zcml package (see http://static.repoze.org/zcmldocs). As a result, the repoze.bfg package now depends on the repoze.zcml package, and no longer depends directly on the zope.component, zope.configuration, zope.interface, or zope.proxy packages.
The primary reason for this change is to enable us to eventually reduce the number of inappropriate repoze.bfg Zope package dependencies, as well as to shed features of dependent package directives that don’t make sense for repoze.bfg.
Note that currently the set of requirements necessary to use bfg has not changed. This is due to inappropriate Zope package requirements in chameleon.zpt, which will hopefully be remedied soon. NOTE: in lemonade index a 1.0b8-repozezcml0 package exists which does away with these requirements.
BFG applications written prior to this release which expect the “stock” zope.component ZCML directive implementations (e.g. adapter, subscriber, or utility) to function now must either 1) include the meta.zcml file from zope.component manually (e.g. <include package="zope.component" file="meta.zcml">) and include the zope.security package as an install_requires dependency or 2) change the ZCML in their applications to use the declarations from repoze.zcml instead of the stock declarations. repoze.zcml only makes available the adapter, subscriber and utility directives.
In short, if you’ve got an existing BFG application, after this update, if your application won’t start due to an import error for “zope.security”, the fastest way to get it working again is to add zope.security to the “install_requires” of your BFG application’s setup.py, then add the following ZCML anywhere in your application’s configure.zcml:
<include package="zope.component" file="meta.zcml">
Then re-setup.py develop or reinstall your application.
The http://namespaces.repoze.org/bfg XML namespace is now the default XML namespace in ZCML for paster-generated applications. The docs have been updated to reflect this.
The copies of BFG’s meta.zcml and configure.zcml were removed from the root of the repoze.bfg package. In 0.3.6, a new package named repoze.bfg.includes was added, which contains the “correct” copies of these ZCML files; the ones that were removed were for backwards compatibility purposes.
The BFG view ZCML directive no longer calls zope.component.interface.provideInterface for the for interface. We don’t support provideInterface in BFG because it mutates the global registry.
In the past, during traversal, the ModelGraphTraverser (the default traverser) always passed each URL path segment to any __getitem__ method of a model object as a byte string (a str object). Now, by default the ModelGraphTraverser attempts to decode the path segment to Unicode (a unicode object) using the UTF-8 encoding before passing it to the __getitem__ method of a model object. This makes it possible for model objects to be dumber in __getitem__ when trying to resolve a subobject, as model objects themselves no longer need to try to divine whether or not to try to decode the path segment passed by the traverser.
Note that since 0.5.4, URLs generated by repoze.bfg’s model_url API will contain UTF-8 encoded path segments as necessary, so any URL generated by BFG itself will be decodeable by the traverser. If another application generates URLs to a BFG application, to be resolved successully, it should generate the URL with UTF-8 encoded path segments to be successfully resolved. The decoder is not at all magical: if a non-UTF-8-decodeable path segment (e.g. one encoded using UTF-16 or some other insanity) is passed in the URL, BFG will raise a TypeError with a message indicating it could not decode the path segment.
To turn on the older behavior, where path segments were not decoded to Unicode before being passed to model object __getitem__ by the traverser, and were passed as a raw byte string, set the unicode_path_segments configuration setting to a false value in your BFG application’s section of the paste .ini file, for example:
unicode_path_segments = False
Or start the application using the BFG_UNICODE_PATH_SEGMENT envvar set to a false value:
BFG_UNICODE_PATH_SEGMENTS=0
Applications must now use the repoze.bfg.interfaces.ILocation interface rather than zope.location.interfaces.ILocation to represent that a model object is “location-aware”. We’ve removed a dependency on zope.location for cleanliness purposes: as new versions of zope libraries are released which have improved dependency information, getting rid of our dependence on zope.location will prevent a newly installed repoze.bfg application from requiring the zope.security, egg, which not truly used at all in a “stock” repoze.bfg setup. These dependencies are still required by the stack at this time; this is purely a futureproofing move.
The security and model documentation for previous versions of repoze.bfg recommended using the zope.location.interfaces.ILocation interface to represent that a model object is “location-aware”. This documentation has been changed to reflect that this interface should now be imported from repoze.bfg.interfaces.ILocation instead.
Bugfixes