It was not possible to use pyramid.httpexceptions.HTTPException as
the context of an exception view as very general catchall for
http-related exceptions when you wanted that exception view to override the
default exception view. See https://github.com/Pylons/pyramid/issues/985.
Backport from master.

When the pyramid.reload_templates setting was true, and a Chameleon
template was reloaded, and the renderer specification named a macro
(e.g. foo#macroname.pt), renderings of the template after the template
was reloaded due to a file change would produce the entire template body
instead of just a rendering of the macro. See
https://github.com/Pylons/pyramid/issues/1013. Backport from master.

Fix an obscure problem when combining a virtual root with a route with a
*traverse in its pattern. Now the traversal path generated in
such a configuration will be correct, instead of an element missing
a leading slash.

pyramid.testing.DummyResource didn’t define __bool__, so code under
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

mako_templating: added defensive workaround for non-importability of
mako due to upstream markupsafe dropping Python 3.2 support. Mako
templating will no longer work under the combination of MarkupSafe 0.17 and
Python 3.2 (although the combination of MarkupSafe 0.17 and Python 3.3 or any
supported Python 2 version will work OK).

Make the pyramid.config.assets.PackageOverrides object implement the API
for __loader__ objects specified in PEP 302. Proxies to the
__loader__ set by the importer, if present; otherwise, raises
NotImplementedError. This makes Pyramid static view overrides work
properly under Python 3.3 (previously they would not). See
https://github.com/Pylons/pyramid/pull/1015 for more information.

pyramid.debug_authorization=true will now correctly print out
Allowed for views registered with NO_PERMISSION_REQUIRED instead
of invoking the permits method of the authorization policy.
See https://github.com/Pylons/pyramid/issues/954

Modified the _depth argument to pyramid.view.view_config to accept
a value relative to the invocation of view_config itself. Thus, when it
was previously expecting a value of 1 or greater, to reflect that
the caller of view_config is 1 stack frame away from venusian.attach,
this implementation detail is now hidden.

Modified the _backframes argument to pyramid.util.action_method in a
similar way to the changes described to _depth above. This argument
remains undocumented, but might be used in the wild by some insane person.

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=1b=2 so you can fill in
values in parameterized .ini file, e.g. pshelletc/development.inihttp_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:

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:

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.

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:

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:

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:

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:

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.

A failure when trying to locate the attribute __text__ on route and view
predicates existed when the debug_routematch setting was true or when the
pviews command was used. See https://github.com/Pylons/pyramid/pull/727

pyramid.authentication.AuthTktAuthenticationPolicy has been updated to
support newer hashing algorithms such as sha512. Existing applications
should consider updating if possible for improved security over the default
md5 hashing.

Added an effective_principals route and view predicate.

Do not allow the userid returned from the authenticated_userid or the
userid that is one of the list of principals returned by
effective_principals to be either of the strings system.Everyone or
system.Authenticated when any of the built-in authorization policies that
live in pyramid.authentication are in use. These two strings are
reserved for internal usage by Pyramid and they will not be accepted as valid
userids.

pyramid.security.view_execution_permitted used to return True if no
view could be found. It now raises a TypeError exception in that case, as
it doesn’t make sense to assert that a nonexistent view is
execution-permitted. See https://github.com/Pylons/pyramid/issues/299.

Allow a _depth argument to pyramid.view.view_config, which will
permit limited composition reuse of the decorator by other software that
wants to provide custom decorators that are much like view_config.

Allow an iterable of decorators to be passed to
pyramid.config.Configurator.add_view. This allows views to be wrapped
by more than one decorator without requiring combining the decorators
yourself.

In the past if a renderer returned None, the body of the resulting
response would be set explicitly to the empty string. Instead, now, the body
is left unchanged, which allows the renderer to set a body itself by using
e.g. request.response.body=b'foo'. The body set by the renderer will
be unmolested on the way out. See
https://github.com/Pylons/pyramid/issues/709

In uncommon cases, the pyramid_excview_tween_factory might have
inadvertently raised a KeyError looking for request_iface as an
attribute of the request. It no longer fails in this case. See
https://github.com/Pylons/pyramid/issues/700

Be more tolerant of potential error conditions in match_param and
physical_path predicate implementations; instead of raising an exception,
return False.

pyramid.authentication.AuthTktAuthenticationPolicy will emit a warning if
an application is using the policy without explicitly passing a hashalg
argument. This is because the default is “md5” which is considered
theoretically subject to collision attacks. If you really want “md5” then you
must specify it explicitly to get rid of the warning.

Move TopologicalSorter from pyramid.config.util to pyramid.util,
move CyclicDependencyError from pyramid.config.util to
pyramid.exceptions, rename Singleton to Sentinel and move from
pyramid.config.util to pyramid.util; this is in an effort to
move that stuff that may be an API one day out of pyramid.config.util,
because that package should never be imported from non-Pyramid code.
TopologicalSorter is still not an API, but may become one.

Get rid of shady monkeypatching of pyramid.request.Request and
pyramid.response.Response done within the __init__.py of Pyramid.
Webob no longer relies on this being done. Instead, the ResponseClass
attribute of the Pyramid Request class is assigned to the Pyramid response
class; that’s enough to satisfy WebOb and behave as it did before with the
monkeypatching.

1.4a pyramid.scripting.prepare behaved differently than 1.3 series
function of same name. In particular, if passed a request, it would not
set the registry attribute of the request like 1.3 did. A symptom
would be that passing a request to pyramid.paster.bootstrap (which uses
the function) that did not have a registry attribute could assume that
the registry would be attached to the request by Pyramid. This assumption
could be made in 1.3, but not in 1.4. The assumption can now be made in
1.4 too (a registry is attached to a request passed to bootstrap or
prepare).

When registering a view configuration that named a Chameleon ZPT renderer
with a macro name in it (e.g. renderer='some/template#somemacro.pt) as
well as a view configuration without a macro name in it that pointed to the
same template (e.g. renderer='some/template.pt'), internal caching could
confuse the two, and your code might have rendered one instead of the
other.

The Configurator testing_securitypolicy method now returns the policy
object it creates.

The Configurator testing_securitypolicy method accepts two new
arguments: remember_result and forget_result. If supplied, these
values influence the result of the policy’s remember and forget
methods, respectively.

The DummySecurityPolicy created by testing_securitypolicy now sets a
forgotten value on the policy (the value True) when its forget
method is called.

The DummySecurityPolicy created by testing_securitypolicy now sets a
remembered value on the policy, which is the value of the principal
argument it’s called with when its remember method is called.

New physical_path view predicate. If specified, this value should be a
string or a tuple representing the physical traversal path of the context
found via traversal for this predicate to match as true. For example:
physical_path='/' or physical_path='/a/b/c' or physical_path=('','a','b','c'). This is not a path prefix match or a regex, it’s a
whole-path match. It’s useful when you want to always potentially show a
view when some object is traversed to, but you can’t be sure about what kind
of object it will be, so you can’t use the context predicate. The
individual path elements inbetween slash characters or in tuple elements
should be the Unicode representation of the name of the resource and should
not be encoded in any way.

A new pyramid.session.check_csrf_token convenience function was added.

A check_csrf view predicate was added. For example, you can now do
config.add_view(someview,check_csrf=True). When the predicate is
checked, if the csrf_token value in request.params matches the CSRF
token in the request’s session, the view will be permitted to execute.
Otherwise, it will not be permitted to execute.

Add Base.metadata.bind=engine to alchemy template, so that tables
defined imperatively will work.

Forward port from 1.3 branch: When no authentication policy was configured,
a call to pyramid.security.effective_principals would unconditionally
return the empty list. This was incorrect, it should have unconditionally
returned [Everyone], and now does.

On at least one 64-bit Ubuntu system under Python 3.2, using the
view_config decorator caused a RuntimeError:dictionarychangedsizeduringiteration exception. It no longer does. See
https://github.com/Pylons/pyramid/issues/635 for more information.

HTTP Accept headers were not being normalized causing potentially
conflicting view registrations to go unnoticed. Two views that only
differ in the case (‘text/html’ vs. ‘text/HTML’) will now raise an error.
https://github.com/Pylons/pyramid/pull/620

Forward-port from 1.3 branch: when registering multiple views with an
accept predicate in a Pyramid application runing under Python 3, you
might have received a TypeError:unorderabletypes:function()<function() exception.

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. withtesting.testConfig(...):.

Users can now invoke a subrequest from within view code using a new
request.invoke_subrequest API.

The pyramid.config.Configurator.set_request_property has been
documentation-deprecated. The method remains usable but the more
featureful pyramid.config.Configurator.add_request_method should be
used in its place (it has all of the same capabilities but can also extend
the request object with methods).

The Pyramid router no longer adds the values bfg.routes.route or
bfg.routes.matchdict to the request’s WSGI environment dictionary.
These values were docs-deprecated in repoze.bfg 1.0 (effectively seven
minor releases ago). If your code depended on these values, use
request.matched_route and request.matchdict instead.

It is no longer possible to pass an environ dictionary directly to
pyramid.traversal.ResourceTreeTraverser.__call__ (aka
ModelGraphTraverser.__call__). Instead, you must pass a request
object. Passing an environment instead of a request has generated a
deprecation warning since Pyramid 1.1.

Pyramid will no longer work properly if you use the
webob.request.LegacyRequest as a request factory. Instances of the
LegacyRequest class have a request.path_info which return a string.
This Pyramid release assumes that request.path_info will
unconditionally be Unicode.

The functions from pyramid.chameleon_zpt and pyramid.chameleon_text
named get_renderer, get_template, render_template, and
render_template_to_response have been removed. These have issued a
deprecation warning upon import since Pyramid 1.0. Use
pyramid.renderers.get_renderer(),
pyramid.renderers.get_renderer().implementation(),
pyramid.renderers.render() or pyramid.renderers.render_to_response
respectively instead of these functions.

The pyramid.configuration module was removed. It had been deprecated
since Pyramid 1.0 and printed a deprecation warning upon its use. Use
pyramid.config instead.

The pyramid.paster.PyramidTemplate API was removed. It had been
deprecated since Pyramid 1.1 and issued a warning on import. If your code
depended on this, adjust your code to import
pyramid.scaffolds.PyramidTemplate instead.

The pyramid.settings.get_settings() API was removed. It had been
printing a deprecation warning since Pyramid 1.0. If your code depended on
this API, use pyramid.threadlocal.get_current_registry().settings
instead or use the settings attribute of the registry available from
the request (request.registry.settings).

These APIs from the pyramid.testing module were removed. They have
been printing deprecation warnings since Pyramid 1.0:

In Pyramid 1.3 and previous, the __call__ method of a Response object
was invoked before any finished callbacks were executed. As of this
release, the __call__ method of a Response object is invoked after
finished callbacks are executed. This is in support of the
request.invoke_subrequest feature.

Added an “Upgrading Pyramid” chapter to the narrative documentation. It
describes how to cope with deprecations and removals of Pyramid APIs and
how to show Pyramid-generated deprecation warnings while running tests and
while running a server.

Added a “Invoking a Subrequest” chapter to the documentation. It describes
how to use the new request.invoke_subrequest API.

When pyramid.wsgi.wsgiapp2 calls the downstream WSGI app, the app’s
environ will no longer have (deprecated and potentially misleading)
bfg.routes.matchdict or bfg.routes.route keys in it. A symptom of
this bug would be a wsgiapp2-wrapped Pyramid app finding the wrong view
because it mistakenly detects that a route was matched when, in fact, it
was not.

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.

All references to the tmpl_context request variable were removed from
the docs. Its existence in Pyramid is confusing for people who were never
Pylons users. It was added as a porting convenience for Pylons users in
Pyramid 1.0, but it never caught on because the Pyramid rendering system is
a lot different than Pylons’ was, and alternate ways exist to do what it
was designed to offer in Pylons. It will continue to exist “forever” but
it will not be recommended or mentioned in the docs.

Add an introspection boolean to the Configurator constructor. If this
is True, actions registered using the Configurator will be registered
with the introspector. If it is False, they won’t. The default is
True. Setting it to False during action processing will prevent
introspection for any following registration statements, and setting it to
True will start them up again. This addition is to service a
requirement that the debug toolbar’s own views and methods not show up in
the introspector.

New API: pyramid.config.Configurator.add_notfound_view. This is a
wrapper for pyramid.Config.configurator.add_view which provides easy
append_slash support and does the right thing about permissions. It should
be preferred over calling add_view directly with
context=HTTPNotFound as was previously recommended.

New API: pyramid.view.notfound_view_config. This is a decorator
constructor like pyramid.view.view_config that calls
pyramid.config.Configurator.add_notfound_view when scanned. It should
be preferred over using pyramid.view.view_config with
context=HTTPNotFound as was previously recommended.

New API: pyramid.config.Configurator.add_forbidden_view. This is a
wrapper for pyramid.Config.configurator.add_view which does the right
thing about permissions. It should be preferred over calling add_view
directly with context=HTTPForbidden as was previously recommended.

New API: pyramid.view.forbidden_view_config. This is a decorator
constructor like pyramid.view.view_config that calls
pyramid.config.Configurator.add_forbidden_view when scanned. It should
be preferred over using pyramid.view.view_config with
context=HTTPForbidden as was previously recommended.

New APIs: pyramid.response.FileResponse and
pyramid.response.FileIter, for usage in views that must serve files
“manually”.

Remove pyramid.config.Configurator.with_context class method. It was
never an API, it is only used by pyramid_zcml and its functionality has
been moved to that package’s latest release. This means that you’ll need
to use the 0.9.2 or later release of pyramid_zcml with this release of
Pyramid.

The introspector argument to the pyramid.config.Configurator
constructor API has been removed. It has been replaced by the boolean
introspection flag.

The pyramid.registry.noop_introspector API object has been removed.

The older deprecated set_notfound_view Configurator method is now an
alias for the new add_notfound_view Configurator method. Likewise, the
older deprecated set_forbidden_view is now an alias for the new
add_forbidden_view. This has the following impact: the context sent
to views with a (context,request) call signature registered via the
set_notfound_view or set_forbidden_view will now be an exception
object instead of the actual resource context found. Use
request.context to get the actual resource context. It’s also
recommended to disuse set_notfound_view in favor of
add_notfound_view, and disuse set_forbidden_view in favor of
add_forbidden_view despite the aliasing.

The API documentation for pyramid.view.append_slash_notfound_view and
pyramid.view.AppendSlashNotFoundViewFactory was removed. These names
still exist and are still importable, but they are no longer APIs. Use
pyramid.config.Configurator.add_notfound_view(append_slash=True) or
pyramid.view.notfound_view_config(append_slash=True) to get the same
behavior.

The set_forbidden_view and set_notfound_view methods of the
Configurator were removed from the documentation. They have been
deprecated since Pyramid 1.1.

The static file response object used by config.add_static_view opened
the static file twice, when it only needed to open it once.

The AppendSlashNotFoundViewFactory used request.path to match routes. This
was wrong because request.path contains the script name, and this would
cause it to fail in circumstances where the script name was not empty. It
should have used request.path_info, and now does.

Updated the “Creating a Not Found View” section of the “Hooks” chapter,
replacing explanations of registering a view using add_view or
view_config with ones using add_notfound_view or
notfound_view_config.

Updated the “Creating a Not Forbidden View” section of the “Hooks” chapter,
replacing explanations of registering a view using add_view or
view_config with ones using add_forbidden_view or
forbidden_view_config.

Updated the “Redirecting to Slash-Appended Routes” section of the “URL
Dispatch” chapter, replacing explanations of registering a view using
add_view or view_config with ones using add_notfound_view or
notfound_view_config

Updated all tutorials to use pyramid.view.forbidden_view_config rather
than pyramid.view.view_config with an HTTPForbidden context.

The scan method of a Configurator can be passed an ignore
argument, which can be a string, a callable, or a list consisting of
strings and/or callables. This feature allows submodules, subpackages, and
global objects from being scanned. See
http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
more information about how to use the ignore argument to scan.

Better error messages when a view callable returns a value that cannot be
converted to a response (for example, when a view callable returns a
dictionary without a renderer defined, or doesn’t return any value at all).
The error message now contains information about the view callable itself
as well as the result of calling it.

Better error message when a .pyc-only module is config.include -ed.
This is not permitted due to error reporting requirements, and a better
error message is shown when it is attempted. Previously it would fail with
something like “AttributeError: ‘NoneType’ object has no attribute
‘rfind’”.

Add pyramid.config.Configurator.add_traverser API method. See the
Hooks narrative documentation section entitled “Changing the Traverser” for
more information. This is not a new feature, it just provides an API for
adding a traverser without needing to use the ZCA API.

Add pyramid.config.Configurator.add_resource_url_adapter API method.
See the Hooks narrative documentation section entitled “Changing How
pyramid.request.Request.resource_url Generates a URL” for more information.
This is not a new feature, it just provides an API for adding a resource
url adapter without needing to use the ZCA API.

The system value req is now supplied to renderers as an alias for
request. This means that you can now, for example, in a template, do
req.route_url(...) instead of request.route_url(...). This is
purely a change to reduce the amount of typing required to use request
methods and attributes from within templates. The value request is
still available too, this is just an alternative.

A new interface was added: pyramid.interfaces.IResourceURL. An adapter
implementing its interface can be used to override resource URL generation
when request.resource_url is called. This interface replaces the
now-deprecated pyramid.interfaces.IContextURL interface.

The dictionary passed to a resource’s __resource_url__ method (see
“Overriding Resource URL Generation” in the “Resources” chapter) now
contains an app_url key, representing the application URL generated
during request.resource_url. It represents a potentially customized
URL prefix, containing potentially custom scheme, host and port information
passed by the user to request.resource_url. It should be used instead
of request.application_url where necessary.

The request.resource_url API now accepts these arguments: app_url,
scheme, host, and port. The app_url argument can be used to
replace the URL prefix wholesale during url generation. The scheme,
host, and port arguments can be used to replace the respective
default values of request.application_url partially.

A new API named request.resource_path now exists. It works like
request.resource_url but produces a relative URL rather than an
absolute one.

The request.route_url API now accepts these arguments: _app_url,
_scheme, _host, and _port. The _app_url argument can be
used to replace the URL prefix wholesale during url generation. The
_scheme, _host, and _port arguments can be used to replace the
respective default values of request.application_url partially.

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.

Create a “MakoRendererFactoryHelper” that provides customizable settings
key prefixes. Allows settings prefixes other than “mako.” to be used to
create different factories that don’t use the global mako settings. This
will be useful for the debug toolbar, which can currently be sabotaged by
someone using custom mako configuration settings.

New API: pyramid.config.Configurator.set_request_property. Add lazy
property descriptors to a request without changing the request factory.
This method provides conflict detection and is the suggested way to add
properties to a request.

The path_info route and view predicates now match against
request.upath_info (Unicode) rather than request.path_info
(indeterminate value based on Python 3 vs. Python 2). This has to be done
to normalize matching on Python 2 and Python 3.

New API: pyramid.request.Request.set_property. Add lazy property
descriptors to a request without changing the request factory. New
properties may be reified, effectively caching the value for the lifetime
of the instance. Common use-cases for this would be to get a database
connection for the request or identify the current user.

The documentation of pyramid.events.subscriber indicated that using it
as a decorator with no arguments like this:

@subscriber()defsomefunc(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.

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.

Added a prequest script (along the lines of pasterrequest). It is
documented in the “Command-Line Pyramid” chapter in the section entitled
“Invoking a Request”.

Add undocumented __discriminator__ API to derived view callables.
e.g. adapters.lookup(...).__discriminator__(context,request). It will
be used by superdynamic systems that require the discriminator to be used
for introspection after manual view lookup.

New API: pyramid.view.view_defaults. If you use a class as a view, you
can use the new view_defaults class decorator on the class to provide
defaults to the view configuration information used by every
@view_config decorator that decorates a method of that class. It also
works against view configurations involving a class made imperatively.

Added a backwards compatibility knob to pcreate to emulate pastercreate handling for the --list-templates option.

Changed scaffolding machinery around a bit to make it easier for people who
want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
1.2.X and 1.3.X. See the new “Creating Pyramid Scaffolds” chapter in the
narrative documentation for more info.

The template_renderer method of pyramid.scaffolds.PyramidScaffold
was renamed to render_template. If you were overriding it, you’re a
bad person, because it wasn’t an API before now. But we’re nice so we’re
letting you know.

New pyramid.compat module and API documentation which provides Python
2/3 straddling support for Pyramid add-ons and development environments.

A mako.directories setting is no longer required to use Mako templates
Rationale: Mako template renderers can be specified using an absolute asset
spec. An entire application can be written with such asset specs,
requiring no ordered lookup path.

bpython interpreter compatibility in pshell. See the “Command-Line
Pyramid” narrative docs chapter for more information.

Added get_appsettings API function to the pyramid.paster module.
This function returns the settings defined within an [app:...] section
in a PasteDeploy ini file.

Added setup_logging API function to the pyramid.paster module.
This function sets up Python logging according to the logging configuration
in a PasteDeploy ini file.

Configuration conflict reporting is reported in a more understandable way
(“Line 11 in file...” vs. a repr of a tuple of similar info).

A configuration introspection system was added; see the narrative
documentation chapter entitled “Pyramid Configuration Introspection” for
more information. New APIs: pyramid.registry.Introspectable,
pyramid.config.Configurator.introspector,
pyramid.config.Configurator.introspectable,
pyramid.registry.Registry.introspector.

Allow extra keyword arguments to be passed to the
pyramid.config.Configurator.action method.

New APIs: pyramid.path.AssetResolver and
pyramid.path.DottedNameResolver. The former can be used to resolve
asset specifications, the latter can be used to resolve dotted names to
modules or packages.

Pyramid no longer runs on Python 2.5 (which includes the most recent
release of Jython and the Python 2.5 version of GAE as of this writing).

The paster command is no longer the documented way to create projects,
start the server, or run debugging commands. To create projects from
scaffolds, pastercreate is replaced by the pcreate console script.
To serve up a project, pasterserve is replaced by the pserve
console script. New console scripts named pshell, pviews,
proutes, and ptweens do what their paster<commandname>
equivalents used to do. Rationale: the Paste and PasteScript packages do
not run under Python 3.

The default WSGI server run as the result of pserve from newly rendered
scaffolding is now the wsgiref WSGI server instead of the
paste.httpserver server. Rationale: Rationale: the Paste and
PasteScript packages do not run under Python 3.

The pshell command (see “paster pshell”) no longer accepts a
--disable-ipython command-line argument. Instead, it accepts a -p
or --python-shell argument, which can be any of the values python,
ipython or bpython.

Removed the pyramid.renderers.renderer_from_name function. It has been
deprecated since Pyramid 1.0, and was never an API.

To use ZCML with versions of Pyramid >= 1.3, you will need pyramid_zcml
version >= 0.8 and zope.configuration version >= 3.8.0. The
pyramid_zcml package version 0.8 is backwards compatible all the way to
Pyramid 1.0, so you won’t be warned if you have older versions installed
and upgrade Pyramid “in-place”; it may simply break instead.

Pyramid no longer depends on the zope.component package, except as a
testing dependency.

Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev,
repoze.lru>=0.4, zope.deprecation>=3.5.0, translationstring>=0.4 (for
Python 3 compatibility purposes). It also, as a testing dependency,
depends on WebTest>=1.3.1 for the same reason.

The SQLAlchemy Wiki tutorial has been updated. It now uses
@view_config decorators and an explicit database population script.

Minor updates to the ZODB Wiki tutorial.

A narrative documentation chapter named “Extending Pyramid Configuration”
was added; it describes how to add a new directive, and how use the
pyramid.config.Configurator.action method within custom directives. It
also describes how to add introspectable objects.

A narrative documentation chapter named “Pyramid Configuration
Introspection” was added. It describes how to query the introspection
system.

The 1.2b1 tarball was a brownbag (particularly for Windows users) because
it contained filenames with stray quotation marks in inappropriate places.
We depend on setuptools-git to produce release tarballs, and when it
was run to produce the 1.2b1 tarball, it didn’t yet cope well with files
present in git repositories with high-order characters in their filenames.

The static file serving machinery could not serve files that started with a
. (dot) character.

Static files with high-order (super-ASCII) characters in their names could
not be served by a static view. The static file serving machinery
inappropriately URL-quoted path segments in filenames when asking for files
from the filesystem.

Within pyramid.traversal.traversal_path , canonicalize URL segments
from UTF-8 to Unicode before checking whether a segment matches literally
one of ., the empty string, or .. in case there’s some sneaky way
someone might tunnel those strings via UTF-8 that don’t match the literals
before decoded.

Support an onerror keyword argument to
pyramid.config.Configurator.scan(). This onerror keyword argument is
passed to venusian.Scanner.scan() to influence error behavior when
an exception is raised during scanning.

The request_method predicate argument to
pyramid.config.Configurator.add_view and
pyramid.config.Configurator.add_route is now permitted to be a tuple of
HTTP method names. Previously it was restricted to being a string
representing a single HTTP method name.

Undeprecated pyramid.traversal.find_model,
pyramid.traversal.model_path, pyramid.traversal.model_path_tuple,
and pyramid.url.model_url, which were all deprecated in Pyramid 1.0.
There’s just not much cost to keeping them around forever as aliases to
their renamed resource_* prefixed functions.

Undeprecated pyramid.view.bfg_view, which was deprecated in Pyramid
1.0. This is a low-cost alias to pyramid.view.view_config which we’ll
just keep around forever.

Pyramid did not properly generate static URLs using
pyramid.url.static_url when passed a caller-package relative path due
to a refactoring done in 1.2a1.

The settings object emitted a deprecation warning any time
__getattr__ was called upon it. However, there are legitimate
situations in which __getattr__ is called on arbitrary objects
(e.g. hasattr). Now, the settings object only emits the warning
upon successful lookup.

When a renderers= argument is not specified to the Configurator
constructor, eagerly register and commit the default renderer set. This
permits the overriding of the default renderers, which was broken in 1.2a1
without a commit directly after Configurator construction.

Mako rendering exceptions had the wrong value for an error message.

An include could not set a root factory successfully because the
Configurator constructor unconditionally registered one that would be
treated as if it were “the word of the user”.

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 pasterptweens, 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”.

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.

The Pyramid “exception view” machinery is now implemented as a “tween”
(pyramid.tweens.excview_tween_factory).

WSGIHTTPException (HTTPFound, HTTPNotFound, etc) now has a new API named
“prepare” which renders the body and content type when it is provided with
a WSGI environ. Required for debug toolbar.

Once __call__ or prepare is called on a WSGIHTTPException, the body
will be set, and subsequent calls to __call__ will always return the
same body. Delete the body attribute to rerender the exception body.

Previously the pyramid.events.BeforeRender event wrapped a dictionary
(it addressed it as its _system attribute). Now it is a dictionary
(it inherits from dict), and it’s the value that is passed to templates
as a top-level dictionary.

The route_url, route_path, resource_url, static_url, and
current_route_url functions in the pyramid.url package now delegate
to a method on the request they’ve been passed, instead of the other way
around. The pyramid.request.Request object now inherits from a mixin named
pyramid.url.URLMethodsMixin to make this possible, and all url/path
generation logic is embedded in this mixin.

Refactor pyramid.config into a package.

Removed the _set_security_policies method of the Configurator.

Moved the StaticURLInfo class from pyramid.static to
pyramid.config.views.

Move the Settings class from pyramid.settings to
pyramid.config.settings.

Move the OverrideProvider, PackageOverrides, DirectoryOverride,
and FileOverride classes from pyramid.asset to
pyramid.config.assets.

All Pyramid-related deployment settings (e.g. debug_all,
debug_notfound) are now meant to be prefixed with the prefix
pyramid.. For example: debug_all -> pyramid.debug_all. The
old non-prefixed settings will continue to work indefinitely but supplying
them may eventually print a deprecation warning. All scaffolds and
tutorials have been changed to use prefixed settings.

The settings dictionary now raises a deprecation warning when you
attempt to access its values via __getattr__ instead of
via __getitem__.

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:

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.

Narrative and API documentation which used the route_url,
route_path, resource_url, static_url, and current_route_url
functions in the pyramid.url package have now been changed to use
eponymous methods of the request instead.

All scaffolds now use the pyramid_tm package rather than the
repoze.tm2 middleware to manage transaction management.

The ZODB scaffold now uses the pyramid_zodbconn package rather than the
repoze.zodbconn package to provide ZODB integration.

All scaffolds now use the pyramid_debugtoolbar package rather than the
WebError package to provide interactive debugging features.

Projects created via a scaffold no longer depend on the WebError
package at all; configuration in the production.ini file which used to
require its error_catcher middleware has been removed. Configuring
error catching / email sending is now the domain of the pyramid_exclog
package (see http://docs.pylonsproject.org/projects/pyramid_exclog/dev/).

Added the pyramid.renderers.null_renderer object as an API. The null
renderer is an object that can be used in advanced integration cases as
input to the view configuration renderer= argument. When the null
renderer is used as a view renderer argument, Pyramid avoids converting the
view callable result into a Response object. This is useful if you want to
reuse the view configuration and lookup machinery outside the context of
its use by the Pyramid router. This feature was added for consumption by
the pyramid_rpc package, which uses view configuration and lookup
outside the context of a router in exactly this way. pyramid_rpc has
been broken under 1.1 since 1.1b1; adding it allows us to make it work
again.

Change all scaffolding templates that point to docs.pylonsproject.org to
use /projects/pyramid/current rather than /projects/pyramid/dev.

The pasterpshell, pasterpviews, and pasterproutes commands
each now under the hood uses pyramid.paster.bootstrap, which makes it
possible to supply an .ini file without naming the “right” section in
the file that points at the actual Pyramid application. Instead, you can
generally just run paster{pshell|proutes|pviews}development.ini and
it will do mostly the right thing.

Omit custom environ variables when rendering a custom exception template in
pyramid.httpexceptions.WSGIHTTPException._set_default_attrs;
stringifying thse may trigger code that should not be executed; see
https://github.com/Pylons/pyramid/issues/239

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.:

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:

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

frompyramid.scriptingimportmake_requestrequest=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.

The pyramid.view.static class has been deprecated in favor of the newer
pyramid.static.static_view class. A deprecation warning is raised when
it is used. You should replace it with a reference to
pyramid.static.static_view with the use_subpath=True argument.

Without a mo-file loaded for the combination of domain/locale,
pyramid.i18n.Localizer.pluralize run using that domain/locale
combination raised an inscrutable “translations object has no attr
‘plural’” error. Now, instead it “works” (it uses a germanic pluralization
by default). It’s nonsensical to try to pluralize something without
translations for that locale/domain available, but this behavior matches
the behavior of pyramid.i18n.Localizer.translate so it’s at least
consistent; see https://github.com/Pylons/pyramid/issues/235.

New environment setting PYRAMID_PREVENT_HTTP_CACHE and new
configuration file value prevent_http_cache. These are synomymous and
allow you to prevent HTTP cache headers from being set by Pyramid’s
http_cache machinery globally in a process. see the “Influencing HTTP
Caching” section of the “View Configuration” narrative chapter and the
detailed documentation for this setting in the “Environment Variables and
Configuration Settings” narrative chapter.

Previously, If a BeforeRender event subscriber added a value via the
__setitem__ or update methods of the event object with a key that
already existed in the renderer globals dictionary, a KeyError was
raised. With the deprecation of the “add_renderer_globals” feature of the
configurator, there was no way to override an existing value in the
renderer globals dictionary that already existed. Now, the event object
will overwrite an older value that is already in the globals dictionary
when its __setitem__ or update is called (as well as the new
setdefault method), just like a plain old dictionary. As a result, for
maximum interoperability with other third-party subscribers, if you write
an event subscriber meant to be used as a BeforeRender subscriber, your
subscriber code will now need to (using .get or __contains__ of the
event object) ensure no value already exists in the renderer globals
dictionary before setting an overriding value.

The Configurator.add_route method allowed two routes with the same
route to be added without an intermediate config.commit(). If you now
receive a ConfigurationError at startup time that appears to be
add_route related, you’ll need to either a) ensure that all of your
route names are unique or b) call config.commit() before adding a
second route with the name of a previously added name or c) use a
Configurator that works in autocommit mode.

The pyramid_routesalchemy and pyramid_alchemy scaffolds
inappropriately used DBSession.rollback() instead of
transaction.abort() in one place.

We now clear request.response before we invoke an exception view; an
exception view will be working with a request.response that has not been
touched by any code prior to the exception.

Wiki2 (SQLAlchemy + URL Dispatch) tutorial models.initialize_sql didn’t
match the pyramid_routesalchemy scaffold function of the same name; it
didn’t get synchronized when it was changed in the scaffold.

It is now possible to invoke pasterpshell 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.

pasterpshell 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:

A nonzero integer. If it’s a nonzero integer, it’s treated as a number
of seconds. This number of seconds will be used to compute the
Expires header and the Cache-Control:max-age parameter of
responses to requests which call this view. For example:
http_cache=3600 instructs the requesting browser to ‘cache this
response for an hour, please’.

A datetime.timedelta instance. If it’s a datetime.timedelta
instance, it will be converted into a number of seconds, and that number
of seconds will be used to compute the Expires header and the
Cache-Control:max-age parameter of responses to requests which call
this view. For example: http_cache=datetime.timedelta(days=1)
instructs the requesting browser to ‘cache this response for a day,
please’.

Zero (0). If the value is zero, the Cache-Control and
Expires headers present in all responses from this view will be
composed such that client browser cache (and any intermediate caches) are
instructed to never cache the response.

A two-tuple. If it’s a two tuple (e.g. http_cache=(1,{'public':True})), the first value in the tuple may be a nonzero
integer or a datetime.timedelta instance; in either case this value
will be used as the number of seconds to cache the response. The second
value in the tuple must be a dictionary. The values present in the
dictionary will be used as input to the Cache-Control response
header. For example: http_cache=(3600,{'public':True}) means ‘cache
for an hour, and add public to the Cache-Control header of the
response’. All keys and values supported by the
webob.cachecontrol.CacheControl interface may be added to the
dictionary. Supplying {'public':True} is equivalent to calling
response.cache_control.public=True.

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}).

Framework wrappers of the original view (such as http_cached and so on)
relied on being able to trust that the response they were receiving was an
IResponse. It wasn’t always, because the response was resolved by the
router instead of early in the view wrapping process. This has been fixed.

The pasterpshell, pasterproutes, and pasterpviews commands
now take a single argument in the form /path/to/config.ini#sectionname
rather than the previous 2-argument spelling /path/to/config.inisectionname. #sectionname may be omitted, in which case #main is
assumed.

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:

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.:

The Wiki and Wiki2 tutorial “Tests” chapters each had two bugs: neither did
told the user to depend on WebTest, and 2 tests failed in each as the
result of changes to Pyramid itself. These issues have been fixed.

1.1a1 broke Akhet by not providing a backwards compatibility import shim
for pyramid.paster.PyramidTemplate. Now one has been added, although a
deprecation warning is emitted when Akhet imports it.

If multiple specs were provided in a single call to
config.add_translation_dirs, the directories were inserted into the
beginning of the directory list in the wrong order: they were inserted in
the reverse of the order they were provided in the *specs list (items
later in the list were added before ones earlier in the list). This is now
fixed.

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 objecttry: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'].

The term “template” used to refer to both “paster templates” and “rendered
templates” (templates created by a rendering engine. i.e. Mako, Chameleon,
Jinja, etc.). “Paster templates” will now be refered to as “scaffolds”,
whereas the name for “rendered templates” will remain as “templates.”

The wiki (ZODB+Traversal) tutorial was updated slightly.

The wiki2 (SQLA+URL Dispatch) tutorial was updated slightly.

Make pyramid.interfaces.IAuthenticationPolicy and
pyramid.interfaces.IAuthorizationPolicy public interfaces, and refer to
them within the pyramid.authentication and pyramid.authorization
API docs.

Render the function definitions for each exposed interface in
pyramid.interfaces.

Add missing docs reference to
pyramid.config.Configurator.set_view_mapper and refer to it within
Hooks chapter section named “Using a View Mapper”.

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.

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 pasterpviews 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.

URL pattern markers used in URL dispatch are permitted to specify a custom
regex. For example, the pattern /{foo:\d+} means to match /12345
(foo==12345 in the match dictionary) but not /abc. However, custom
regexes in a pattern marker which used squiggly brackets did not work. For
example, /{foo:\d{4}} would fail to match /1234 and
/{foo:\d{1,2}} would fail to match /1 or /11. One level of
inner squiggly brackets is now recognized so that the prior two patterns
given as examples now work. See also
https://github.com/Pylons/pyramid/issues/#issue/123.

Static views registered with config.add_static_view which also included
a permission keyword argument would not work as expected, because
add_static_view also registered a route factory internally. Because a
route factory was registered internally, the context checked by the Pyramid
permission machinery never had an ACL. add_static_view no longer
registers a route with a factory, so the default root factory will be used.

config.add_static_view now passes extra keyword arguments it receives
to config.add_route (calling add_static_view is mostly logically
equivalent to adding a view of the type pyramid.static.static_view
hooked up to a route with a subpath). This makes it possible to pass e.g.,
factory= to add_static_view to protect a particular static view
with a custom ACL.

testing.DummyRequest used the wrong registry (the global registry) as
self.registry if a dummy request was created beforetesting.setUp
was executed (testing.setUp pushes a local registry onto the
threadlocal stack). Fixed by implementing registry as a property for
DummyRequest instead of eagerly assigning an attribute.
See also https://github.com/Pylons/pyramid/issues/165

When visiting a URL that represented a static view which resolved to a
subdirectory, the index.html of that subdirectory would not be served
properly. Instead, a redirect to /subdir would be issued. This has
been fixed, and now visiting a subdirectory that contains an index.html
within a static view returns the index.html properly. See also
https://github.com/Pylons/pyramid/issues/67.

Redirects issued by a static view did not take into account any existing
SCRIPT_NAME (such as one set by a url mapping composite). Now they do.

The pyramid.wsgi.wsgiapp2 decorator did not take into account the
SCRIPT_NAME in the origin request.

The pyramid.wsgi.wsgiapp2 decorator effectively only worked when it
decorated a view found via traversal; it ignored the PATH_INFO that was
part of a url-dispatch-matched view.

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:

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:

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 default Mako renderer is now configured to escape all HTML in
expression tags. This is intended to help prevent XSS attacks caused by
rendering unsanitized input from users. To revert this behavior in user’s
templates, they need to filter the expression through the ‘n’ filter.
For example, ${ myhtml | n }.
See https://github.com/Pylons/pyramid/issues/193.

A custom request factory is now required to return a request object that
has a response attribute (or “reified”/lazy property) if they the
request is meant to be used in a view that uses a renderer. This
response attribute should be an instance of the class
pyramid.response.Response.

The JSON and string renderer factories now assign to
request.response.content_type rather than
request.response_content_type.

Each built-in renderer factory now determines whether it should change the
content type of the response by comparing the response’s content type
against the response’s default content type; if the content type is the
default content type (usually text/html), the renderer changes the
content type (to application/json or text/plain for JSON and string
renderers respectively).

The pyramid.wsgi.wsgiapp2 now uses a slightly different method of
figuring out how to “fix” SCRIPT_NAME and PATH_INFO for the
downstream application. As a result, those values may differ slightly from
the perspective of the downstream application (for example, SCRIPT_NAME
will now never possess a trailing slash).

Previously, pyramid.request.Request inherited from
webob.request.Request and implemented __getattr__, __setattr__
and __delattr__ itself in order to overidde “adhoc attr” WebOb behavior
where attributes of the request are stored in the environ. Now,
pyramid.request.Request object inherits from (the more recent)
webob.request.BaseRequest instead of webob.request.Request, which
provides the same behavior. pyramid.request.Request no longer
implements its own __getattr__, __setattr__ or __delattr__ as a
result.

pyramid.response.Response is now a subclass of
webob.response.Response (in order to directly implement the
pyramid.interfaces.IResponse interface).

The “exception response” objects importable from pyramid.httpexceptions
(e.g. HTTPNotFound) are no longer just import aliases for classes that
actually live in webob.exc. Instead, we’ve defined our own exception
classes within the module that mirror and emulate the webob.exc
exception response objects almost entirely. See the “Design Defense” doc
section named “Pyramid Uses its Own HTTP Exception Classes” for more
information.

Pyramid no longer supports Python 2.4. Python 2.5 or better is required to
run Pyramid 1.1+.

The Pyramid router now, by default, expects response objects returned from
view callables to implement the pyramid.interfaces.IResponse interface.
Unlike the Pyramid 1.0 version of this interface, objects which implement
IResponse now must define a __call__ method that accepts environ
and start_response, and which returns an app_iter iterable, among
other things. Previously, it was possible to return any object which had
the three WebOb app_iter, headerlist, and status attributes as
a response, so this is a backwards incompatibility. It is possible to get
backwards compatibility back by registering an adapter to IResponse from
the type of object you’re now returning from view callables. See the
section in the Hooks chapter of the documentation entitled “Changing How
Pyramid Treats View Responses”.

The pyramid.interfaces.IResponse interface is now much more extensive.
Previously it defined only app_iter, status and headerlist; now
it is basically intended to directly mirror the webob.Response API,
which has many methods and attributes.

The pyramid.httpexceptions classes named HTTPFound,
HTTPMultipleChoices, HTTPMovedPermanently, HTTPSeeOther,
HTTPUseProxy, and HTTPTemporaryRedirect now accept location as
their first positional argument rather than detail. This means that
you can do, e.g. returnpyramid.httpexceptions.HTTPFound('http://foo')
rather than returnpyramid.httpexceptions.HTTPFound(location='http//foo') (the latter will
of course continue to work).

Pyramid now depends on WebOb >= 1.0.2 as tests depend on the bugfix in that
release: “Fix handling of WSGI environs with missing SCRIPT_NAME”.
(Note that in reality, everyone should probably be using 1.0.4 or better
though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag releases.)

Removed duplicate implementations of is_response. Two competing
implementations existed: one in pyramid.config and one in
pyramid.view. Now the one defined in pyramid.view is used
internally by pyramid.config and continues to be advertised as an API.

The production.ini generated by all paster templates now have an
effective logging level of WARN, which prevents e.g. SQLAlchemy statement
logging and other inappropriate output.

The production.ini of the pyramid_routesalchemy and
pyramid_alchemy paster templates did not have a sqlalchemy logger
section, preventing pasterserveproduction.ini from working.

The pyramid_routesalchemy and pyramid_alchemy paster templates used
the {{package}} variable in a place where it should have used the
{{project}} variable, causing applications created with uppercase
letters e.g. pastercreate-tpyramid_routesalchemyDibbus to fail to
start when pasterservedevelopment.ini was used against the result.
See https://github.com/Pylons/pyramid/issues/#issue/107

The render_view method of pyramid.renderers.RendererHelper passed
an incorrect value into the renderer for renderer_info. It now passes
an instance of RendererHelper instead of a dictionary, which is
consistent with other usages. See
https://github.com/Pylons/pyramid/issues#issue/106

A bug existed in the pyramid.authentication.AuthTktCookieHelper which
would break any usage of an AuthTktAuthenticationPolicy when one was
configured to reissue its tokens (reissue_time < timeout /
max_age). Symptom: ValueError:('Invalidtoken%r',''). See
https://github.com/Pylons/pyramid/issues#issue/108.

The AuthTktAuthenticationPolicy now accepts a tokens parameter via
pyramid.security.remember. The value must be a sequence of strings.
Tokens are placed into the auth_tkt “tokens” field and returned in the
auth_tkt cookie.

Add wild_domain argument to AuthTktAuthenticationPolicy, which defaults
to True. If it is set to False, the feature of the policy which
sets a cookie with a wilcard domain will be turned off.

Using testing.setUp now registers an ISettings utility as a side
effect. Some test code which queries for this utility after
testing.setUp via queryAdapter will expect a return value of None.
This code will need to be changed.

When a pyramid.exceptions.Forbidden error is raised, its status code
now 403Forbidden. It was previously 401Unauthorized, for
backwards compatibility purposes with repoze.bfg. This change will
cause problems for users of Pyramid with repoze.who, which intercepts
401Unauthorized by default, but allows 403Forbidden to pass
through. Those deployments will need to configure repoze.who to also
react to 403Forbidden.

The default value for the cookie_on_exception parameter to
pyramid.session.UnencyrptedCookieSessionFactory is now True. This
means that when view code causes an exception to be raised, and the session
has been mutated, a cookie will be sent back in the response. Previously
its default value was False.

The pyramid_zodb, pyramid_routesalchemy and pyramid_alchemy
paster templates now use a default “commit veto” hook when configuring the
repoze.tm2 transaction manager in development.ini. This prevents a
transaction from being committed when the response status code is within
the 400 or 500 ranges. See also
http://docs.repoze.org/tm2/#using-a-commit-veto.

The add_handler method of a Configurator has been removed from the
Pyramid core. Handlers are now a feature of the pyramid_handlers
package, which can be downloaded from PyPI. Documentation for the package
should be available via
http://pylonsproject.org/projects/pyramid_handlers/dev/, which describes how
to add a configuration statement to your main block to reobtain this
method. You will also need to add an install_requires dependency upon
pyramid_handlers to your setup.py file.

The load_zcml method of a Configurator has been removed from the
Pyramid core. Loading ZCML is now a feature of the pyramid_zcml
package, which can be downloaded from PyPI. Documentation for the package
should be available via
http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how
to add a configuration statement to your main block to reobtain this
method. You will also need to add an install_requires dependency upon
pyramid_zcml to your setup.py file.

The pyramid.includes subpackage has been removed. ZCML files which use
include the package pyramid.includes (e.g. <includepackage="pyramid.includes"/>) now must include the pyramid_zcml
package instead (e.g. <includepackage="pyramid_zcml"/>).

The pyramid.view.action decorator has been removed from the Pyramid
core. Handlers are now a feature of the pyramid_handlers package. It
should now be imported from pyramid_handlers e.g. frompyramid_handlersimportaction.

The handler ZCML directive has been removed. It is now a feature of
the pyramid_handlers package.

The pylons_minimal, pylons_basic and pylons_sqla paster
templates were removed. Use pyramid_sqla (available from PyPI) as a
generic replacement for Pylons-esque development.

The make_app function has been removed from the pyramid.router
module. It continues life within the pyramid_zcml package. This
leaves the pyramid.router module without any API functions.

The configure_zcml setting within the deployment settings (within
**settings passed to a Pyramid main function) has ceased to have any
meaning.

pyramid.testing.setUp and pyramid.testing.tearDown have been
undeprecated. They are now the canonical setup and teardown APIs for test
configuration, replacing “direct” creation of a Configurator. This is a
change designed to provide a facade that will protect against any future
Configurator deprecations.

When Configurator.include is passed a module as an argument, it
defaults to attempting to find and use a callable named includeme
within that module. This makes it possible to use
config.include('some.module') rather than
config.include('some.module.somefunc') as long as the include function
within some.module is named includeme.

The bfg2pyramid script now converts ZCML include tags that have
repoze.bfg.includes as a package attribute to the value
pyramid_zcml. For example, <includepackage="repoze.bfg.includes">
will be converted to <includepackage="pyramid_zcml">.

Deprecation warnings related to import of the following API functions were
added: pyramid.traversal.find_model, pyramid.traversal.model_path,
pyramid.traversal.model_path_tuple, pyramid.url.model_url. The
instructions emitted by the deprecation warnings instruct the developer to
change these method spellings to their resource equivalents. This is a
consequence of the mass concept rename of “model” to “resource” performed
in 1.0a7.

The proutes command tried too hard to resolve the view for printing,
resulting in exceptions when an exceptional root factory was encountered.
Instead of trying to resolve the view, if it cannot, it will now just print
<unknown>.

The self argument was included in new methods of the ISession interface
signature, causing pyramid_beaker tests to fail.

Readd pyramid.traversal.model_path_tuple as an alias for
pyramid.traversal.resource_path_tuple for backwards compatibility.

Add a new API pyramid.url.current_route_url, which computes a URL based
on the “current” route (if any) and its matchdict values.

config.add_view now accepts a decorator keyword argument, a callable
which will decorate the view callable before it is added to the registry.

If a handler class provides an __action_decorator__ attribute (usually
a classmethod or staticmethod), use that as the decorator for each view
registration for that handler.

The pyramid.interfaces.IAuthenticationPolicy interface now specifies an
unauthenticated_userid method. This method supports an important
optimization required by people who are using persistent storages which do
not support object caching and whom want to create a “user object” as a
request attribute.

A new API has been added to the pyramid.security module named
unauthenticated_userid. This API function calls the
unauthenticated_userid method of the effective security policy.

An unauthenticated_userid method has been added to the dummy
authentication policy returned by
pyramid.config.Configurator.testing_securitypolicy. It returns the
same thing as that the dummy authentication policy’s
authenticated_userid method.

The class pyramid.authentication.AuthTktCookieHelper is now an API.
This class can be used by third-party authentication policy developers to
help in the mechanics of authentication cookie-setting.

New constructor argument to Configurator: default_view_mapper. Useful
to create systems that have alternate view calling conventions. A view
mapper allows objects that are meant to be used as view callables to have
an arbitrary argument list and an arbitrary result. The object passed as
default_view_mapper should implement the
pyramid.interfaces.IViewMapperFactory interface.

add a set_view_mapper API to Configurator. Has
the same result as passing default_view_mapper to the Configurator
constructor.

config.add_view now accepts a mapper keyword argument, which should
either be None, a string representing a Python dotted name, or an
object which is an IViewMapperFactory. This feature is not useful for
“civilians”, only for extension writers.

Allow static renderer provided during view registration to be overridden at
request time via a request attribute named override_renderer, which
should be the name of a previously registered renderer. Useful to provide
“omnipresent” RPC using existing rendered views.

Instances of pyramid.testing.DummyRequest now have a session
object, which is mostly a dictionary, but also implements the other session
API methods for flash and CSRF.

Since the pyramid.interfaces.IAuthenticationPolicy interface now
specifies that a policy implementation must implement an
unauthenticated_userid method, all third-party custom authentication
policies now must implement this method. It, however, will only be called
when the global function named pyramid.security.unauthenticated_userid
is invoked, so if you’re not invoking that, you will not notice any issues.

pyramid.interfaces.ISession.get_csrf_token now mandates that an
implementation should return a new token if one doesn’t already exist in
the session (previously it would return None). The internal sessioning
implementation has been changed.

The “view derivation” code is now factored into a set of classes rather
than a large number of standalone functions (a side effect of the
view mapper refactoring).

The pyramid.renderer.RendererHelper class has grown a render_view
method, which is used by the default view mapper (a side effect of the
view mapper refactoring).

The object passed as renderer to the “view deriver” is now an instance
of pyramid.renderers.RendererHelper rather than a dictionary (a side
effect of view mapper refactoring).

The class used as the “page template” in pyramid.chameleon_text was
removed, in preference to using a Chameleon-inbuilt version.

A view callable wrapper registered in the registry now contains an
__original_view__ attribute which references the original view callable
(or class).

The (non-API) method of all internal authentication policy implementations
previously named _get_userid is now named unauthenticated_userid,
promoted to an API method. If you were overriding this method, you’ll now
need to override it as unauthenticated_userid instead.

If a resource implements a __resource_url__ method, it will be called
as the result of invoking the pyramid.url.resource_url function to
generate a URL, overriding the default logic. See the new “Generating The
URL Of A Resource” section within the Resources narrative chapter.

Added flash messaging, as described in the “Flash Messaging” narrative
documentation chapter.

Added “Advanced Configuration” narrative chapter which documents how to
deal with configuration conflicts, two-phase configuration, include and
commit.

Fix API documentation rendering for pyramid.view.static

Add “Pyramid Provides More Than One Way to Do It” to Design Defense
documentation.

Changed “Static Assets” narrative chapter: clarify that name represents
a prefix unless it’s a URL, added an example of a root-relative static view
fallback for URL dispatch, added an example of creating a simple view that
returns the body of a file.

1.0a5 introduced a bug when pyramid.config.Configurator.scan was used
without a package argument (e.g. config.scan() as opposed to
config.scan('packagename'). The symptoms were: lots of deprecation
warnings printed to the console about imports of deprecated Pyramid
functions and classes and non-detection of view callables decorated with
view_config decorators. This has been fixed.

Tests now pass on Windows (no bugs found, but a few tests in the test suite
assumed UNIX path segments in filenames).

If you followed it to-the-letter, the ZODB+Traversal Wiki tutorial would
instruct you to run a test which would fail because the view callable
generated by the pyramid_zodb tutorial used a one-arg view callable,
but the test in the sample code used a two-arg call.

Updated ZODB+Traversal tutorial setup.py of all steps to match what’s
generated by pyramid_zodb.

The pyramid.testing.setUp function now accepts an autocommit
keyword argument, which defaults to True. If it is passed False,
the Config object returned by setUp will be a non-autocommiting Config
object.

Add logging configuration to all paster templates.

pyramid_alchemy, pyramid_routesalchemy, and pylons_sqla paster
templates now use idiomatic SQLAlchemy configuration in their respective
.ini files and Python code.

pyramid.testing.DummyRequest now has a class variable,
query_string, which defaults to the empty string.

Add support for json on GAE by catching NotImplementedError and importing
simplejson from django.utils.

The Mako renderer now accepts a resource specification for
mako.module_directory.

When creating a Configurator from within a pasterpshell session, you
were required to pass a package argument although package is not
actually required. If you didn’t pass package, you would receive an
error something like KeyError:'__name__' emanating from the
pyramid.path.caller_module function. This has now been fixed.

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.

URL Dispatch now allows for replacement markers to be located anywhere
in the pattern, instead of immediately following a /.

URL Dispatch now uses the form {marker} to denote a replace marker in
the route pattern instead of :marker. The old colon-style marker syntax
is still accepted for backwards compatibility. The new format allows a
regular expression for that marker location to be used instead of the
default [^/]+, for example {marker:\d+} is now valid to require the
marker to be digits.

Add a pyramid.url.route_path API, allowing folks to generate relative
URLs. Calling route_path is the same as calling
pyramid.url.route_url with the argument _app_url equal to the empty
string.

Add a pyramid.request.Request.route_path API. This is a convenience
method of the request which calls pyramid.url.route_url.

Make test suite pass on Jython (requires PasteScript trunk, presumably to
be 1.7.4).

Make test suite pass on PyPy (Chameleon doesn’t work).

Surrounding application configuration with config.begin() and
config.end() is no longer necessary. All paster templates have been
changed to no longer call these functions.

Fix configurator to not convert ImportError to ConfigurationError
if the import that failed was unrelated to the import requested via a
dotted name when resolving dotted names (such as view dotted names).

Add deprecation warnings to import of pyramid.chameleon_text and
pyramid.chameleon_zpt of get_renderer, get_template,
render_template, and render_template_to_response.

Add deprecation warning for import of pyramid.zcml.zcml_configure and
pyramid.zcml.file_configure.

The pyramid_alchemy paster template had a typo, preventing an import
from working.

Fix apparent failures when calling pyramid.traversal.find_model(root,path) or pyramid.traversal.traverse(path) when path is
(erroneously) a Unicode object. The user is meant to pass these APIs a
string object, never a Unicode object. In practice, however, users indeed
pass Unicode. Because the string that is passed must be ASCII encodeable,
now, if they pass a Unicode object, its data is eagerly converted to an
ASCII string rather than being passed along to downstream code as a
convenience to the user and to prevent puzzling second-order failures from
cropping up (all failures will occur within pyramid.traversal.traverse
rather than later down the line as the result of calling e.g.
traversal_path).

The pyramid.settings.get_settings API is now deprecated. Use
pyramid.threadlocals.get_current_registry().settings instead or use the
settings attribute of the registry available from the request
(request.registry.settings).

Normalized all paster templates: each now uses the name main to
represent the function that returns a WSGI application, each now uses
WebError, each now has roughly the same shape of development.ini style.

Added class vars matchdict and matched_route to
pyramid.request.Request. Each is set to None.

New API method: pyramid.settings.asbool.

New API methods for pyramid.request.Request: model_url,
route_url, and static_url. These are simple passthroughs for their
respective functions in pyramid.url.

The settings object which used to be available only when
request.settings.get_settings was called is now available as
registry.settings (e.g. request.registry.settings in view code).

The pylons_* paster templates erroneously used the {squiggly} routing
syntax as the pattern supplied to add_route. This style of routing is
not supported. They were replaced with :colon style route patterns.

The pylons_* paster template used the same string
(your_app_secret_string) for the session.secret setting in the
generated development.ini. This was a security risk if left unchanged
in a project that used one of the templates to produce production
applications. It now uses a randomly generated string.

Obtaining the settings object via
registry.{get|query}Utility(ISettings) is now deprecated. Instead,
obtain the settings object via the registry.settings attribute. A
backwards compatibility shim was added to the registry object to register
the settings object as an ISettings utility when setattr(registry,'settings',foo) is called, but it will be removed in a later release.

Obtaining the settings object via pyramid.settings.get_settings is
now deprecated. Obtain it as the settings attribute of the registry
now (obtain the registry via pyramid.threadlocal.get_registry or as
request.registry).

Internal: ZCML directives no longer call get_current_registry() if there’s
a registry attribute on the ZCML context (kill off use of
threadlocals).

Internal: Chameleon template renderers now accept two arguments: path
and lookup. Lookup will be an instance of a lookup class which
supplies (late-bound) arguments for debug, reload, and translate. Any
third-party renderers which use (the non-API) function
pyramid.renderers.template_renderer_factory will need to adjust their
implementations to obey the new callback argument list. This change was to
kill off inappropriate use of threadlocals.

All references to events by interface
(e.g. pyramid.interfaces.INewRequest) have been changed to reference
their concrete classes (e.g. pyramid.events.NewRequest) in
documentation about making subscriptions.

All references to Pyramid-the-application were changed from mod-pyramid
to app-Pyramid. A custom role setting was added to docs/conf.py to
allow for this. (internal)

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:

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

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.

The “”bfgwiki2” (SQLAlchemy + url dispatch) tutorial has been
updated slightly. In particular, the source packages no longer
attempt to use a private index, and the recommended Python version
is now 2.6. It was also updated to take into account the changes to
the bfg_routesalchemy template used to set up an environment.

The “bfgwiki” (ZODB + traversal) tutorial has been updated slightly.
In particular, the source packages no longer attempt to use a
private index, and the recommended Python version is now 2.6.

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

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

A prior changelog entry asserted that the INewResponse event was
not sent to listeners if the response was not “valid” (if a view or
renderer returned a response object that did not have a
status/headers/app_iter). This is not true in this release, nor was
it true in 1.3a13.

In support of making it easier to configure applications which are
“secure by default”, a default permission feature was added. If
supplied, the default permission is used as the permission string to
all view registrations which don’t otherwise name a permission.
These APIs are in support of that:

A new constructor argument was added to the Configurator:
default_permission.

A new method was added to the Configurator:
set_default_permission.

A new ZCML directive was added: default_permission.

Add a new request API: request.add_finished_callback. Finished
callbacks are called by the router unconditionally near the very end
of request processing. See the “Using Finished Callbacks” section
of the “Hooks” narrative chapter of the documentation for more
information.

A request.matched_route attribute is now added to the request
when a route has matched. Its value is the “route” object that
matched (see the IRoute interface within
repoze.bfg.interfaces API documentation for the API of a route
object).

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

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

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

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

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

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

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

Fix a bug in repoze.bfg.url.static_url URL generation: if two
resource specifications were used to create two separate static
views, but they shared a common prefix, it was possible that
static_url would generate an incorrect URL.

Fix another bug in repoze.bfg.static_url URL generation: too
many slashes in generated URL.

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

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

The path attribute to the ZCML route directive is now named
pattern for better explicability. The older path attribute
will continue to work indefinitely.

Add an API to the Configurator named get_routes_mapper.
This returns an object implementing the IRoutesMapper interface.

The repoze.bfg.urldispatch.RoutesMapper object now has a
get_route method which returns a single Route object or
None.

A new interface repoze.bfg.interfaces.IRoute was added. The
repoze.bfg.urldispatch.Route object implements this interface.

The canonical attribute for accessing the routing pattern from a
route object is now pattern rather than path.

Use hash() rather than id() when computing the “phash” of a
custom route/view predicate in order to allow the custom predicate
some control over which predicates are “equal”.

Use response.headerlist.append instead of
response.headers.add in
repoze.bfg.request.add_global_response_headers in case the
response is not a WebOb response.

The repoze.bfg.urldispatch.Route constructor (not an API) now
accepts a different ordering of arguments. Previously it was
(pattern,name,factory=None,predicates=()). It is now
(name,pattern,factory=None,predicates=()). This is in
support of consistency with configurator.add_route.

The repoze.bfg.urldispatch.RoutesMapper.connect method (not an
API) now accepts a different ordering of arguments. Previously it
was (pattern,name,factory=None,predicates=()). It is now
(name,pattern,factory=None,predicates=()). This is in
support of consistency with configurator.add_route.

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:

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

The INewResponse event is now not sent to listeners if the response
returned by view code (or a renderer) is not a “real” response
(e.g. if it does not have .status, .headerlist and
.app_iter attribtues).

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

The repoze.bfg.events.NewResponse class’s construct has changed:
it now must be created with (request,response) rather than
simply (response).

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

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

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

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

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

The functions in repoze.bfg.renderers named render and
render_to_response now accept an additonal keyword argument
named package.

The get_renderer API in repoze.bfg.renderers now accepts a
package argument.

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 404NotFound
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:

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

The repoze.bfg.configuration.Configurator.add_route API now
returns the route object that was added.

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

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

Pattern matches for a :segment marker in a URL dispatch route
pattern now always match at least one character. See “Backwards
Incompatibilities” below in this changelog.

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

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 Hybrid narrative chapter now contains a description of the
traverse route argument.

The Hooks narrative chapter now contains sections about
changing the request factory and adding a renderer globals factory.

The API documentation includes a new module:
repoze.bfg.renderers.

The Templates chapter was updated; all narrative that used
templating-specific APIs within examples to perform rendering (such
as the repoze.bfg.chameleon_zpt.render_template_to_response
method) was changed to use repoze.bfg.renderers.render_*
functions.

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

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:Nofactoryforrenderernamed'.pt'whenlookingupkarl.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:

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:

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

New internal exception: repoze.bfg.exceptions.URLDecodeError.
This URL is a subclass of the built-in Python exception named
UnicodeDecodeError.

When decoding a URL segment to Unicode fails, the exception raised
is now repoze.bfg.exceptions.URLDecodeError instead of
UnicodeDecodeError. This makes it possible to register an
exception view invoked specifically when repoze.bfg cannot
decode a URL.

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

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:

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:

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.

A locale negotiator no longer needs to be registered explicitly. The
default locale negotiator at
repoze.bfg.i18n.default_locale_negotiator is now used
unconditionally as... um, the default locale negotiator.

The default locale negotiator has become more complex.

First, the negotiator looks for the _LOCALE_ attribute of
the request object (possibly set by a view or an event listener).

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 InternationalizationandLocalization.

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 exception views feature replaces the need for the
set_notfound_view and set_forbidden_view methods of the
Configurator as well as the notfound and forbidden ZCML
directives. Those methods and directives will continue to work for
the foreseeable future, but they are deprecated in the
documentation.

View registrations and lookups are now done with three “requires”
arguments instead of two to accomodate orthogonality of exception
views.

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

Remove repoze.bfg.compat.pkgutil_26.py and import alias
repoze.bfg.compat.walk_packages. These were only required by
internal scanning machinery; Venusian replaced the internal scanning
machinery, so these are no longer required.

Remove magical feature of repoze.bfg.url.model_url which
prepended a fully-expanded urldispatch route URL before a the
model’s path if it was noticed that the request had matched a route.
This feature was ill-conceived, and didn’t work in all scenarios.

1.2b4 introduced a bug whereby views added via a route configuration
that named a view callable and also a view_attr became broken.
Symptom: MyViewClassisnotcallable or the __call__ of a
class was being called instead of the method named via
view_attr.

Fix a bug whereby a renderer argument to the @bfg_view
decorator that provided a package-relative template filename might
not have been resolved properly. Symptom: inappropriate Missingtemplateresource errors.

Remove view_header, view_accept, view_xhr,
view_path_info, view_request_method, view_request_param,
and view_containment predicate arguments from the
Configurator.add_route argument list. These arguments were
speculative. If you need the features exposed by these arguments,
add a view associated with a route using the route_name argument
to the add_view method instead.

Remove view_header, view_accept, view_xhr,
view_path_info, view_request_method, view_request_param,
and view_containment predicate arguments from the route ZCML
directive attribute set. These attributes were speculative. If you
need the features exposed by these attributes, add a view associated
with a route using the route_name attribute of the view ZCML
directive instead.

When “hybrid mode” (both traversal and urldispatch) is in use,
default to finding route-related views even if a non-route-related
view registration has been made with a more specific context. The
default used to be to find views with a more specific context first.
Use the new use_global_views argument to the route definition to
get back the older behavior.

When registering a view, register the view adapter with the
“requires” interfaces as (request_type,context_type) rather
than (context_type,request_type). This provides for saner
lookup, because the registration will always be made with a specific
request interface, but registration may not be made with a specific
context interface. In general, when creating multiadapters, you
want to order the requires interfaces so that the elements which
are more likely to be registered using specific interfaces are
ordered before those which are less likely.

When the Configurator is passed an instance of
zope.component.registry.Components as a registry constructor
argument, fix the instance up to have the attributes we expect of an
instance of repoze.bfg.registry.Registry when setup_registry
is called. This makes it possible to use the global Zope component
registry as a BFG application registry.

When WebOb 0.9.7.1 was used, a deprecation warning was issued for
the class attribute named charset within
repoze.bfg.request.Request. BFG now requires WebOb >= 0.9.7,
and code was added so that this deprecation warning has disappeared.

Fix a view lookup ordering bug whereby a view with a larger number
of predicates registered first (literally first, not “earlier”) for
a triad would lose during view lookup to one registered with fewer.

Make sure views with exactly N custom predicates are always called
before views with exactly N non-custom predicates given all else is
equal in the view configuration.

In bfg_routesalchemy, bfg_alchemy paster templates and the
bfgwiki2 tutorial, clean up the SQLAlchemy connection by
registering a repoze.tm.after_end callback instead of relying on
a __del__ method of a Cleanup class added to the WSGI
environment. The __del__ strategy was fragile and caused
problems in the wild. Thanks to Daniel Holth for testing.

The Configurator.add_view method now accepts an argument named
context. This is an alias for the older argument named
for_; it is preferred over for_, but for_ will continue
to be supported “forever”.

The view ZCML directive now accepts an attribute named
context. This is an alias for the older attribute named
for; it is preferred over for, but for will continue to
be supported “forever”.

The Configurator.add_route method now accepts an argument named
view_context. This is an alias for the older argument named
view_for; it is preferred over view_for, but view_for
will continue to be supported “forever”.

The route ZCML directive now accepts an attribute named
view_context. This is an alias for the older attribute named
view_for; it is preferred over view_for, but view_for
will continue to be supported “forever”.

The documentation (the result of make<html|latex|htmlhelp>
within the docs directory) in this release is now offered under
the Creative Commons Attribution-Noncommercial-No Derivative Works
3.0 United States License as described by
http://creativecommons.org/licenses/by-nc-nd/3.0/us/ . This is only
a licensing change for the documentation; the repoze.bfg
software continues to be offered under the Repoze Public License
at http://repoze.org/license.html (BSD-like).

General documentation improvements by using better Sphinx roles such
as “class”, “func”, “meth”, and so on. This means that there are
many more hyperlinks pointing to API documentation for API
definitions in all narrative, tutorial, and API documentation
elements.

Added a description of imperative configuration in various places
which only described ZCML configuration.

A syntactical refreshing of various tutorials.

Added the repoze.bfg.authentication,
repoze.bfg.authorization, and repoze.bfg.interfaces modules
to API documentation.

Add four new testing-related APIs to the
repoze.bfg.configuration.Configurator class:
testing_securitypolicy, testing_models,
testing_add_subscriber, and testing_add_template. These
were added in order to provide more direct access to the
functionality of the repoze.bfg.testing APIs named
registerDummySecurityPolicy, registerModels,
registerEventListener, and registerTemplateRenderer when a
configurator is used. The testing APIs named are nominally
deprecated (although they will likely remain around “forever”, as
they are in heavy use in the wild).

Add a new API to the repoze.bfg.configuration.Configurator
class: add_settings. This API can be used to add “settings”
(information returned within via the
repoze.bfg.settings.get_settings API) after the configurator has
been initially set up. This is most useful for testing purposes.

Add a custom_predicates argument to the Configuratoradd_view method, the bfg_view decorator and the attribute
list of the ZCML view directive. If custom_predicates is
specified, it must be a sequence of predicate callables (a predicate
callable accepts two arguments: context and request and
returns True or False). The associated view callable will
only be invoked if all custom predicates return True. Use one
or more custom predicates when no existing predefined predicate is
useful. Predefined and custom predicates can be mixed freely.

Add a custom_predicates argument to the Configuratoradd_route and the attribute list of the ZCML route
directive. If custom_predicates is specified, it must be a
sequence of predicate callables (a predicate callable accepts two
arguments: context and request and returns True or
False). The associated route will match will only be invoked if
all custom predicates return True, else route matching
continues. Note that the value context will always be None
when passed to a custom route predicate. Use one or more custom
predicates when no existing predefined predicate is useful.
Predefined and custom predicates can be mixed freely.

Doc-deprecated most helper functions in the repoze.bfg.testing
module. These helper functions likely won’t be removed any time
soon, nor will they generate a warning any time soon, due to their
heavy use in the wild, but equivalent behavior exists in methods of
a Configurator.

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.

When a repoze.bfg.exceptions.NotFound or
repoze.bfg.exceptions.Forbiddenclass (as opposed to instance)
was raised as an exception within a root factory (or route root
factory), the exception would not be caught properly by the
repoze.bfg. Router and it would propagate to up the call stack,
as opposed to rendering the not found view or the forbidden view as
would have been expected.

When Chameleon page or text templates used as renderers were added
imperatively (via Configurator.add_view or some derivative),
they too-eagerly attempted to look up the reload_templates
setting via get_settings, meaning they were always registered in
non-auto-reload-mode (the default). Each now waits until its
respective template attribute is accessed to look up the value.

When a route with the same name as a previously registered route was
added, the old route was not removed from the mapper’s routelist.
Symptom: the old registered route would be used (and possibly
matched) during route lookup when it should not have had a chance to
ever be used.

When the repoze.bfg.exceptions.NotFound or
repoze.bfg.exceptions.Forbidden error is raised from within a
custom root factory or the factory of a route, the appropriate
response is now sent to the requesting user agent (the result of the
notfound view or the forbidden view, respectively). When these
errors are raised from within a root factory, the context passed
to the notfound or forbidden view will be None. Also, the
request will not be decorated with view_name, subpath,
context, etc. as would normally be the case if traversal had
been allowed to take place.

Added a “Special Exceptions” section to the “Views” narrative
documentation chapter explaining the effect of raising
repoze.bfg.exceptions.NotFound and
repoze.bfg.exceptions.Forbidden from within view code.

repoze.bfg.testing.DummyModel now accepts a new constructor
keyword argument: __provides__. If this constructor argument is
provided, it should be an interface or a tuple of interfaces. The
resulting model will then provide these interfaces (they will be
attached to the constructed model via
zope.interface.alsoProvides).

Operation on GAE was broken, presumably because the
repoze.bfg.configuration module began to attempt to import the
repoze.bfg.chameleon_zpt and repoze.bfg.chameleon_text
modules, and these cannot be used on non-CPython platforms. It now
tolerates startup time import failures for these modules, and only
raise an import error when a template from one of these packages is
actually used.

When two views were registered with differering for interfaces
or classes, and the for of first view registered was a
superclass of the second, the repoze.bfg view machinery would
incorrectly associate the two views with the same “multiview”.
Multiviews are meant to be collections of views that have exactly
the same for/request/viewname values, without taking inheritance
into account. Symptom: wrong view callable found even when you had
correctly specified a for_ interface/class during view
configuration for one or both view configurations.

The long description of this package (as shown on PyPI) was not
valid reStructuredText, and so was not renderable.

Trying to use an HTTP method name string such as GET as a
request_type predicate argument caused a startup time failure
when it was encountered in imperative configuration or in a
decorator (symptom: TypeError:Requiredspecificationmustbeaspecification). This now works again, although request_method
is now the preferred predicate argument for associating a view
configuration with an HTTP request method.

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.

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.

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.bfgpaster 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 documentation now uses the “request-only” view calling
convention in most examples (as opposed to the context,request
convention). This is a documentation-only change; the context,request convention is also supported and documented, and will be
“forever”.

repoze.bfg.configuration API documentation has been added.

A narrative documentation chapter entitled “Creating Your First
repoze.bfg Application” has been added. This chapter details
usage of the new repoze.bfg.configuration.Configurator class,
and demonstrates a simplified “imperative-mode” configuration; doing
repoze.bfg application configuration imperatively was previously
much more difficult.

The “ZCML Hooks” chapter has been renamed to “Hooks”; it documents
how to override hooks now via imperative configuration and ZCML.

The explanation about how to supply an alternate “response factory”
has been removed from the “Hooks” chapter. This feature may be
removed in a later release (it still works now, it’s just not
documented).

Add a section entitled “Test Set Up and Tear Down” to the
unittesting chapter.

The ACL authorization policy debugging output when
debug_authorization console debugging output was turned on
wasn’t as clear as it could have been when a view execution was
denied due to an authorization failure resulting from the set of
principals passed never having matched any ACE in any ACL in the
lineage. Now in this case, we report <defaultdeny> as the ACE
value and either the root ACL or <NoACLfoundonanyobjectinmodellineage> if no ACL was found.

When two views were registered with the same accept argument,
but were otherwise registered with the same arguments, if a request
entered the application which had an Accept header that accepted
either of the media types defined by the set of views registered
with predicates that otherwise matched, a more or less “random” one
view would “win”. Now, we try harder to use the view callable
associated with the view configuration that has the most specific
accept argument. Thanks to Alberto Valverde for an initial
patch.

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

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 callget_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_typeand 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 <includepackage="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.

Remove ez_setup.py and its import from all paster templates,
samples, and tutorials for distribute compatibility. The
documentation already explains how to install virtualenv (which will
include some setuptools package), so these files, imports and
usages were superfluous.

The options kw arg to the repoze.bfg.router.make_app
function is deprecated. In its place is the keyword argument
settings. The options keyword continues to work, and a
deprecation warning is not emitted when it is detected. However,
the paster templates, code samples, and documentation now make
reference to settings rather than options. This
change/deprecation was mainly made for purposes of clarity and
symmetry with the get_settings() API and dicussions of
“settings” in various places in the docs: we want to use the same
name to refer to the same thing everywhere.

repoze.bfg.testing.registerRoutesMapper testing facility added.
This testing function registers a routes “mapper” object in the
registry, for tests which require its presence. This function is
documented in the repoze.bfg.testing API documentation.

Compound statements that used an assignment entered into in an
interactive IPython session invoked via pasterbfgshell no
longer fail to mutate the shell namespace correctly. For example,
this set of statements used to fail:

Prevent PyPI installation failure due to easy_install trying way
too hard to guess the best version of Paste. When easy_install
pulls from PyPI it reads links off various pages to determine “more
up to date” versions. It incorrectly picks up a link for an ancient
version of a package named “Paste-Deploy-0.1” (note the dash) when
trying to find the “Paste” distribution and somehow believes it’s
the latest version of “Paste”. It also somehow “helpfully” decides
to check out a version of this package from SVN. We pin the Paste
dependency version to a version greater than 1.7 to work around
this easy_install bug.

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:

The routes root factory called route factories and the default route
factory with an environ rather than a request. One of the symptoms
of this bug: applications generated using the bfg_zodb paster
template in 1.1a9 did not work properly.

Header values returned by the authtktauthenticationpolicyremember and forget methods would be of type unicode.
This violated the WSGI spec, causing a TypeError to be raised
when these headers were used under mod_wsgi.

If a BFG app that had a route matching the root URL was mounted
under a path in modwsgi, ala WSGIScriptAlias/myapp/Users/chrism/projects/modwsgi/env/bfg.wsgi, the home route (a
route with the path of '/' or '') would not match when the
path /myapp was visited (only when the path /myapp/ was
visited). This is now fixed: if the urldispatch root factory notes
that the PATH_INFO is empty, it converts it to a single slash before
trying to do matching.

An incorrect ZCML conflict would be encountered when the
request_param predicate attribute was used on the ZCML view
directive if any two otherwise same-predicated views had the
combination of a predicate value with an = sign and one without
(e.g. a vs. a=123).

In previous versions of BFG, the “root factory” (the get_root
callable passed to make_app or a function pointed to by the
factory attribute of a route) was called with a “bare” WSGI
environment. In this version, and going forward, it will be called
with a request object. The request object passed to the factory
implements dictionary-like methods in such a way that existing root
factory code which expects to be passed an environ will continue to
work.

The __call__ of a plugin “traverser” implementation (registered
as an adapter for ITraverser or ITraverserFactory) will now
receive a request as the single argument to its __call__
method. In previous versions it was passed a WSGI environ
object. The request object passed to the factory implements
dictionary-like methods in such a way that existing traverser code
which expects to be passed an environ will continue to work.

The ZCML route directive’s attributes xhr,
request_method, path_info, request_param, header and
accept are now route predicates rather than view predicates.
If one or more of these predicates is specified in the route
configuration, all of the predicates must return true for the route
to match a request. If one or more of the route predicates
associated with a route returns False when checked during a
request, the route match fails, and the next match in the routelist
is tried. This differs from the previous behavior, where no route
predicates existed and all predicates were considered view
predicates, because in that scenario, the next route was not tried.

The request implements dictionary-like methods that mutate and query
the WSGI environ. This is only for the purpose of backwards
compatibility with root factories which expect an environ rather
than a request.

The repoze.bfg.request.create_route_request_factory function,
which returned a request factory was removed in favor of a
repoze.bfg.request.route_request_interface function, which
returns an interface.

The repoze.bfg.request.Request class, which is a subclass of
webob.Request now defines its own __setattr__,
__getattr__ and __delattr__ methods, which override the
default WebOb behavior. The default WebOb behavior stores
attributes of the request in self.environ['webob.adhoc_attrs'],
and retrieves them from that dictionary during a __getattr__.
This behavior was undesirable for speed and “expectation” reasons.
Now attributes of the request are stored in request.__dict__
(as you otherwise might expect from an object that did not override
these methods).

The router no longer calls repoze.bfg.traversal._traverse and
does its work “inline” (speed).

Reverse the order in which the router calls the request factory and
the root factory. The request factory is now called first; the
resulting request is passed to the root factory.

The repoze.bfg.request.request_factory function has been
removed. Its functionality is no longer required.

The “routes root factory” that wraps the default root factory when
there are routes mentioned in the configuration now attaches an
interface to the request via zope.interface.directlyProvides.
This replaces logic in the (now-gone)
repoze.bfg.request.request_factory function.

The route and view ZCML directives now register an interface
as a named utility (retrieved from
repoze.bfg.request.route_request_interface) rather than a
request factory (the previous return value of the now-missing
repoze.bfg.request.create_route_request_factory.

Explicitly revert the feature introduced in 1.1a8: where the name
root is available as an attribute of the request before a
NewRequest event is emitted. This makes some potential future
features impossible, or at least awkward (such as grouping traversal
and view lookup into a single adapter lookup).

The containment, attr and renderer attributes of the
route ZCML directive were removed.

pasterbfgshell now supports IPython if it’s available for
import. Thanks to Daniel Holth for the initial patch.

Add repoze.bfg.testing.registerSettings API, which is documented
in the “repoze.bfg.testing” API chapter. This allows for
registration of “settings” values obtained via
repoze.bfg.settings.get_settings() for use in unit tests.

The name root is available as an attribute of the request
slightly earlier now (before a NewRequest event is emitted).
root is the result of the application “root factory”.

Added max_age parameter to authtktauthenticationpolicy ZCML
directive. If this value is set, it must be an integer representing
the number of seconds which the auth tkt cookie will survive.
Mainly, its existence allows the auth_tkt cookie to survive across
browser sessions.

The reissue_time argument to the authtktauthenticationpolicy
ZCML directive now actually works. When it is set to an integer
value, an authticket set-cookie header is appended to the response
whenever a request requires authentication and ‘now’ minus the
authticket’s timestamp is greater than reissue_time seconds.

Change how bfg_view decorator works when used as a class method
decorator. In 1.1a7, the``scan``directive actually tried to grope
every class in scanned package at startup time, calling dir
against each found class, and subsequently invoking getattr
against each thing found by dir to see if it was a method. This
led to some strange symptoms (e.g. AttributeError:objecthasnoattribute__provides__), and was generally just a bad idea. Now,
instead of groping classes for methods at startup time, we just
cause the bfg_view decorator itself to populate the method’s
class’ __dict__ when it is used as a method decorator. This
also requires a nasty _getframe thing but it’s slightly less nasty
than the startup time groping behavior. This is essentially a
reversion back to 1.1a6 “grokking” behavior plus some special magic
for using the bfg_view decorator as method decorator inside the
bfg_view class itself.

The router now checks for a global_response_headers attribute of
the request object before returning a response. If this value
exists, it is presumed to be a sequence of two-tuples, representing
a set of headers to append to the ‘normal’ response headers. This
feature is internal, rather than exposed externally, because it’s
unclear whether it will stay around in the long term. It was added
to support the reissue_time feature of the authtkt
authentication policy.

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:

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:

fromwebobimportResponsefromrepoze.bfg.viewimportbfg_viewclassMyView(object):def__init__(self,context,request):self.context=contextself.request=request@bfg_view(name='hello')defamethod(self):returnResponse('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.

Add xhr, accept, and header view configuration
predicates to ZCML view declaration, ZCML route declaration, and
bfg_view decorator. See the Views narrative documentation
chapter for more information about these predicates.

Add setUp and tearDown functions to the
repoze.bfg.testing module. Using setUp in a test setup and
tearDown in a test teardown is now the recommended way to do
component registry setup and teardown. Previously, it was
recommended that a single function named
repoze.bfg.testing.cleanUp be called in both the test setup and
tear down. repoze.bfg.testing.cleanUp still exists (and will
exist “forever” due to its widespread use); it is now just an alias
for repoze.bfg.testing.setUp and is nominally deprecated.

The BFG component registry is now available in view and event
subscriber code as an attribute of the request
ie. request.registry. This fact is currently undocumented
except for this note, because BFG developers never need to interact
with the registry directly anywhere else.

The BFG component registry now inherits from dict, meaning that
it can optionally be used as a simple dictionary. Component
registrations performed against it via e.g. registerUtility,
registerAdapter, and similar API methods are kept in a
completely separate namespace than its dict members, so using the
its component API methods won’t effect the keys and values in the
dictionary namespace. Likewise, though the component registry
“happens to be” a dictionary, use of mutating dictionary methods
such as __setitem__ will have no influence on any component
registrations made against it. In other words, the registry object
you obtain via e.g. repoze.bfg.threadlocal.get_current_registry
or request.registry happens to be both a component registry and
a dictionary, but using its component-registry API won’t impact data
added to it via its dictionary API and vice versa. This is a
forward compatibility move based on the goals of “marco”.

Expose and document repoze.bfg.testing.zcml_configure API. This
function populates a component registry from a ZCML file for testing
purposes. It is documented in the “Unit and Integration Testing”
chapter.

Importing getSiteManager and get_registry from
repoze.bfg.registry is no longer supported. These imports were
deprecated in repoze.bfg 1.0. Import of getSiteManager should
be done as fromzope.componentimportgetSiteManager. Import of
get_registry should be done as fromrepoze.bfg.threadlocalimportget_current_registry. This was done to prevent a circular
import dependency.

Code bases which alternately invoke both
zope.testing.cleanup.cleanUp and repoze.bfg.testing.cleanUp
(treating them equivalently, using them interchangeably) in the
setUp/tearDown of unit tests will begin to experience test failures
due to lack of test isolation. The “right” mechanism is
repoze.bfg.testing.cleanUp (or the combination of
repoze.bfg.testing.setUp and
repoze.bfg.testing.tearDown). but a good number of legacy
codebases will use zope.testing.cleanup.cleanUp instead. We
support zope.testing.cleanup.cleanUp but not in combination with
repoze.bfg.testing.cleanUp in the same codebase. You should use
one or the other test cleanup function in a single codebase, but not
both.

Created new repoze.bfg.configuration module which assumes
responsibilities previously held by the repoze.bfg.registry and
repoze.bfg.router modules (avoid a circular import dependency).

The result of the zope.component.getSiteManager function in unit
tests set up with repoze.bfg.testing.cleanUp or
repoze.bfg.testing.setUp will be an instance of
repoze.bfg.registry.Registry instead of the global
zope.component.globalregistry.base registry. This also means
that the threadlocal ZCA API functions such as getAdapter and
getUtility as well as internal BFG machinery (such as
model_url and route_url) will consult this registry within
unit tests. This is a forward compatibility move based on the goals
of “marco”.

Removed repoze.bfg.testing.addCleanUp function and associated
module-scope globals. This was never an API.

Add a new repoze.bfg.testing API: registerRoute, for
registering routes to satisfy calls to
e.g. repoze.bfg.url.route_url in unit tests.

The notfound and forbidden ZCML directives now accept the
following addtional attributes: attr, renderer, and
wrapper. These have the same meaning as they do in the context
of a ZCML view directive.

For behavior like Django’s APPEND_SLASH=True, use the
repoze.bfg.view.append_slash_notfound_view view as the Not Found
view in your application. When this view is the Not Found view
(indicating that no view was found), and any routes have been
defined in the configuration of your application, if the value of
PATH_INFO does not already end in a slash, and if the value of
PATH_INFOplus a slash matches any route’s path, do an HTTP
redirect to the slash-appended PATH_INFO. Note that this will
losePOST data information (turning it into a GET), so you
shouldn’t rely on this to redirect POST requests.

The import of repoze.bfg.view.NotFound is deprecated in favor of
repoze.bfg.exceptions.NotFound. The old location still
functions, but emits a deprecation warning.

The import of repoze.bfg.security.Unauthorized is deprecated in
favor of repoze.bfg.exceptions.Forbidden. The old location
still functions but emits a deprecation warning. The rename from
Unauthorized to Forbidden brings parity to the name of
the exception and the system view it invokes when raised.

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.

On 64-bit Linux systems, views that were members of a multiview
(orderings of views with predicates) were not evaluated in the
proper order. Symptom: in a configuration that had two views with
the same name but one with a request_method=POST predicate and
one without, the one without the predicate would be called
unconditionally (even if the request was a POST request). Thanks
much to Sebastien Douche for providing the buildbots that pointed
this out.

Add a repoze.bfg.url.static_url API which is capable of
generating URLs to static resources defined by the <static> ZCML
directive. See the “Views” narrative chapter’s section titled
“Generating Static Resource URLs” for more information.

Add a string renderer. This renderer converts a non-Response
return value of any view callble into a string. It is documented in
the “Views” narrative chapter.

Give the route ZCML directive the view_attr and
view_renderer parameters (bring up to speed with 1.1a3
features). These can also be spelled as attr and renderer.

An object implementing the IRenderer interface (and
ITemplateRenderer`,whichisasubclassof``IRenderer) must now
accept an extra system argument in its __call__ method
implementation. Values computed by the system (as opposed to by the
view) are passed by the system in the system parameter, which
will always be a dictionary. Keys in the dictionary include:
view (the view object that returned the value),
renderer_name (the template name or simple name of the
renderer), context (the context object passed to the view), and
request (the request object passed to the view). Previously
only ITemplateRenderers received system arguments as elements inside
the main value dictionary.

A renderer attribute has been added to view configurations,
replacing the previous (1.1a2) version’s template attribute. A
“renderer” is an object which accepts the return value of a view and
converts it to a string. This includes, but is not limited to,
templating systems.

A new interface named IRenderer was added. The existing
interface, ITemplateRenderer now derives from this new
interface. This interface is internal.

A new interface named IRendererFactory was added. An existing
interface named ITemplateRendererFactory now derives from this
interface. This interface is internal.

The view attribute of the view ZCML directive is no longer
required if the ZCML directive also has a renderer attribute.
This is useful when the renderer is a template renderer and no names
need be passed to the template at render time.

A new zcml directive renderer has been added. It is documented
in the “Views” narrative chapter of the documentation.

A ZCML view directive (and the associated bfg_view
decorator) can now accept a “wrapper” value. If a “wrapper” value
is supplied, it is the value of a separate view’s name attribute.
When a view with a wrapper attribute is rendered, the “inner”
view is first rendered normally. Its body is then attached to the
request as “wrapped_body”, and then a wrapper view name is looked up
and rendered (using repoze.bfg.render_view_to_response), passed
the request and the context. The wrapper view is assumed to do
something sensible with request.wrapped_body, usually inserting
its structure into some other rendered template. This feature makes
it possible to specify (potentially nested) “owrap” relationships
between views using only ZCML or decorators (as opposed always using
ZPT METAL and analogues to wrap view renderings in outer wrappers).

The repoze.bfg.testing.registerDummyRenderer API has been
deprecated in favor of
repoze.bfg.testing.registerTemplateRenderer. A deprecation
warning is not issued at import time for the former name; it will
exist “forever”; its existence has been removed from the
documentation, however.

The repoze.bfg.templating.renderer_from_cache function has been
moved to repoze.bfg.renderer.template_renderer_factory. This
was never an API, but code in the wild was spotted that used it. A
deprecation warning is issued at import time for the former.

The ITemplateRenderer interface has been changed. Previously
its __call__ method accepted **kw. It now accepts a single
positional parameter named kw (REVISED: it accepts two
positional parameters as of 1.1a4: value and system). This
is mostly an internal change, but it was exposed in APIs in one
place: if you’ve used the
repoze.bfg.testing.registerDummyRenderer API in your tests with
a custom “renderer” argument with your own renderer implementation,
you will need to change that renderer implementation to accept
kw instead of **kw in its __call__ method (REVISED: make
it accept value and system positional arguments as of 1.1a4).

The ITemplateRendererFactory interface has been changed.
Previously its __call__ method accepted an auto_reload
keyword parameter. Now its __call__ method accepts no keyword
parameters. Renderers are now themselves responsible for
determining details of auto-reload. This is purely an internal
change. This interface was never external.

The template_renderer ZCML directive introduced in 1.1a2 has
been removed. It has been replaced by the renderer directive.

The previous release (1.1a2) added a view configuration attribute
named template. In this release, the attribute has been renamed
to renderer. This signifies that the attribute is more generic:
it can now be not just a template name but any renderer name (ala
json).

In the previous release (1.1a2), the Chameleon text template
renderer was used if the system didn’t associate the template
view configuration value with a filename with a “known” extension.
In this release, you must use a renderer attribute which is a
path that ends with a .txt extension
(e.g. templates/foo.txt) to use the Chameleon text renderer.

A ZCML view directive (and the associated bfg_view
decorator) can now accept an “attr” value. If an “attr” value is
supplied, it is considered a method named of the view object to be
called when the response is required. This is typically only good
for views that are classes or instances (not so useful for
functions, as functions typically have no methods other than
__call__).

A ZCML view directive (and the associated bfg_view
decorator) can now accept a “template” value. If a “template” value
is supplied, and the view callable returns a dictionary, the
associated template is rendered with the dictionary as keyword
arguments. See the section named “Views That Have a template”
in the “Views” narrative documentation chapter for more information.

Bugfix: the discriminator for the ZCML “route” directive was
incorrect. It was possible to register two routes that collided
without the system spitting out a ConfigurationConflictError at
startup time.

Feature addition: view predicates. These are exposed as the
request_method, request_param, and containment
attributes of a ZCML view declaration, or the respective
arguments to a @bfg_view decorator. View predicates can be used
to register a view for a more precise set of environment parameters
than was previously possible. For example, you can register two
views with the same name with different request_param
attributes. If the request.params dict contains ‘foo’
(request_param=”foo”), one view might be called; if it contains
‘bar’ (request_param=”bar”), another view might be called.
request_param can also name a key/value pair ala foo=123.
This will match only when the foo key is in the request.params
dict and it has the value ‘123’. This particular example makes it
possible to write separate view functions for different form
submissions. The other predicates, containment and
request_method work similarly. containment is a view
predicate that will match only when the context’s graph lineage has
an object possessing a particular class or interface, for example.
request_method is a view predicate that will match when the HTTP
REQUEST_METHOD equals some string (eg. ‘POST’).

The @bfg_view decorator now accepts three additional arguments:
request_method, request_param, and containment.
request_method is used when you’d like the view to match only a
request with a particular HTTP REQUEST_METHOD; a string naming
the REQUEST_METHOD can also be supplied as request_type for
backwards compatibility. request_param is used when you’d like
a view to match only a request that contains a particular
request.params key (with or without a value). containment
is used when you’d like to match a request that has a context that
has some class or interface in its graph lineage. These are
collectively known as “view predicates”.

The route ZCML directive now honors view_request_method,
view_request_param and view_containment attributes, which
pass along these values to the associated view if any is provided.
Additionally, the request_type attribute can now be spelled as
view_request_type, and permission can be spelled as
view_permission. Any attribute which starts with view_ can
now be spelled without the view_ prefix, so view_for can be
spelled as for now, etc. Both forms are documented in the
urldispatch narraitve documentation chapter.

The request_param ZCML view directive attribute (and its
bfg_view decorator cousin) can now specify both a key and a
value. For example, request_param="foo=123" means that the foo
key must have a value of 123 for the view to “match”.

Allow repoze.bfg.traversal.find_interface API to use a class
object as the argument to compare against the model passed in.
This means you can now do find_interface(model,SomeClass) and
the first object which is found in the lineage which has
SomeClass as its class (or the first object found which has
SomeClass as any of its superclasses) will be returned.

Added static ZCML directive which registers a route for a view
that serves up files in a directory. See the “Views” narrative
documentation chapter’s “Serving Static Resources Using a ZCML
Directive” section for more information.

The repoze.bfg.view.static class now accepts a string as its
first argument (“root_dir”) that represents a package-relative name
e.g. somepackage:foo/bar/static. This is now the preferred
mechanism for spelling package-relative static paths using this
class. A package_name keyword argument has been left around for
backwards compatibility. If it is supplied, it will be honored.

The API repoze.bfg.testing.registerView now takes a
permission argument. Use this instead of using
repoze.bfg.testing.registerViewPermission.

The ordering of route declarations vs. the ordering of view
declarations that use a “route_name” in ZCML no longer matters.
Previously it had been impossible to use a route_name from a route
that had not yet been defined in ZCML (order-wise) within a “view”
declaration.

The repoze.bfg router now catches both
repoze.bfg.security.Unauthorized and
repoze.bfg.view.NotFound exceptions while rendering a view.
When the router catches an Unauthorized, it returns the
registered forbidden view. When the router catches a NotFound,
it returns the registered notfound view.

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:

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.

Added support for has_resource, resource_isdir, and
resource_listdir to the resource “OverrideProvider”; this fixes
a bug with a symptom that a file could not be overridden in a
resource directory unless a file with the same name existed in the
original directory being overridden.

Fixed documentation bug showing invalid test for values from the
matchdict: they are stored as attributes of the Article, rather
than subitems.

Fixed documentation bug showing wrong environment key for the matchdict
produced by the matching route.

Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having
to do with a recursion error in the mimetypes module when trying to
serve static files from Paste’s FileApp:
http://bugs.python.org/issue5853. Symptom: File
“/usr/lib/python2.6/mimetypes.py”, line 244, in guess_type return
guess_type(url, strict) RuntimeError: maximum recursion depth
exceeded. Thanks to Armin Ronacher for identifying the symptom and
pointing out a fix.

Fix configure_zcml filespec check on Windows. Previously if an
absolute filesystem path including a drive letter was passed as
filename (or as configure_zcml in the options dict) to
repoze.bfg.router.make_app, it would be treated as a
package:resource_name specification.

Allow a Paste config file (configure_zcml) value or an
environment variable (BFG_CONFIGURE_ZCML) to name a ZCML file
(optionally package-relative) that will be used to bootstrap the
application. Previously, the integrator could not influence which
ZCML file was used to do the boostrapping (only the original
application developer could do so).

Make it possible to pass strings in the form
“package_name:relative/path” to APIs like render_template,
render_template_to_response, and get_template. Sometimes
the package in which a caller lives is a direct namespace package,
so the module which is returned is semi-useless for navigating from.
In this way, the caller can control the horizontal and vertical of
where things get looked up from.

Deprecate the authentication_policy and authorization_policy
arguments to repoze.bfg.router.make_app. Instead, developers
should use the various authentication policy ZCML directives
(repozewho1authenticationpolicy,
remoteuserauthenticationpolicy and
authtktauthenticationpolicy) and the aclauthorizationpolicy`
authorization policy directive as described in the changes to the
“Security” narrative documenation chapter and the wiki tutorials.

Bug fix: when a repoze.bfg.resource.PackageOverrides class was
instantiated, and the package it was overriding already had a
__loader__ attribute, it would fail at startup time, even if the
__loader__ attribute was another PackageOverrides instance. We
now replace any __loader__ that is also a PackageOverrides
instance. Symptom: ConfigurationExecutionError:<type'exceptions.TypeError'>:Package<module'karl.views'from'/Users/chrism/projects/osi/bfgenv/src/karl/karl/views/__init__.pyc'>alreadyhasa__loader__(probablyamoduleinazippedegg).

Add a reload_resources configuration file setting (aka the
BFG_RELOAD_RESOURCES environment variable). When this is set to
true, the server never needs to be restarted when moving files
between directory resource overrides (esp. for templates currently).

The static helper view class now uses a PackageURLParser in
order to allow for the overriding of static resources (CSS / logo
files, etc) using the resource ZCML directive. The
PackageURLParser class was added to a (new) static module in
BFG; it is a subclass of the StaticURLParser class in
paste.urlparser.

The repoze.bfg.templating.renderer_from_cache function now
checks for the reload_resources setting; if it’s true, it does
not register a template renderer (it won’t use the registry as a
template renderer cache).

Use caller_package function instead of caller_module
function within templating to avoid needing to name the caller
module in resource overrides (actually match docs).

Make it possible to override templates stored directly in a module
with templates in a subdirectory of the same module, stored directly
within another module, or stored in a subdirectory of another module
(actually match docs).

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:

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:

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:

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_resourcesget_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.

Cause :segment matches in route paths to put a Unicode-decoded
and URL-dequoted value in the matchdict for the value matched.
Previously a non-decoded non-URL-dequoted string was placed in the
matchdict as the value.

Cause *remainder matches in route paths to put a tuple in the
matchdict dictionary in order to be able to present Unicode-decoded
and URL-dequoted values for the traversal path. Previously a
non-decoded non-URL-dequoted string was placed in the matchdict as
the value.

Add optional max_age keyword value to the remember method of
repoze.bfg.authentication.AuthTktAuthenticationPolicy; if this
value is passed to remember, the generated cookie will have a
corresponding Max-Age value.

repoze.bfg no longer relies on the Routes package to interpret
URL paths. All known existing path patterns will continue to
work with the reimplemented logic, which lives in
repoze.bfg.urldispatch. <route> ZCML directives which use
certain attributes (uncommon ones) may not work (see “Backwards
Incompatibilities” below).

model_url when passed a request that was generated as a result
of a route match would fail in a call to route.generate.

BFG-on-GAE didn’t work due to a corner case bug in the fallback
Python implementation of threading.local (symptom:
“Initialization arguments are not supported”). Thanks to Michael
Bernstein for the bug report.

Added the repoze.bfg.url.route_url API. This API allows you to
generate URLs based on <route> declarations. See the URL
Dispatch narrative chapter and the “repoze.bfg.url” module API
documentation for more information.

As a result of disusing Routes, using the Routes url_for API
inside a BFG application (as was suggested by previous iterations of
tutorials) will no longer work. Use the
repoze.bfg.url.route_url method instead.

The following attributes on the <route> ZCML directive no longer
work: encoding, static, filter, condition_method,
condition_subdomain, condition_function, explicit, or
subdomains. These were all Routes features.

The <route> ZCML directive no longer supports the
<requirement> subdirective. This was a Routes feature.

The callback argument of the repoze.bfg.authentication
authentication policies named RepozeWho1AuthenticationPolicy,
RemoteUserAuthenticationPolicy, and
AuthTktAuthenticationPolicy now must accept two positional
arguments: the orginal argument accepted by each (userid or
identity) plus a second argument, which will be the current request.
Apologies, this is required to service finding groups when there is
no “global” database connection.

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.:

defaview(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.:

defAView(object):def__call__(self,request):passview=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).

Utility registrations against
repoze.bfg.interfaces.INotFoundView and
repoze.bfg.interfaces.IForbiddenView are now deprecated. Use
the notfound and forbidden ZCML directives instead (see the
“Hooks” chapter for more information). Such registrations will
continue to work, but the notfound and forbidden directives do
“extra work” to ensure that the callable named by the directive can
be called by the router even if it’s a class or
request-argument-only view.

Moved the repoze.bfg.push module, which implemented the pushpage
decorator, into a separate distribution, repoze.bfg.pushpage.
Applications which used this decorator should continue to work after
adding that distribution to their installation requirements.

Changing the default request factory via an IRequestFactory utility
registration (as used to be documented in the “Hooks” chapter’s
“Changing the request factory” section) is no longer supported. The
dance to manufacture a request is complicated as a result of
unifying traversal and url dispatch, making it highly unlikely for
anyone to be able to override it properly. For those who just want
to decorate or modify a request, use a NewRequestEvent subscriber
(see the Events chapter in the documentation).

The repoze.bfg.IRequestFactory interface was removed. See the
bullet above for why.

Routes “context factories” (spelled as the factory argument to a
route statement in ZCML) must now expect the WSGI environ as a
single argument rather than a set of keyword arguments. They can
obtain the match dictionary by asking for
environ[‘bfg.routes.matchdict’]. This is the same set of keywords
that used to be passed to urldispatch “context factories” in BFG 0.9
and below.

Using the @zope.component.adapter decorator on a bfg view
function no longer works. Use the @repoze.bfg.view.bfg_view
decorator instead to mark a function (or a class) as a view.

The name under which the matching route object is found in the
environ was changed from bfg.route to bfg.routes.route.

Finding the root is now done before manufacturing a request object
(and sending a new request event) within the router (it used to be
performed afterwards).

Adding *path_info to a route no longer changes the PATH_INFO for
a request that matches using URL dispatch. This feature was only
there to service the repoze.bfg.wsgi.wsgiapp2 decorator and it
did it wrong; use *subpath instead now.

The values of subpath, traversed, and virtual_root_path
attached to the request object are always now tuples instead of
lists (performance).

The bfg_alchemy Paster template named “repoze.tm” in its
pipeline rather than “repoze.tm2”, causing the startup to fail.

Move BBB logic for registering an
IAuthenticationPolicy/IForbiddenView/INotFoundView based on older
concepts from the router module’s make_app function into the
repoze.bfg.zcml.zcml_configure callable, to service
compatibility with scripts that use “zope.configuration.xmlconfig”
(replace with repoze.bfg.zml.zcml_configure as necessary to get
BBB logic)

Add API named repoze.bfg.settings.get_settings which retrieves a
derivation of values passed as the options value of
repoze.bfg.router.make_app. This API should be preferred
instead of using getUtility(ISettings). I added a new
repoze.bfg.settings API document as well.

The request_type argument of ZCML view declarations and
bfg_view decorators can now be one of the strings GET,
POST, PUT, DELETE, or HEAD instead of a reference to
the respective interface type imported from
repoze.bfg.interfaces.

The route ZCML directive now accepts request_type as an
alias for its condition_method argument for symmetry with the
view directive.

The bfg_routesalchemy paster template now provides a unit test
and actually uses the database during a view rendering.

It is now possible to register a custom
repoze.bfg.interfaces.INotFoundView for a given application.
This feature replaces the
repoze.bfg.interfaces.INotFoundAppFactory feature previously
described in the Hooks chapter. The INotFoundView will be called
when the framework detects that a view lookup done as a result of a
request fails; it should accept a context object and a request
object; it should return an IResponse object (a webob response,
basically). See the Hooks narrative chapter of the BFG docs for
more info.

The error presented when a view invoked by the router returns a
non-response object now includes the view’s name for troubleshooting
purposes.

Remove “context” argument from effective_principals and
authenticated_userid function APIs in repoze.bfg.security,
effectively a doing reversion to 0.8 and before behavior. Both
functions now again accept only the request parameter.

Add an AuthTktAuthenticationPolicy. This policy retrieves
credentials from an auth_tkt cookie managed by the application
itself (instead of relying on an upstream data source for
authentication data). See the Security API chapter of the
documentation for more info.

Allow RemoteUserAuthenticationPolicy and
RepozeWho1AuthenticationPolicy to accept various constructor
arguments. See the Security API chapter of the documentation for
more info.

Add a get_app API functions to the paster module. This
obtains a WSGI application from a config file given a config file
name and a section name. See the repoze.bfg.paster API docs for
more information.

Add a new module named scripting. It contains a get_root
API function, which, provided a Router instance, returns a traversal
root object and a “closer”. See the repoze.bfg.scripting API
docs for more info.

Added deprecations for imports of ACLSecurityPolicy,
InheritingACLSecurityPolicy, RemoteUserACLSecurityPolicy,
RemoteUserInheritingACLSecurityPolicy, WhoACLSecurityPolicy,
and WhoInheritingACLSecurityPolicy from the
repoze.bfg.security module; for the meantime (for backwards
compatibility purposes) these live in the repoze.bfg.secpols
module. Note however, that the entire concept of a “security
policy” is deprecated in BFG in favor of separate authentication and
authorization policies, so any use of a security policy will
generate additional deprecation warnings even if you do start using
repoze.bfg.secpols. repoze.bfg.secpols will disappear in a
future release of repoze.bfg.

Remove repoze.bfg.template module. All imports from this
package have been deprecated since 0.3.8. Instead, import
get_template, render_template, and
render_template_to_response from the
repoze.bfg.chameleon_zpt module.

Remove backwards compatibility import alias for
repoze.bfg.traversal.split_path (deprecated since 0.6.5). This
must now be imported as repoze.bfg.traversal.traversal_path).

Remove backwards compatibility import alias for
repoze.bfg.urldispatch.RoutesContext (deprecated since 0.6.5).
This must now be imported as
repoze.bfg.urldispatch.DefaultRoutesContext.

Removed backwards compatibility import aliases for
repoze.bfg.router.get_options and repoze.bfg.router.Settings
(deprecated since 0.6.2). These both must now be imported from
repoze.bfg.settings.

Removed backwards compatibility import alias for
repoze.bfg.interfaces.IRootPolicy (deprecated since 0.6.2). It
must be imported as repoze.bfg.interfaces.IRootFactory now.

Removed backwards compatibility import alias for
repoze.bfg.interfaces.ITemplate (deprecated since 0.4.4). It
must be imported as repoze.bfg.interfaces.ITemplateRenderer now.

Removed backwards compatibility import alias for
repoze.bfg.interfaces.ITemplateFactory (deprecated since 0.4.4).
It must be imported as
repoze.bfg.interfaces.ITemplateRendererFactory now.

Removed backwards compatibility import alias for
repoze.bfg.chameleon_zpt.ZPTTemplateFactory (deprecated since
0.4.4). This must be imported as repoze.bfg.ZPTTemplateRenderer
now.

The name repoze.bfg.registry.registry_manager was never an API,
but scripts in the wild were using it to set up an environment for
use under a debug shell. A backwards compatibility shim has been
added for this purpose, but the feature is deprecated.

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 notNone, then
authorization_policy is ignored (the ability to do authorization
depends on authentication).

If the authentication_policy argument is notNone, and the
authorization_policy argument isNone, 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.

Custom NotFound and Forbidden (nee’ Unauthorized) WSGI applications
(registered as a utility for INotFoundAppFactory and
IUnauthorizedAppFactory) could rely on an environment key named
message describing the circumstance of the response. This key
has been renamed to repoze.bfg.message (as per the WSGI spec,
which requires environment extensions to contain dots).

The repoze.bfg.interfaces.IUnauthorizedAppFactory interface has
been deprecated in favor of using the new
repoze.bfg.interfaces.IForbiddenResponseFactory mechanism.

The view_execution_permitted API should now be imported from the
repoze.bfg.security module instead of the repoze.bfg.view
module.

The authenticated_userid and effective_principals APIs in
repoze.bfg.security used to only take a single argument
(request). They now accept two arguments (context and
request). Calling them with a single argument is still
supported but issues a deprecation warning. (NOTE: this change was
reverted in 0.9a7; meaning the 0.9 versions of these functions
again accept request only, just like 0.8 and before).

Use of “old-style” security policies (those base on ISecurityPolicy)
is now deprecated. See the “Security” chapter of the docs for info
about activating an authorization policy and an authentication poicy.

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:

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.

Added a traverse function to the repoze.bfg.traversal
module. This function may be used to retrieve certain values
computed during path resolution. See the Traversal API chapter of
the documentation for more information about this function.

Internal: ITraverser callables should now return a dictionary
rather than a tuple. Up until 0.7.0, all ITraversers were assumed
to return a 3-tuple. In 0.7.1, ITraversers were assumed to return a
6-tuple. As (by evidence) it’s likely we’ll need to add further
information to the return value of an ITraverser callable, 0.8
assumes that an ITraverser return a dictionary with certain elements
in it. See the repoze.bfg.interfaces.ITraverser interface for
the list of keys that should be present in the dictionary.
ITraversers which return tuples will still work, although a
deprecation warning will be issued.

If your code used the ITraverser interface directly (not via an API
function such as find_model) via an adapter lookup, you’ll need
to change your code to expect a dictionary rather than a 3- or
6-tuple if your code ever gets return values from the default
ModelGraphTraverser or RoutesModelTraverser adapters.

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:

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

Two new security policies were added:
RemoteUserInheritingACLSecurityPolicy and
WhoInheritingACLSecurityPolicy. These are security policies which
take into account all ACLs defined in the lineage of a context
rather than stopping at the first ACL found in a lineage. See the
“Security” chapter of the API documentation for more information.

The API and narrative documentation dealing with security was
changed to introduce the new “inheriting” security policy variants.

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:

Applications which rely on zope.testing.cleanup.cleanUp in unit
tests can still use that function indefinitely. However, for
maximum forward compatibility, they should import cleanUp from
repoze.bfg.testing instead of from zope.testing.cleanup.
The BFG paster templates and docs have been changed to use this
function instead of the zope.testing.cleanup version.

We no longer include the configure.zcml of the chameleon.zpt
package within the configure.zcml of the “repoze.bfg.includes”
package. This has been a no-op for some time now.

The repoze.bfg.chameleon_zpt package no longer imports from
chameleon.zpt at module scope, deferring the import until later
within a method call. The chameleon.zpt package can’t be
imported on platforms like GAE.

Since version 0.6.1, a deprecation warning has been emitted when the
name model_url is imported from the repoze.bfg.traversal
module. This import alias (and the deprecation warning) has been
removed. Any import of the model_url function will now need to
be done from repoze.bfg.url; any import of the name
model_url from repoze.bfg.traversal will now fail. This was
done to remove a dependency on zope.deferredimport.

Since version 0.6.5, a deprecation warning has been emitted when the
name RoutesModelTraverser is imported from the
repoze.bfg.traversal module. This import alias (and the
deprecation warning) has been removed. Any import of the
RoutesModelTraverser class will now need to be done from
repoze.bfg.urldispatch; any import of the name
RoutesModelTraverser from repoze.bfg.traversal will now
fail. This was done to remove a dependency on zope.deferredimport.

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.

Removed the repoze.bfg.chameleon_genshi module, and thus support
for Genshi-style chameleon templates. Genshi-style Chameleon
templates depend upon lxml, which is implemented in C (as
opposed to pure Python) and the repoze.bfg core is “C-free” as
of this release. You may get Genshi-style Chameleon support back by
installing the repoze.bfg.chameleon_genshi package availalable
from http://svn.repoze.org/repoze.bfg.chameleon_genshi (also
available in the index at http://dist.repoze.org/bfg/0.8/simple).
All existing code that depended on the chameleon_genshi module
prior to this release of repoze.bfg should work without change
after this addon is installed.

Removed the repoze.bfg.xslt module and thus support for XSL
templates. The repoze.bfg.xslt module depended upon lxml,
which is implemented in C, and the repoze.bfg core is “C-free”
as of this release. You bay get XSL templating back by installing
the repoze.bfg.xslt package available from
http://svn.repoze.org/repoze.bfg.xslt/ (also available in the index
at http://dist.repoze.org/bfg/0.8/simple). All existing code that
depended upon the xslt module prior to this release of
repoze.bfg should work without modification after this addon is
installed.

Removed the repoze.bfg.interfaces.INodeTemplateRenderer
interface and the an old b/w compat aliases from that interface to
repoze.bfg.interfaces.INodeTemplate. This interface must now be
imported from the repoze.bfg.xslt.interfaces package after
installation of the repoze.bfg.xslt addon package described
above as repoze.bfg.interfaces.INodeTemplateRenderer. This
interface was never part of any public API.

Other backwards incompatibilities:

The render_template function in repoze.bfg.chameleon_zpt
returns Unicode instead of a string. Likewise, the individual
values returned by the iterable created by the
render_template_to_iterable function are also each Unicode.
This is actually a backwards incompatibility inherited from our new
use of the combination of chameleon.core 1.0b32 (the
non-lxml-depending version) and chameleon.zpt 1.0b16+ ; the
chameleon.zpt PageTemplateFile implementation used to return a
string, but now returns Unicode.

The canonical package index location for repoze.bfg has changed.
The “old” index (http://dist.repoze.org/lemonade/dev/simple) has
been superseded by a new index location
(http://dist.repoze.org/bfg/current/simple). The installation
documentation has been updated as well as the setup.cfg file in
this package. The “lemonade” index still exists, but it is not
guaranteed to have the latest BFG software in it, nor will it be
maintained in the future.

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.

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:

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.

Fix a bug in repoze.bfg.wsgi.HTTPException: the content length
was returned as an int rather than as a string.

Add explicit dependencies on zope.deferredimport,
zope.deprecation, and zope.proxy for forward compatibility
reasons (zope.component will stop relying on
zope.deferredimport soon and although we use it directly, it’s
only a transitive dependency, and ‘’zope.deprecation`` and
zope.proxy are used directly even though they’re only transitive
dependencies as well).

Using model_url or model_path against a broken model graph
(one with models that had a non-root model with a __name__ of
None) caused an inscrutable error to be thrown: ( if not
_must_quote[cachekey].search(s):TypeError:expectedstringorbuffer). Now URLs and paths generated against graphs that have
None names in intermediate nodes will replace the None with the
empty string, and, as a result, the error won’t be raised. Of
course the URL or path will still be bogus.

Make it possible to have testing.DummyTemplateRenderer return
some nondefault string representation.

Added a new anchor keyword argument to model_url. If
anchor is present, its string representation will be used
as a named anchor in the generated URL (e.g. if anchor is
passed as foo and the model URL is
http://example.com/model/url, the generated URL will be
http://example.com/model/url#foo).

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:

lru cache was unstable under concurrency (big surprise!) when it
tried to redelete a key in the cache that had already been deleted.
Symptom: line 64 in put:del data[oldkey]:KeyError: ‘/some/path’.
Now we just ignore the key error if we can’t delete the key (it has
already been deleted).

Empty location names in model paths when generating a URL using
repoze.bfg.model_url based on a model obtained via traversal are
no longer ignored in the generated URL. This means that if a
non-root model object has a __name__ of '', the URL will
reflect it (e.g. model_url will generate http://foo/bar//baz
if an object with the __name__ of '' is a child of bar and
the parent of baz). URLs generated with empty path segments are,
however, still irresolveable by the model graph traverser on request
ingress (the traverser strips empty path segment names).

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

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.

Each argument contained in elements passed to
repoze.bfg.traversal.model_path will now have any /
characters contained within quoted to %2F in the returned
string. Previously, / characters in elements were left unquoted
(a bug).

A repoze.bfg.traversal.model_path_tuple API was added. This API
is an alternative to model_path (which returns a string);
model_path_tuple returns a model path as a tuple (much like
Zope’s getPhysicalPath).

A repoze.bfg.traversal.quote_path_segment API was added. This
API will quote an individual path segment (string or unicode
object). See the repoze.bfg.traversal API documentation for
more information.

The repoze.bfg.traversal.find_model API now accepts “path
tuples” (see the above note regarding model_path_tuple) as well
as string path representations (from
repoze.bfg.traversal.model_path) as a path argument.

Add ` renderer` argument (defaulting to None) to
repoze.bfg.testing.registerDummyRenderer. This makes it
possible, for instance, to register a custom renderer that raises an
exception in a unit test.

The repoze.bfg.url.model_url API now works against contexts
derived from Routes URL dispatch (Routes.util.url_for is called
under the hood).

“Virtual root” support for traversal-based applications has been
added. Virtual root support is useful when you’d like to host some
model in a repoze.bfg model graph as an application under a
URL pathname that does not include the model path itself. For more
information, see the (new) “Virtual Hosting” chapter in the
documentation.

A repoze.bfg.traversal.virtual_root API has been added. When
called, it returns the virtual root object (or the physical root
object if no virtual root has been specified).

There is an indirection in repoze.bfg.url.model_url now that
consults a utility to generate the base model url (without extra
elements or a query string). Eventually this will service virtual
hosting; for now it’s undocumented and should not be hooked.

You can now override the NotFound and Unauthorized responses that
repoze.bfg generates when a view cannot be found or cannot be
invoked due to lack of permission. See the “ZCML Hooks” chapter in
the docs for more information.

Added Routes ZCML directive attribute explanations in documentation.

Added a traversal_path API to the traversal module; see the
“traversal” API chapter in the docs. This was a function previously
known as split_path that was not an API but people were using it
anyway. Unlike split_path, it now returns a tuple instead of a
list (as its values are cached).

The repoze.bfg.view.render_view_to_response API will no longer
raise a ValueError if an object returned by a view function it calls
does not possess certain attributes (headerlist, app_iter,
status). This API used to attempt to perform a check using the
is_response function in repoze.bfg.view, and raised a
ValueError if the is_response check failed. The
responsibility is now the caller’s to ensure that the return value
from a view function is a “real” response.

WSGI environ dicts passed to repoze.bfg ‘s Router must now
contain a REQUEST_METHOD key/value; if they do not, a KeyError will
be raised (speed).

It is no longer permissible to pass a “nested” list of principals to
repoze.bfg.ACLAuthorizer.permits (e.g. ['fred',['larry','bob']]). The principals list must be fully expanded. This
feature was never documented, and was never an API, so it’s not a
backwards incompatibility.

It is no longer permissible for a security ACE to contain a “nested”
list of permissions (e.g. (Allow,Everyone,['read',['view',['write','manage']]])`)`.Thelistmustinsteadbefullyexpanded(e.g.``(Allow,Everyone,['read','view','write','manage])). This
feature was never documented, and was never an API, so it’s not a
backwards incompatibility.

The repoze.bfg.urldispatch.RoutesRootFactory now injects the
wsgiorg.routing_args environment variable into the environ when
a route matches. This is a tuple of ((), routing_args) where
routing_args is the value that comes back from the routes mapper
match (the “match dict”).

The repoze.bfg.traversal.RoutesModelTraverser class now wants to
obtain the view_name and subpath from the
wsgiorgs.routing_args environment variable. It falls back to
obtaining these from the context for backwards compatibility.

The unicode_path_segments configuration variable and the
BFG_UNICODE_PATH_SEGMENTS configuration variable have been
removed. Path segments are now always passed to model
__getitem__ methods as unicode. “True” has been the default for
this setting since 0.5.4, but changing this configuration setting to
false allowed you to go back to passing raw path element strings to
model __getitem__ methods. Removal of this knob services a
speed goal (we get about +80 req/s by removing the check), and it’s
clearer just to always expect unicode path segments in model
__getitem__ methods.

repoze.bfg.traversal.split_path now also handles decoding
path segments to unicode (for speed, because its results are
cached).

repoze.bfg.traversal.step was made a method of the

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.

Readd root_policy attribute on Router object (as a property
which returns the IRootFactory utility). It was inadvertently
removed in 0.6.2. Code in the wild depended upon its presence
(esp. scripts and “debug” helpers).

URL-dispatch has been overhauled: it is no longer necessary to
manually create a RoutesMapper in your application’s entry point
callable in order to use URL-dispatch (aka Routes). A new route directive has been
added to the available list of ZCML directives. Each route
directive inserted into your application’s configure.zcml
establishes a Routes mapper connection. If any route
declarations are made via ZCML within a particular application, the
get_root callable passed in to repoze.bfg.router.make_app
will automatically be wrapped in the equivalent of a RoutesMapper.
Additionally, the new route directive allows the specification
of a context_interfaces attribute for a route, this will be used
to tag the manufactured routes context with specific interfaces when
a route specifying a context_interfaces attribute is matched.

A new interface repoze.bfg.interfaces.IContextNotFound was
added. This interface is attached to a “dummy” context generated
when Routes cannot find a match and there is no “fallback” get_root
callable that uses traversal.

The bfg_starter and bfg_zodb “paster create” templates now
contain images and CSS which are displayed when the default page is
displayed after initial project generation.

Allow the repoze.bfg.view.static helper to be passed a relative
root_path name; it will be considered relative to the file in
which it was called.

The functionality of repoze.bfg.convention has been merged into
the core. Applications which make use of repoze.bfg.convention
will continue to work indefinitely, but it is recommended that apps
stop depending upon it. To do so, substitute imports of
repoze.bfg.convention.bfg_view with imports of
repoze.bfg.view.bfg_view, and change the stanza in ZCML from
<conventionpackage="."> to <scanpackage=".">. As a result
of the merge, bfg has grown a new dependency: martian.

View functions which use the pushpage decorator are now pickleable
(meaning their use won’t prevent a configure.zcml.cache file
from being written to disk).

Instead of invariably using webob.Request as the “request
factory” (e.g. in the Router class) and webob.Response and
the “response factory” (e.g. in render_template_to_response),
allow both to be overridden via a ZCML utility hook. See the “Using
ZCML Hooks” chapter of the documentation for more information.

The class repoze.bfg.urldispatch.RoutesContext has been renamed
to repoze.bfg.urldispatch.DefaultRoutesContext. The class
should be imported by the new name as necessary (although in reality
it probably shouldn’t be imported from anywhere except internally
within BFG, as it’s not part of the API).

The repoze.bfg.wsgi.wsgiapp decorator now uses
webob.Request.get_response to do its work rather than relying on
homegrown WSGI code.

The repoze.bfg.view.static helper now uses
webob.Request.get_response to do its work rather than relying on
homegrown WSGI code.

The repoze.bfg.urldispatch.RoutesModelTraverser class has been
moved to repoze.bfg.traversal.RoutesModelTraverser.

The repoze.bfg.registry.makeRegistry function was renamed to
repoze.bfg.registry.populateRegistry and now accepts a
registry argument (which should be an instance of
zope.component.registry.Components).

Tests can be run with coverage output if you’ve got nose
installed in the interpreter which you use to run tests. Using an
interpreter with nose installed, do pythonsetup.pynosetests within a checkout of the repoze.bfg package to see
test coverage output.

Added a post argument to the repoze.bfg.testing:DummyRequest
constructor.

Added __len__ and __nonzero__ to repoze.bfg.testing:DummyModel.

The repoze.bfg.registry.get_options callable (now renamed to
repoze.bfg.setings.get_options) used to return only
framework-specific keys and values in the dictionary it returned.
It now returns all the keys and values in the dictionary it is
passed plus any framework-specific settings culled from the
environment. As a side effect, all PasteDeploy application-specific
config file settings are made available as attributes of the
ISettings utility from within BFG.

Add a method named assert_ to the DummyTemplateRenderer. This
method accepts keyword arguments. Each key/value pair in the
keyword arguments causes an assertion to be made that the renderer
received this key with a value equal to the asserted value.

Projects generated by the paster templates now use the
DummyTemplateRenderer.assert_ method in their view tests.

Make the (internal) thread local registry manager maintain a stack
of registries in order to make it possible to call one BFG
application from inside another.

An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is
attached to each request object on ingress. The HTTP-verb-related
interfaces are defined in repoze.bfg.interfaces and are
IGETRequest, IPOSTRequest, IPUTRequest,
IDELETERequest and IHEADRequest. These interfaces can be
specified as the request_type attribute of a bfg view
declaration. A view naming a specific HTTP-verb-matching interface
will be found only if the view is defined with a request_type that
matches the HTTP verb in the incoming request. The more general
IRequest interface can be used as the request_type to catch all
requests (and this is indeed the default). All requests implement
IRequest. The HTTP-verb-matching idea was pioneered by
repoze.bfg.restrequest . That
package is no longer required, but still functions fine.

Fix a bug where the Paste configuration’s unicode_path_segments
(and os.environ’s BFG_UNICODE_PATH_SEGMENTS) may have been
defaulting to false in some circumstances. It now always defaults
to true, matching the documentation and intent.

The repoze.bfg.traversal.find_model API did not work properly
when passed a path argument which was unicode and contained
high-order bytes when the unicode_path_segments or
BFG_UNICODE_PATH_SEGMENTS configuration variables were “true”.

A new module was added: repoze.bfg.settings. This contains
deployment-settings-related code.

The make_app callable within repoze.bfg.router now registers
the root_policy argument as a utility (unnamed, using the new
repoze.bfg.interfaces.IRootFactory as a provides interface)
rather than passing it as the first argument to the
repoze.bfg.router.Router class. As a result, the
repoze.bfg.router.Router router class only accepts a single
argument: registry. The repoze.bfg.router.Router class
retrieves the root policy via a utility lookup now. The
repoze.bfg.router.make_app API also now performs some important
application registrations that were previously handled inside
repoze.bfg.registry.makeRegistry.

The repoze.bfg.settings.Settings class (an instance of which is
registered as a utility providing
repoze.bfg.interfaces.ISettings when any application is started)
now automatically calls repoze.bfg.settings.get_options on the
options passed to its constructor. This means that usage of
get_options within an application’s make_app function is no
longer required (the “raw” options dict or None may be passed).

Remove old cold which attempts to recover from trying to unpickle a
z3c.pt template; Chameleon has been the templating engine for a
good long time now. Running repoze.bfg against a sandbox that has
pickled z3c.pt templates it will now just fail with an
unpickling error, but can be fixed by deleting the template cache
files.

Moved the repoze.bfg.registry.Settings class. This has been
moved to repoze.bfg.settings.Settings. A deprecation warning is
issued when it is imported from the older location.

Moved the repoze.bfg.registry.get_options function This has been
moved to repoze.bfg.settings.get_options. A deprecation warning
is issued when it is imported from the older location.

The repoze.bfg.interfaces.IRootPolicy interface was renamed
within the interfaces package. It has been renamed to
IRootFactory. A deprecation warning is issued when it is
imported from the older location.

A new module repoze.bfg.url has been added. It contains the
model_url API (moved from repoze.bfg.traversal) and an
implementation of urlencode (like Python’s
urllib.urlencode) which can handle Unicode keys and values in
parameters to the query argument.

The model_url function has been moved from
repoze.bfg.traversal into repoze.bfg.url. It can still
be imported from repoze.bfg.traversal but an import from
repoze.bfg.traversal will emit a DeprecationWarning.

A static helper class was added to the repoze.bfg.views
module. Instances of this class are willing to act as BFG views
which return static resources using files on disk. See the
repoze.bfg.view docs for more info.

The repoze.bfg.url.model_url API (nee’
repoze.bfg.traversal.model_url) now accepts and honors a
keyword argument named query. The value of this argument
will be used to compose a query string, which will be attached to
the generated URL before it is returned. See the API docs (in
the docs directory or on the web) for more information.

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. <includepackage="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.pydevelop 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.

Speed up traversal.model_url execution by using a custom url quoting
function instead of Python’s urllib.quote, by caching URL path
segment quoting and encoding results, by disusing Python’s
urlparse.urljoin in favor of a simple string concatenation, and by
using ob.__class__isunicode rather than isinstance(ob,unicode)
in one strategic place.

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:

URL-quote “extra” element names passed in as **elements to the
traversal.model_url API. If any of these names is a Unicode string,
encode it to UTF-8 before URL-quoting. This is a slight backwards
incompatibility that will impact you if you were already UTF-8 encoding
or URL-quoting the values you passed in as elements to this API.

Remove the ITestingTemplateRenderer interface. When
testing.registerDummyRenderer is used, it instead registers a dummy
implementation using ITemplateRenderer interface, which is checked
for when the built-in templating facilities do rendering. This change
also allows developers to make explcit named utility registrations in
the ZCML registry against ITemplateRenderer; these will be found
before any on-disk template is looked up.

The component registration handler for views (functions or class
instances) now observes component adaptation annotations (see
zope.component.adaptedBy) and uses them before the fallback values
for for_ and request_type. This change does not affect existing
code insomuch as the code does not rely on these defaults when an
annotation is set on the view (unlikely). This means that for a
new-style class you can do zope.component.adapts(ISomeContext,ISomeRequest) at class scope or at module scope as a decorator to a
bfg view function you can do @zope.component.adapter(ISomeContext,ISomeRequest). This differs from r.bfg.convention inasmuch as you
still need to put something in ZCML for the registrations to get done;
it’s only the defaults that will change if these declarations exist.

Strip all slashes from end and beginning of path in clean_path within
traversal machinery.

Fix ModelGraphTraverser; don’t try to change the __name__ or
__parent__ of an object that claims it implements ILocation during
traversal even if the __name__ or __parent__ of the object
traversed does not match the name used in the traversal step or the or
the traversal parent . Rationale: it was insane to do so. This bug was
only found due to a misconfiguration in an application that mistakenly
had intermediate persistent non-ILocation objects; traversal was causing
a persistent write on every request under this setup.

repoze.bfg.location.locate now unconditionally sets __name__ and
__parent__ on objects which provide ILocation (it previously only set
them conditionally if they didn’t match attributes already present on the
object via equality).

repoze.bfg.traversal.model_url now always appends a slash to all
generated URLs unless further elements are passed in as the third and
following arguments. Rationale: views often use model_url without
the third-and-following arguments in order to generate a URL for a model
in order to point at the default view of a model. The URL that points to
the default view of the root model is technically http://mysite/ as
opposed to http://mysite (browsers happen to ask for ‘/’ implicitly
in the GET request). Because URLs are never automatically generated for
anything except models by model_url, and because the root model is
not really special, we continue this pattern. The impact of this change
is minimal (at most you will have too many slashes in your URL, which BFG
deals with gracefully anyway).

Added a repoze.bfg.testing module to attempt to make it slightly
easier to write unittest-based automated tests of BFG applications.
Information about this module is in the documentation.

The default template renderer now supports testing better by looking for
ITestingTemplateRenderer using a relative pathname. This is exposed
indirectly through the API named registerTemplateRenderer in
repoze.bfg.testing.

The names repoze.bfg.interfaces.ITemplate ,
repoze.bfg.interfaces.ITemplateFactory and
repoze.bfg.interfaces.INodeTemplate have been deprecated. These
should now be imported as repoze.bfg.interfaces.ITemplateRenderer and
repoze.bfg.interfaces.ITemplateRendererFactory, and
INodeTemplateRenderer respectively.

The name repoze.bfg.chameleon_zpt.ZPTTemplateFactory is deprecated.
Use repoze.bfg.chameleon_zpt.ZPTTemplateRenderer.

The name repoze.bfg.chameleon_genshi.GenshiTemplateFactory is
deprecated. Use repoze.bfg.chameleon_genshi.GenshiTemplateRenderer.

The name repoze.bfg.xslt.XSLTemplateFactory is deprecated. Use
repoze.bfg.xslt.XSLTemplateRenderer.

Not passing the result of “get_options” as the second argument of
make_app could cause attribute errors when attempting to look up settings
against the ISettings object (internal). Fixed by giving the Settings
objects defaults for debug_authorization and debug_notfound.

Return an instance of Allowed (rather than True) from
has_permission when no security policy is in use.

Expose a single ILogger named “repoze.bfg.debug” as a utility; this
logger is registered unconditionally and is used by the authorization
debug machinery. Applications may also make use of it as necessary
rather than inventing their own logger, for convenience.

The BFG_DEBUG_AUTHORIZATION envvar and the debug_authorization
config file value now only imply debugging of view-invoked security
checks. Previously, information was printed for every call to
has_permission as well, which made output confusing. To debug
has_permission checks and other manual permission checks, use the
debugger and print statements in your own code.

Authorization debugging info is now only present in the HTTP response
body oif debug_authorization is true.

The format of authorization debug messages was improved.

A new BFG_DEBUG_NOTFOUND envvar was added and a symmetric
debug_notfound config file value was added. When either is true, and
a NotFound response is returned by the BFG router (because a view could
not be found), debugging information is printed to stderr. When this
value is set true, the body of HTTPNotFound responses will also contain
the same debugging information.

Allowed and Denied responses from the security machinery are now
specialized into two types: ACL types, and non-ACL types. The
ACL-related responses are instances of repoze.bfg.security.ACLAllowed
and repoze.bfg.security.ACLDenied. The non-ACL-related responses are
repoze.bfg.security.Allowed and repoze.bfg.security.Denied. The
allowed-type responses continue to evaluate equal to things that
themselves evaluate equal to the True boolean, while the denied-type
responses continue to evaluate equal to things that themselves evaluate
equal to the False boolean. The only difference between the two
types is the information attached to them for debugging purposes.

Added a new BFG_DEBUG_ALL envvar and a symmetric debug_all config
file value. When either is true, all other debug-related flags are set
true unconditionally (e.g. debug_notfound and
debug_authorization).

Change default paster template generator to use Paste#http server
rather than PasteScript#cherrpy server. The cherrypy server has a
security risk in it when REMOTE_USER is trusted by the downstream
application.

If the render_view_to_response function was called, if the view was
found and called, but it returned something that did not implement
IResponse, the error would pass by unflagged. This was noticed when I
created a view function that essentially returned None, but received a
NotFound error rather than a ValueError when the view was rendered. This
was fixed.

The environment variable BFG_RELOAD_TEMPLATES is now available
(serves the same purpose as reload_templates in the config file).

A new configuration file option debug_authorization was added.
This turns on printing of security authorization debug statements
to sys.stderr. The BFG_DEBUG_AUTHORIZATION environment
variable was also added; this performs the same duty.

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.

Replace z3c.pt support with support for chameleon.zpt.
Chameleon is the new name for the package that used to be named
z3c.pt. NOTE: If you update a repoze.bfg SVN checkout
that you’re using for development, you will need to run “setup.py
install” or “setup.py develop” again in order to obtain the
proper Chameleon packages. z3c.pt is no longer supported by
repoze.bfg. All API functions that used to render z3c.pt
templates will work fine with the new packages, and your
templates should render almost identically.

Importing API functions directly from repoze.bfg.template is
now deprecated. The get_template, render_template,
render_template_to_response functions should now be imported
from repoze.chameleon_zpt. The render_transform, and
render_transform_to_response functions should now be imported
from repoze.bfg.xslt. The repoze.bfg.template module
will remain around “forever” to support backwards compatibility.

Move core repoze.bfg ZCML into a repoze.bfg.includes package so we
can use repoze.bfg better as a namespace package. Adjust the code
generator to use it. We’ve left around the configure.zcml in the
repoze.bfg package directly so as not to break older apps.

When a zcml application registry cache was unpickled, and it contained a
reference to an object that no longer existed (such as a view), bfg would
not start properly.

Event notification is issued after application is created and configured
(IWSGIApplicationCreatedEvent).

New API module: repoze.bfg.view. This module contains the functions
named render_view_to_response, render_view_to_iterable,
render_view and is_response, which are documented in the API
docs. These features aid programmatic (non-server-driven) view
execution.

Make repoze.bfg a namespace package so we can allow folks to create
subpackages (e.g. repoze.bfg.otherthing) within separate eggs. This
is a backwards incompatible change which makes it impossible to import
“make_app” and “get_options” from the repoze.bfg module directly.
This change will break all existing apps generated by the paster code
generator. Instead, you need to import these functions as
repoze.bfg.router:make_app and repoze.bfg.registry:get_options,
respectively. Sorry folks, it has to be done now or never, and
definitely better now.

Read and write a pickled ZCML actions list, stored as
configure.zcml.cache next to the applications’s “normal”
configuration file. A given bfg app will usually start faster if it’s
able to read the pickle data. It fails gracefully to reading the real
ZCML file if it cannot read the pickle.

Generated application differences: make_app entry point renamed to
app in order to have a different name than the bfg function of the
same name, to prevent confusion.

Add “options” processing to bfg’s make_app to support runtime
options. A new API function named get_options was added to the
registry module. This function is typically used in an application’s
app entry point. The Paste config file section for the app can now
supply the reload_templates option, which, if true, will prevent the
need to restart the appserver in order for z3c.pt or XSLT template
changes to be detected.

Use only the module name in generated project’s “test_suite” (run all
tests found in the package).

Add a request_type attribute to the available attributes of a
bfg:view configure.zcml element. This attribute will have a value
which is a dotted Python path, pointing at an interface. If the request
object implements this interface when the view lookup is performed, the
appropriate view will be called. This is meant to allow for simple
“skinning” of sites based on request type. An event subscriber should
attach the interface to the request on ingress to support skins.

Remove “template only” views. These were just confusing and were never
documented.

Small url dispatch overhaul: the connect method of the
urldispatch.RoutesMapper object now accepts a keyword parameter named
context_factory. If this parameter is supplied, it must be a
callable which returns an instance. This instance is used as the context
for the request when a route is matched.

The registration of a RoutesModelTraverser no longer needs to be
performed by the application; it’s in the bfg ZCML now.

The concept of “view factories” was removed in favor of always calling a
view, which is a callable that returns a response directly (as opposed to
returning a view). As a result, the factory attribute in the
bfg:view ZCML statement has been renamed to view. Various interface
names were changed also.

render_template and render_transform no longer return a Response
object. Instead, these return strings. The old behavior can be obtained
by using render_template_to_response and
render_transform_to_response.

Added ‘repoze.bfg.push:pushpage’ decorator, which creates BFG views from
callables which take (context, request) and return a mapping of top-level
names.