diff options
| -rw-r--r-- | CHANGES.txt | 1256 | ||||
| -rw-r--r-- | HISTORY.txt | 1263 | ||||
| -rw-r--r-- | docs/api/testing.rst | 4 | ||||
| -rw-r--r-- | docs/authorintro.rst | 34 | ||||
| -rw-r--r-- | docs/changes.rst | 2 | ||||
| -rw-r--r-- | docs/conf.py | 39 | ||||
| -rw-r--r-- | docs/conventions.rst | 16 | ||||
| -rw-r--r-- | docs/copyright.rst | 21 | ||||
| -rw-r--r-- | docs/designdefense.rst | 518 | ||||
| -rw-r--r-- | docs/glossary.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 69 | ||||
| -rw-r--r-- | docs/latexindex.rst | 6 | ||||
| -rw-r--r-- | docs/tutorials/wiki/background.rst | 2 | ||||
| -rw-r--r-- | docs/whatsnew-1.1.rst | 802 | ||||
| -rw-r--r-- | docs/whatsnew-1.2.rst | 364 | ||||
| -rw-r--r-- | docs/whatsnew-1.3.rst | 771 | ||||
| l--------- | docs/zcml/.#include.rst | 1 | ||||
| -rw-r--r-- | pyramid/testing.py | 58 | ||||
| -rw-r--r-- | pyramid/tests/test_testing.py | 36 |
19 files changed, 1550 insertions, 3714 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 6d97062f7..242e4bfe8 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,1260 +1,12 @@ Next release ============ -Features --------- - -- The ``paster`` template named ``bfg_routesalchemy`` has been updated - to use SQLAlchemy declarative syntax. Thanks to Ergo^. - -- 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. - -Bug Fixes ---------- - -- When a renderer factory could not be found, a misleading error - message was raised if the renderer name was not a string. - -1.3a15 (2010-09-30) -=================== - -Features --------- - -- The ``repoze.bfg.traversal.traversal_path`` API now eagerly attempts - to encode a Unicode ``path`` into ASCII before attempting to split - it and decode its segments. This is for convenience, effectively to - allow a (stored-as-Unicode-in-a-database, or - retrieved-as-Unicode-from-a-request-parameter) Unicode path to be - passed to ``find_model``, which eventually internally uses the - ``traversal_path`` function under the hood. In version 1.2 and - prior, if the ``path`` was Unicode, that Unicode was split on - slashes and each resulting segment value was Unicode. An - inappropriate call to the ``decode()`` method of a resulting Unicode - path segment could cause a ``UnicodeDecodeError`` to occur even if - the Unicode representation of the path contained no 'high order' - characters (it effectively did a "double decode"). By converting - the Unicode path argument to ASCII before we attempt to decode and - split, genuine errors will occur in a more obvious place while also - allowing us to handle (for convenience) the case that it's a Unicode - representation formed entirely from ASCII-compatible characters. - -1.3a14 (2010-09-14) -=================== - -Bug Fixes ---------- - -- If an exception view was registered through the legacy - ``set_notfound_view`` or ``set_forbidden_view`` APIs, the context - sent to the view was incorrect (could be ``None`` inappropriately). - -Features --------- - -- Compatibility with WebOb 1.0. - -Requirements ------------- - -- Now requires WebOb >= 1.0. - -Backwards Incompatibilities ---------------------------- - -- Due to changes introduced WebOb 1.0, the - ``repoze.bfg.request.make_request_ascii`` event subscriber no longer - works, so it has been removed. This subscriber was meant to be used - in a deployment so that code written before BFG 0.7.0 could run - unchanged. At this point, such code will need to be rewritten to - expect Unicode from ``request.GET``, ``request.POST`` and - ``request.params`` or it will need to be changed to use - ``request.str_POST``, ``request.str_GET`` and/or - ``request.str_params`` instead of the non-``str`` versions of same, - as the non-``str`` versions of the same APIs always now perform - decoding to Unicode. - -Errata ------- - -- A prior changelog entry asserted that the ``INewResponse`` event was - not sent to listeners if the response was not "valid" (if a view or - renderer returned a response object that did not have a - status/headers/app_iter). This is not true in this release, nor was - it true in 1.3a13. - -1.3a13 (2010-09-14) -=================== - -Bug Fixes ---------- - -- The ``traverse`` route predicate could not successfully generate a - traversal path. - -Features --------- - -- In support of making it easier to configure applications which are - "secure by default", a default permission feature was added. If - supplied, the default permission is used as the permission string to - all view registrations which don't otherwise name a permission. - These APIs are in support of that: - - - A new constructor argument was added to the Configurator: - ``default_permission``. - - - A new method was added to the Configurator: - ``set_default_permission``. - - - A new ZCML directive was added: ``default_permission``. - -- Add a new request API: ``request.add_finished_callback``. Finished - callbacks are called by the router unconditionally near the very end - of request processing. See the "Using Finished Callbacks" section - of the "Hooks" narrative chapter of the documentation for more - information. - -- A ``request.matched_route`` attribute is now added to the request - when a route has matched. Its value is the "route" object that - matched (see the ``IRoute`` interface within - ``repoze.bfg.interfaces`` API documentation for the API of a route - object). - -- The ``exception`` attribute of the request is now set slightly - earlier and in a slightly different set of scenarios, for benefit of - "finished callbacks" and "response callbacks". In previous - versions, the ``exception`` attribute of the request was not set at - all if an exception view was not found. In this version, the - ``request.exception`` attribute is set immediately when an exception - is caught by the router, even if an exception view could not be - found. - -- The ``add_route`` method of a Configurator now accepts a - ``pregenerator`` argument. The pregenerator for the resulting route - is called by ``route_url`` in order to adjust the set of arguments - passed to it by the user for special purposes, such as Pylons - 'subdomain' support. It will influence the URL returned by - ``route_url``. See the ``repoze.bfg.interfaces.IRoutePregenerator`` - interface for more information. - -Backwards Incompatibilities ---------------------------- - -- The router no longer sets the value ``wsgiorg.routing_args`` into - the environ when a route matches. The value used to be something - like ``((), matchdict)``. This functionality was only ever - obliquely referred to in change logs; it was never documented as an - API. - -- The ``exception`` attribute of the request now defaults to ``None``. - In prior versions, the ``request.exception`` attribute did not exist - if an exception was not raised by user code during request - processing; it only began existence once an exception view was - found. - -Deprecations ------------- - -- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event - interface was renamed to - ``repoze.bfg.interfaces.IApplicationCreated``. Likewise, the - ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed - to ``repoze.bfg.events.ApplicationCreated``. The older aliases will - continue to work indefinitely. - -- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was - renamed to ``repoze.bfg.interfaces.IContextFound``. Likewise, the - ``repoze.bfg.events.AfterTraversal`` class was renamed to - ``repoze.bfg.events.ContextFound``. The older aliases will continue - to work indefinitely. - -- References to the WSGI environment values ``bfg.routes.matchdict`` - and ``bfg.routes.route`` were removed from documentation. These - will stick around internally for several more releases, but it is - ``request.matchdict`` and ``request.matched_route`` are now the - "official" way to obtain the matchdict and the route object which - resulted in the match. - -Documentation -------------- - -- Added documentation for the ``default_permission`` ZCML directive. - -- Added documentation for the ``default_permission`` constructor value - and the ``set_default_permission`` method in the Configurator API - documentation. - -- Added a new section to the "security" chapter named "Setting a - Default Permission". - -- Document ``renderer_globals_factory`` and ``request_factory`` - arguments to Configurator constructor. - -- Added two sections to the "Hooks" chapter of the documentation: - "Using Response Callbacks" and "Using Finished Callbacks". - -- Added documentation of the ``request.exception`` attribute to the - ``repoze.bfg.request.Request`` API documentation. - -- Added glossary entries for "response callback" and "finished - callback". - -- The "Request Processing" narrative chapter has been updated to note - finished and response callback steps. - -- New interface in interfaces API documentation: ``IRoutePregenerator``. - -- Added a "The Matched Route" section to the URL Dispatch narrative - docs chapter, detailing the ``matched_route`` attribute. - -1.3a12 (2010-09-08) -=================== - -Bug Fixes ---------- - -- Fix a bug in ``repoze.bfg.url.static_url`` URL generation: if two - resource specifications were used to create two separate static - views, but they shared a common prefix, it was possible that - ``static_url`` would generate an incorrect URL. - -- Fix another bug in ``repoze.bfg.static_url`` URL generation: too - many slashes in generated URL. - -- Prevent a race condition which could result in a ``RuntimeError`` - when rendering a Chameleon template that has not already been - rendered once. This would usually occur directly after a restart, - when more than one person or thread is trying to execute the same - view at the same time: https://bugs.launchpad.net/karl3/+bug/621364 - -Features --------- - -- The argument to ``repoze.bfg.configuration.Configurator.add_route`` - which was previously called ``path`` is now called ``pattern`` for - better explicability. For backwards compatibility purposes, passing - a keyword argument named ``path`` to ``add_route`` will still work - indefinitely. - -- The ``path`` attribute to the ZCML ``route`` directive is now named - ``pattern`` for better explicability. The older ``path`` attribute - will continue to work indefinitely. - -Documentation -------------- - -- All narrative, API, and tutorial docs which referred to a route - pattern as a ``path`` have now been updated to refer to them as a - ``pattern``. - -- The ``repoze.bfg.interfaces`` API documentation page is now rendered - via ``repoze.sphinx.autointerface``. - -- The URL Dispatch narrative chapter now refers to the ``interfaces`` - chapter to explain the API of an ``IRoute`` object. - -Paster Templates ----------------- - -- The routesalchemy template has been updated to use ``pattern`` in - its route declarations rather than ``path``. - -Dependencies ------------- - -- ``tests_require`` now includes ``repoze.sphinx.autointerface`` as a - dependency. - -Internal --------- - -- Add an API to the ``Configurator`` named ``get_routes_mapper``. - This returns an object implementing the ``IRoutesMapper`` interface. - -- The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a - ``get_route`` method which returns a single Route object or - ``None``. - -- A new interface ``repoze.bfg.interfaces.IRoute`` was added. The - ``repoze.bfg.urldispatch.Route`` object implements this interface. - -- The canonical attribute for accessing the routing pattern from a - route object is now ``pattern`` rather than ``path``. - -- Use ``hash()`` rather than ``id()`` when computing the "phash" of a - custom route/view predicate in order to allow the custom predicate - some control over which predicates are "equal". - -- Use ``response.headerlist.append`` instead of - ``response.headers.add`` in - ``repoze.bfg.request.add_global_response_headers`` in case the - response is not a WebOb response. - -- The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now - accepts a different ordering of arguments. Previously it was - ``(pattern, name, factory=None, predicates=())``. It is now - ``(name, pattern, factory=None, predicates=())``. This is in - support of consistency with ``configurator.add_route``. - -- The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an - API) now accepts a different ordering of arguments. Previously it - was ``(pattern, name, factory=None, predicates=())``. It is now - ``(name, pattern, factory=None, predicates=())``. This is in - support of consistency with ``configurator.add_route``. - -1.3a11 (2010-09-05) -=================== - -Bug Fixes ---------- - -- Process the response callbacks and the NewResponse event earlier, to - enable mutations to the response to take effect. - -1.3a10 (2010-09-05) -=================== - -Features --------- - -- A new ``repoze.bfg.request.Request.add_response_callback`` API has - been added. This method is documented in the new - ``repoze.bfg.request`` API chapter. It can be used to influence - response values before a concrete response object has been created. - -- The ``repoze.bfg.interfaces.INewResponse`` interface now includes a - ``request`` attribute; as a result, a handler for INewResponse now - has access to the request which caused the response. - -- Each of the follow methods of the Configurator now allow the - below-named arguments to be passed as "dotted name strings" - (e.g. "foo.bar.baz") rather than as actual implementation objects - that must be imported: - - setup_registry - root_factory, authentication_policy, authorization_policy, - debug_logger, locale_negotiator, request_factory, - renderer_globals_factory - - add_subscriber - subscriber, iface - - derive_view - view - - add_view - view, ``for_``, context, request_type, containment - - add_route() - view, view_for, factory, ``for_``, view_context - - scan - package - - add_renderer - factory - - set_forbidden_view - view - - set_notfound_view - view - - set_request_factory - factory - - set_renderer_globals_factory() - factory - - set_locale_negotiator - negotiator - - testing_add_subscriber - event_iface - -Bug Fixes ---------- - -- The route pattern registered internally for a a local "static view" - (either via the ``static`` ZCML directive or via the - ``add_static_view`` method of the configurator) was incorrect. It - was regsistered for e.g. ``static*traverse``, while it should have - been registered for ``static/*traverse``. Symptom: two static views - could not reliably be added to a system when they both shared the - same path prefix (e.g. ``/static`` and ``/static2``). - -Backwards Incompatibilities ---------------------------- - -- The INewResponse event is now not sent to listeners if the response - returned by view code (or a renderer) is not a "real" response - (e.g. if it does not have ``.status``, ``.headerlist`` and - ``.app_iter`` attribtues). - -Documentation -------------- - -- Add an API chapter for the ``repoze.bfg.request`` module, which - includes documentation for the ``repoze.bfg.request.Request`` class - (the "request object"). - -- Modify the "Request and Response" narrative chapter to reference the - new ``repoze.bfg.request`` API chapter. Some content was moved from - this chapter into the API documentation itself. - -- Various changes to denote that Python dotted names are now allowed - as input to Configurator methods. - -Internal --------- - -- The (internal) feature which made it possible to attach a - ``global_response_headers`` attribute to the request (which was - assumed to contain a sequence of header key/value pairs which would - later be added to the response by the router), has been removed. - The functionality of - ``repoze.bfg.request.Request.add_response_callback`` takes its - place. - -- The ``repoze.bfg.events.NewResponse`` class's construct has changed: - it now must be created with ``(request, response)`` rather than - simply ``(response)``. - -1.3a9 (2010-08-22) -================== - -Features --------- - -- The Configurator now accepts a dotted name *string* to a package as - a ``package`` constructor argument. The ``package`` argument was - previously required to be a package *object* (not a dotted name - string). - -- The ``repoze.bfg.configuration.Configurator.with_package`` method - was added. This method returns a new Configurator using the same - application registry as the configurator object it is called - upon. The new configurator is created afresh with its ``package`` - constructor argument set to the value passed to ``with_package``. - This feature will make it easier for future BFG versions to allow - dotted names as arguments in places where currently only object - references are allowed (the work to allow dotted names isntead of - object references everywhere has not yet been done, however). - -- The new ``repoze.bfg.configuration.Configurator.maybe_dotted`` - method resolves a Python dotted name string supplied as its - ``dotted`` argument to a global Python object. If the value cannot - be resolved, a ``repoze.bfg.configuration.ConfigurationError`` is - raised. If the value supplied as ``dotted`` is not a string, the - value is returned unconditionally without any resolution attempted. - -- The new - ``repoze.bfg.configuration.Configurator.absolute_resource_spec`` - method resolves a potentially relative "resource specification" - string into an absolute version. If the value supplied as - ``relative_spec`` is not a string, the value is returned - unconditionally without any resolution attempted. - Backwards Incompatibilities --------------------------- -- The functions in ``repoze.bfg.renderers`` named ``render`` and - ``render_to_response`` introduced in 1.3a6 previously took a set of - ``**values`` arguments for the values to be passed to the renderer. - This was wrong, as renderers don't need to accept only dictionaries - (they can accept any type of object). Now, the value sent to the - renderer must be supplied as a positional argument named ``value``. - The ``request`` argument is still a keyword argument, however. - -- The functions in ``repoze.bfg.renderers`` named ``render`` and - ``render_to_response`` now accept an additonal keyword argument - named ``package``. - -- The ``get_renderer`` API in ``repoze.bfg.renderers`` now accepts a - ``package`` argument. - -Documentation -------------- - -- The ZCML ``include`` directive docs were incorrect: they specified - ``filename`` rather than (the correct) ``file`` as an allowable - attribute. - -Internal --------- - -- The ``repoze.bfg.resource.resolve_resource_spec`` function can now - accept a package object as its ``pname`` argument instead of just a - package name. - -- The ``_renderer_factory_from_name`` and ``_renderer_from_name`` - methods of the Configurator were removed. These were never APIs. - -- The ``_render``, ``_render_to_response`` and ``_make_response`` - functions with ``repoze.bfg.render`` (added in 1.3a6) have been - removed. - -- A new helper class ``repoze.bfg.renderers.RendererHelper`` was - added. - -- The _map_view function of ``repoze.bfg.configuration`` now takes - only a renderer_name argument instead of both a ``renderer`` and - ``renderer``_name argument. It also takes a ``package`` argument - now. - -- Use ``imp.get_suffixes`` indirection in - ``repoze.bfg.path.package_name`` instead of hardcoded ``.py`` - ``.pyc`` and ``.pyo`` to use for comparison when attemtping to - decide if a directory is a package. - -- Make tests runnable again under Jython (although they do not all - pass currently). - -- The reify decorator now maintains the docstring of the function it - wraps. - -1.3a8 (2010-08-08) -================== - -Features --------- - -- New public interface: ``repoze.bfg.exceptions.IExceptionResponse``. - This interface is provided by all internal exception classes (such - as ``repoze.bfg.exceptions.NotFound`` and - ``repoze.bfg.exceptions.Forbidden``), instances of which are both - exception objects and can behave as WSGI response objects. This - interface is made public so that exception classes which are also - valid WSGI response factories can be configured to implement them or - exception instances which are also or response instances can be - configured to provide them. - -- New API class: ``repoze.bfg.view.AppendSlashNotFoundViewFactory``. - - There can only be one Not Found view in any ``repoze.bfg`` - application. Even if you use - ``repoze.bfg.view.append_slash_notfound_view`` as the Not Found - view, ``repoze.bfg`` still must generate a ``404 Not Found`` - response when it cannot redirect to a slash-appended URL; this not - found response will be visible to site users. - - If you don't care what this 404 response looks like, and you only - need redirections to slash-appended route URLs, you may use the - ``repoze.bfg.view.append_slash_notfound_view`` object as the Not - Found view. However, if you wish to use a *custom* notfound view - callable when a URL cannot be redirected to a slash-appended URL, - you may wish to use an instance of the - ``repoze.bfg.view.AppendSlashNotFoundViewFactory`` class as the Not - Found view, supplying the notfound view callable as the first - argument to its constructor. For instance:: - - from repoze.bfg.exceptions import NotFound - from repoze.bfg.view import AppendSlashNotFoundViewFactory - - def notfound_view(context, request): - return HTTPNotFound('It aint there, stop trying!') - - custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view) - config.add_view(custom_append_slash, context=NotFound) - - The ``notfound_view`` supplied must adhere to the two-argument view - callable calling convention of ``(context, request)`` (``context`` - will be the exception object). - -Documentation --------------- - -- Expanded the "Cleaning Up After a Request" section of the URL - Dispatch narrative chapter. - -- Expanded the "Redirecting to Slash-Appended Routes" section of the - URL Dispatch narrative chapter. - -Internal --------- - -- Previously, two default view functions were registered at - Configurator setup (one for ``repoze.bfg.exceptions.NotFound`` named - ``default_notfound_view`` and one for - ``repoze.bfg.exceptions.Forbidden`` named - ``default_forbidden_view``) to render internal exception responses. - Those default view functions have been removed, replaced with a - generic default view function which is registered at Configurator - setup for the ``repoze.bfg.interfaces.IExceptionResponse`` interface - that simply returns the exception instance; the ``NotFound`` and - ``Forbidden`` classes are now still exception factories but they are - also response factories which generate instances that implement the - new ``repoze.bfg.interfaces.IExceptionResponse`` interface. - -1.3a7 (2010-08-01) -================== - -Features --------- - -- The ``repoze.bfg.configuration.Configurator.add_route`` API now - returns the route object that was added. - -- A ``repoze.bfg.events.subscriber`` decorator was added. This - decorator decorates module-scope functions, which are then treated - as event listeners after a scan() is performed. See the Events - narrative documentation chapter and the ``repoze.bfg.events`` module - documentation for more information. - -Bug Fixes ---------- - -- When adding a view for a route which did not yet exist ("did not yet - exist" meaning, temporally, a view was added with a route name for a - route which had not yet been added via add_route), the value of the - ``custom_predicate`` argument to ``add_view`` was lost. Symptom: - wrong view matches when using URL dispatch and custom view - predicates together. - -- Pattern matches for a ``:segment`` marker in a URL dispatch route - pattern now always match at least one character. See "Backwards - Incompatibilities" below in this changelog. - -Backwards Incompatibilities ---------------------------- - -- A bug existed in the regular expression to do URL matching. As an - example, the URL matching machinery would cause the pattern - ``/{foo}`` to match the root URL ``/`` resulting in a match - dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might - match the URL ``//edit`` resulting in a match dictionary of - ``{'fud':u''}``. It was always the intent that ``:segment`` markers - in the pattern would need to match *at least one* character, and - never match the empty string. This, however, means that in certain - circumstances, a routing match which your application inadvertently - depended upon may no longer happen. - -Documentation --------------- - -- Added description of the ``repoze.bfg.events.subscriber`` decorator - to the Events narrative chapter. - -- Added ``repoze.bfg.events.subscriber`` API documentation to - ``repoze.bfg.events`` API docs. - -- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By - Default; BFG Does Not" to the "Design Defense" chapter. - -1.3a6 (2010-07-25) -================== - -Features --------- - -- New argument to ``repoze.bfg.configuration.Configurator.add_route`` - and the ``route`` ZCML directive: ``traverse``. If you would like - to cause the ``context`` to be something other than the ``root`` - object when this route matches, you can spell a traversal pattern as - the ``traverse`` argument. This traversal pattern will be used as - the traversal path: traversal will begin at the root object implied - by this route (either the global root, or the object returned by the - ``factory`` associated with this route). - - The syntax of the ``traverse`` argument is the same as it is for - ``path``. For example, if the ``path`` provided is - ``articles/:article/edit``, and the ``traverse`` argument provided - is ``/:article``, when a request comes in that causes the route to - match in such a way that the ``article`` match value is '1' (when - the request URI is ``/articles/1/edit``), the traversal path will be - generated as ``/1``. This means that the root object's - ``__getitem__`` will be called with the name ``1`` during the - traversal phase. If the ``1`` object exists, it will become the - ``context`` of the request. The Traversal narrative has more - information about traversal. - - If the traversal path contains segment marker names which are not - present in the path argument, a runtime error will occur. The - ``traverse`` pattern should not contain segment markers that do not - exist in the ``path``. - - A similar combining of routing and traversal is available when a - route is matched which contains a ``*traverse`` remainder marker in - its path. The ``traverse`` argument allows you to associate route - patterns with an arbitrary traversal path without using a a - ``*traverse`` remainder marker; instead you can use other match - information. - - Note that the ``traverse`` argument is ignored when attached to a - route that has a ``*traverse`` remainder marker in its path. - -- A new method of the ``Configurator`` exists: - ``set_request_factory``. If used, this method will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- The ``Configurator`` constructor takes an additional argument: - ``request_factory``. If used, this argument will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- The ``Configurator`` constructor takes an additional argument: - ``request_factory``. If used, this argument will set the factory - used by the ``repoze.bfg`` router to create all request objects. - -- A new method of the ``Configurator`` exists: - ``set_renderer_globals_factory``. If used, this method will set the - factory used by the ``repoze.bfg`` router to create renderer - globals. - -- A new method of the ``Configurator`` exists: ``get_settings``. If - used, this method will return the current settings object (performs - the same job as the ``repoze.bfg.settings.get_settings`` API). - -- The ``Configurator`` constructor takes an additional argument: - ``renderer_globals_factory``. If used, this argument will set the - factory used by the ``repoze.bfg`` router to create renderer - globals. - -- Add ``repoze.bfg.renderers.render``, - ``repoze.bfg.renderers.render_to_response`` and - ``repoze.bfg.renderers.get_renderer`` functions. These are - imperative APIs which will use the same rendering machinery used by - view configurations with a ``renderer=`` attribute/argument to - produce a rendering or renderer. Because these APIs provide a - central API for all rendering, they now form the preferred way to - perform imperative template rendering. Using functions named - ``render_*`` from modules such as ``repoze.bfg.chameleon_zpt`` and - ``repoze.bfg.chameleon_text`` is now discouraged (although not - deprecated). The code the backing older templating-system-specific - APIs now calls into the newer ``repoze.bfg.renderer`` code. - -- The ``repoze.bfg.configuration.Configurator.testing_add_template`` - has been renamed to ``testing_add_renderer``. A backwards - compatibility alias is present using the old name. - -Documentation -------------- - -- The ``Hybrid`` narrative chapter now contains a description of the - ``traverse`` route argument. - -- The ``Hooks`` narrative chapter now contains sections about - changing the request factory and adding a renderer globals factory. - -- The API documentation includes a new module: - ``repoze.bfg.renderers``. - -- The ``Templates`` chapter was updated; all narrative that used - templating-specific APIs within examples to perform rendering (such - as the ``repoze.bfg.chameleon_zpt.render_template_to_response`` - method) was changed to use ``repoze.bfg.renderers.render_*`` - functions. - -Bug Fixes ---------- - -- The ``header`` predicate (when used as either a view predicate or a - route predicate) had a problem when specified with a name/regex - pair. When the header did not exist in the headers dictionary, the - regex match could be fed ``None``, causing it to throw a - ``TypeError: expected string or buffer`` exception. Now, the - predicate returns False as intended. - -Deprecations ------------- - -- The ``repoze.bfg.renderers.rendered_response`` function was never an - official API, but may have been imported by extensions in the wild. - It is officially deprecated in this release. Use - ``repoze.bfg.renderers.render_to_response`` instead. - -- The following APIs are *documentation* deprecated (meaning they are - officially deprecated in documentation but do not raise a - deprecation error upon their usage, and may continue to work for an - indefinite period of time): - - In the ``repoze.bfg.chameleon_zpt`` module: ``get_renderer``, - ``get_template``, ``render_template``, - ``render_template_to_response``. The suggested alternatives are - documented within the docstrings of those methods (which are still - present in the documentation). - - In the ``repoze.bfg.chameleon_text`` module: ``get_renderer``, - ``get_template``, ``render_template``, - ``render_template_to_response``. The suggested alternatives are - documented within the docstrings of those methods (which are still - present in the documentation). - - In general, to perform template-related functions, one should now - use the various methods in the ``repoze.bfg.renderers`` module. - -Backwards Incompatibilities ---------------------------- - -- A new internal exception class (*not* an API) named - ``repoze.bfg.exceptions.PredicateMismatch`` now exists. This - exception is currently raised when no constituent view of a - multiview can be called (due to no predicate match). Previously, in - this situation, a ``repoze.bfg.exceptions.NotFound`` was raised. We - provide backwards compatibility for code that expected a - ``NotFound`` to be raised when no predicates match by causing - ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from - ``NotFound``. This will cause any exception view registered for - ``NotFound`` to be called when a predicate mismatch occurs, as was - the previous behavior. - - There is however, one perverse case that will expose a backwards - incompatibility. If 1) you had a view that was registered as a - member of a multiview 2) this view explicitly raised a ``NotFound`` - exception *in order to* proceed to the next predicate check in the - multiview, that code will now behave differently: rather than - skipping to the next view match, a NotFound will be raised to the - top-level exception handling machinery instead. For code to be - depending upon the behavior of a view raising ``NotFound`` to - proceed to the next predicate match, would be tragic, but not - impossible, given that ``NotFound`` is a public interface. - ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and - cannot be depended upon by application code, so you should not - change your view code to raise ``PredicateMismatch``. Instead, move - the logic which raised the ``NotFound`` exception in the view out - into a custom view predicate. - -- If, when you run your application's unit test suite under BFG 1.3, a - ``KeyError`` naming a template or a ``ValueError`` indicating that a - 'renderer factory' is not registered may is raised - (e.g. ``ValueError: No factory for renderer named '.pt' when looking - up karl.views:templates/snippets.pt``), you may need to perform some - extra setup in your test code. - - The best solution is to use the - ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or, - alternately the deprecated - ``repoze.bfg.testing.registerTemplateRenderer`` or - ``registerDummyRenderer``) API within the code comprising each - individual unit test suite to register a "dummy" renderer for each - of the templates and renderers used by code under test. For - example:: - - config = Configurator() - config.testing_add_renderer('karl.views:templates/snippets.pt') - - This will register a basic dummy renderer for this particular - missing template. The ``testing_add_renderer`` API actually - *returns* the renderer, but if you don't care about how the render - is used, you don't care about having a reference to it either. - - A more rough way to solve the issue exists. It causes the "real" - template implementations to be used while the system is under test, - which is suboptimal, because tests will run slower, and unit tests - won't actually *be* unit tests, but it is easier. Always ensure you - call the ``setup_registry()`` method of the Configurator . Eg:: - - reg = MyRegistry() - config = Configurator(registry=reg) - config.setup_registry() - - Calling ``setup_registry`` only has an effect if you're *passing in* - a ``registry`` argument to the Configurator constructor. - ``setup_registry`` is called by the course of normal operations - anyway if you do not pass in a ``registry``. - - If your test suite isn't using a Configurator yet, and is still - using the older ``repoze.bfg.testing`` APIs name ``setUp`` or - ``cleanUp``, these will register the renderers on your behalf. - - A variant on the symptom for this theme exists: you may already be - dutifully registering a dummy template or renderer for a template - used by the code you're testing using ``testing_register_renderer`` - or ``registerTemplateRenderer``, but (perhaps unbeknownst to you) - the code under test expects to be able to use a "real" template - renderer implementation to retrieve or render *another* template - that you forgot was being rendered as a side effect of calling the - code you're testing. This happened to work because it found the - *real* template while the system was under test previously, and now - it cannot. The solution is the same. - - It may also help reduce confusion to use a *resource specification* - to specify the template path in the test suite and code rather than - a relative path in either. A resource specification is unambiguous, - while a relative path needs to be relative to "here", where "here" - isn't always well-defined ("here" in a test suite may or may not be - the same as "here" in the code under test). - -1.3a5 (2010-07-14) -================== - -Features --------- - -- New internal exception: ``repoze.bfg.exceptions.URLDecodeError``. - This URL is a subclass of the built-in Python exception named - ``UnicodeDecodeError``. - -- When decoding a URL segment to Unicode fails, the exception raised - is now ``repoze.bfg.exceptions.URLDecodeError`` instead of - ``UnicodeDecodeError``. This makes it possible to register an - exception view invoked specifically when ``repoze.bfg`` cannot - decode a URL. - -Bug Fixes ---------- - -- Fix regression in - ``repoze.bfg.configuration.Configurator.add_static_view``. Before - 1.3a4, view names that contained a slash were supported as route - prefixes. 1.3a4 broke this by trying to treat them as full URLs. - -Documentation -------------- - -- The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to - the exceptions chapter of the API documentation. - -Backwards Incompatibilities ----------------------------- - -- in previous releases, when a URL could not be decoded from UTF-8 - during traversal, a ``TypeError`` was raised. Now the error which - is raised is a ``repoze.bfg.exceptions.URLDecodeError``. - -1.3a4 (2010-07-03) -================== - -Features --------- - -- Undocumented hook: make ``get_app`` and ``get_root`` of the - ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where - endware may interfere with the default versions. - -- In earlier versions, a custom route predicate associated with a url - dispatch route (each of the predicate functions fed to the - ``custom_predicates`` argument of - ``repoze.bfg.configuration.Configurator.add_route``) has always - required a 2-positional argument signature, e.g. ``(context, - request)``. Before this release, the ``context`` argument was - always ``None``. - - As of this release, the first argument passed to a predicate is now - a dictionary conventionally named ``info`` consisting of ``route``, - and ``match``. ``match`` is a dictionary: it represents the - arguments matched in the URL by the route. ``route`` is an object - representing the route which was matched. - - This is useful when predicates need access to the route match. For - example:: - - def any_of(segment_name, *args): - def predicate(info, request): - if info['match'][segment_name] in args: - return True - return predicate - - num_one_two_or_three = any_of('num, 'one', 'two', 'three') - - add_route('num', '/:num', custom_predicates=(num_one_two_or_three,)) - - The ``route`` object is an object that has two useful attributes: - ``name`` and ``path``. The ``name`` attribute is the route name. - The ``path`` attribute is the route pattern. An example of using - the route in a set of route predicates:: - - def twenty_ten(info, request): - if info['route'].name in ('ymd', 'ym', 'y'): - return info['match']['year'] == '2010' - - add_route('y', '/:year', custom_predicates=(twenty_ten,)) - add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,)) - add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,)) - -- The ``repoze.bfg.url.route_url`` API has changed. If a keyword - ``_app_url`` is present in the arguments passed to ``route_url``, - this value will be used as the protocol/hostname/port/leading path - prefix of the generated URL. For example, using an ``_app_url`` of - ``http://example.com:8080/foo`` would cause the URL - ``http://example.com:8080/foo/fleeb/flub`` to be returned from this - function if the expansion of the route pattern associated with the - ``route_name`` expanded to ``/fleeb/flub``. - -- It is now possible to use a URL as the ``name`` argument fed to - ``repoze.bfg.configuration.Configurator.add_static_view``. When the - name argument is a URL, the ``repoze.bfg.url.static_url`` API will - generate join this URL (as a prefix) to a path including the static - file name. This makes it more possible to put static media on a - separate webserver for production, while keeping static media - package-internal and served by the development webserver during - development. - -Documentation -------------- - -- The authorization chapter of the ZODB Wiki Tutorial - (docs/tutorials/bfgwiki) was changed to demonstrate authorization - via a group rather than via a direct username (thanks to Alex - Marandon). - -- The authorization chapter of the SQLAlchemy Wiki Tutorial - (docs/tutorials/bfgwiki2) was changed to demonstrate authorization - via a group rather than via a direct username. - -- Redirect requests for tutorial sources to - http://docs.repoze.org/bfgwiki-1.3 and - http://docs.repoze.org/bfgwiki2-1.3/ respectively. - -- A section named ``Custom Route Predicates`` was added to the URL - Dispatch narrative chapter. - -- The Static Resources chapter has been updated to mention using - ``static_url`` to generate URLs to external webservers. - -Internal --------- - -- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new - abstraction revolving around the (still-internal) - ``repoze.bfg.static.StaticURLInfo`` helper class. - -1.3a3 (2010-05-01) -================== - -Paster Templates ----------------- - -- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer - register a ``handle_teardown`` event listener which calls - ``DBSession.remove``. This was found by Chris Withers to be - unnecessary. - -Documentation -------------- - -- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation - was changed to remove the ``handle_teardown`` event listener which - calls ``DBSession.remove``. - -- Any mention of the ``handle_teardown`` event listener as used by the - paster templates was removed from the URL Dispatch narrative chapter. - -- A section entitled Detecting Available Languages was added to the - i18n narrative docs chapter. - -1.3a2 (2010-04-28) -================== - -Features --------- - -- A locale negotiator no longer needs to be registered explicitly. The - default locale negotiator at - ``repoze.bfg.i18n.default_locale_negotiator`` is now used - unconditionally as... um, the default locale negotiator. - -- The default locale negotiator has become more complex. - - * First, the negotiator looks for the ``_LOCALE_`` attribute of - the request object (possibly set by a view or an event listener). - - * Then it looks for the ``request.params['_LOCALE_']`` value. - - * Then it looks for the ``request.cookies['_LOCALE_']`` value. - -Backwards Incompatibilities ---------------------------- - -- The default locale negotiator now looks for the parameter named - ``_LOCALE_`` rather than a parameter named ``locale`` in - ``request.params``. - -Behavior Changes ----------------- - -- A locale negotiator may now return ``None``, signifying that the - default locale should be used. - -Documentation -------------- - -- Documentation concerning locale negotiation in the - Internationalizationa and Localization chapter was updated. - -- Expanded portion of i18n narrative chapter docs which discuss - working with gettext files. - -1.3a1 (2010-04-26) -================== - -Features --------- - -- Added "exception views". When you use an exception (anything that - inherits from the Python ``Exception`` builtin) as view context - argument, e.g.:: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound) - def notfound_view(request): - return HTTPNotFound() - - For the above example, when the ``repoze.bfg.exceptions.NotFound`` - exception is raised by any view or any root factory, the - ``notfound_view`` view callable will be invoked and its response - returned. - - Other normal view predicates can also be used in combination with an - exception view registration:: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound, route_name='home') - def notfound_view(request): - return HTTPNotFound() - - The above exception view names the ``route_name`` of ``home``, - meaning that it will only be called when the route matched has a - name of ``home``. You can therefore have more than one exception - view for any given exception in the system: the "most specific" one - will be called when the set of request circumstances which match the - view registration. The only predicate that cannot be not be used - successfully is ``name``. The name used to look up an exception - view is always the empty string. - - Existing (pre-1.3) normal views registered against objects - inheriting from ``Exception`` will continue to work. Exception - views used for user-defined exceptions and system exceptions used as - contexts will also work. - - The feature can be used with any view registration mechanism - (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view`` - styles). - - This feature was kindly contributed by Andrey Popp. - -- Use "Venusian" (`http://docs.repoze.org/venusian - <http://docs.repoze.org/venusian>`_) to perform ``bfg_view`` - decorator scanning rather than relying on a BFG-internal decorator - scanner. (Truth be told, Venusian is really just a generalization - of the BFG-internal decorator scanner). - -- Internationalization and localization features as documented in the - narrative documentation chapter entitled ``Internationalization and - Localization``. - -- A new deployment setting named ``default_locale_name`` was added. - If this string is present as a Paster ``.ini`` file option, it will - be considered the default locale name. The default locale name is - used during locale-related operations such as language translation. - -- It is now possible to turn on Chameleon template "debugging mode" - for all Chameleon BFG templates by setting a BFG-related Paster - ``.ini`` file setting named ``debug_templates``. The exceptions - raised by Chameleon templates when a rendering fails are sometimes - less than helpful. ``debug_templates`` allows you to configure your - application development environment so that exceptions generated by - Chameleon during template compilation and execution will contain - more helpful debugging information. This mode is on by default in - all new projects. - -- Add a new method of the Configurator named ``derive_view`` which can - be used to generate a BFG view callable from a user-supplied - function, instance, or class. This useful for external framework and - plugin authors wishing to wrap callables supplied by their users - which follow the same calling conventions and response conventions - as objects that can be supplied directly to BFG as a view callable. - See the ``derive_view`` method in the - ``repoze.bfg.configuration.Configurator`` docs. - -ZCML ----- - -- Add a ``translationdir`` ZCML directive to support localization. - -- Add a ``localenegotiator`` ZCML directive to support localization. - -Deprecations ------------- - -- The exception views feature replaces the need for the - ``set_notfound_view`` and ``set_forbidden_view`` methods of the - ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML - directives. Those methods and directives will continue to work for - the foreseeable future, but they are deprecated in the - documentation. - -Dependencies ------------- - -- A new install-time dependency on the ``venusian`` distribution was - added. - -- A new install-time dependency on the ``translationstring`` - distribution was added. - -- Chameleon 1.2.3 or better is now required (internationalization and - per-template debug settings). - -Internal --------- - -- View registrations and lookups are now done with three "requires" - arguments instead of two to accomodate orthogonality of exception - views. - -- The ``repoze.bfg.interfaces.IForbiddenView`` and - ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed; - they weren't APIs and they became vestigial with the addition of - exception views. - -- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias - ``repoze.bfg.compat.walk_packages``. These were only required by - internal scanning machinery; Venusian replaced the internal scanning - machinery, so these are no longer required. - -Documentation -------------- - -- Exception view documentation was added to the ``Hooks`` narrative - chapter. - -- A new narrative chapter entitled ``Internationalization and - Localization`` was added. - -- The "Environment Variables and ``ini`` File Settings" chapter was - changed: documentation about the ``default_locale_name`` setting was - added. - -- A new API chapter for the ``repoze.bfg.i18n`` module was added. - -- Documentation for the new ``translationdir`` and - ``localenegotiator`` ZCML directives were added. - -- A section was added to the Templates chapter entitled "Nicer - Exceptions in Templates" describing the result of setting - ``debug_templates = true``. - -Paster Templates ----------------- - -- All paster templates now create a ``setup.cfg`` which includes - commands related to nose testing and Babel message catalog - extraction/compilation. - -- A ``default_locale_name = en`` setting was added to each existing paster - template. - -- A ``debug_templates = true`` setting was added to each existing - paster template. - -Licensing ---------- +- The ``pyramid.testing.registerRoutesMapper`` API (deprecated in BFG + 1.2) has been removed. -- The Edgewall (BSD) license was added to the LICENSES.txt file, as - some code in the ``repoze.bfg.i18n`` derives from Babel source. +- The ``pyramid.testing.registerViewPermission`` API (deprecated in + BFG 1.1) has been removed. diff --git a/HISTORY.txt b/HISTORY.txt index bc69dbeb2..9096d6464 100644 --- a/HISTORY.txt +++ b/HISTORY.txt @@ -1,3 +1,1266 @@ +1.3b1 (2010-10-25) +================== + +Features +-------- + +- The ``paster`` template named ``bfg_routesalchemy`` has been updated + to use SQLAlchemy declarative syntax. Thanks to Ergo^. + +Bug Fixes +--------- + +- When a renderer factory could not be found, a misleading error + message was raised if the renderer name was not a string. + +Documentation +------------- + +- The ""bfgwiki2" (SQLAlchemy + url dispatch) tutorial has been + updated slightly. In particular, the source packages no longer + attempt to use a private index, and the recommended Python version + is now 2.6. It was also updated to take into account the changes to + the ``bfg_routesalchemy`` template used to set up an environment. + +- The "bfgwiki" (ZODB + traversal) tutorial has been updated slightly. + In particular, the source packages no longer attempt to use a + private index, and the recommended Python version is now 2.6. + +1.3a15 (2010-09-30) +=================== + +Features +-------- + +- The ``repoze.bfg.traversal.traversal_path`` API now eagerly attempts + to encode a Unicode ``path`` into ASCII before attempting to split + it and decode its segments. This is for convenience, effectively to + allow a (stored-as-Unicode-in-a-database, or + retrieved-as-Unicode-from-a-request-parameter) Unicode path to be + passed to ``find_model``, which eventually internally uses the + ``traversal_path`` function under the hood. In version 1.2 and + prior, if the ``path`` was Unicode, that Unicode was split on + slashes and each resulting segment value was Unicode. An + inappropriate call to the ``decode()`` method of a resulting Unicode + path segment could cause a ``UnicodeDecodeError`` to occur even if + the Unicode representation of the path contained no 'high order' + characters (it effectively did a "double decode"). By converting + the Unicode path argument to ASCII before we attempt to decode and + split, genuine errors will occur in a more obvious place while also + allowing us to handle (for convenience) the case that it's a Unicode + representation formed entirely from ASCII-compatible characters. + +1.3a14 (2010-09-14) +=================== + +Bug Fixes +--------- + +- If an exception view was registered through the legacy + ``set_notfound_view`` or ``set_forbidden_view`` APIs, the context + sent to the view was incorrect (could be ``None`` inappropriately). + +Features +-------- + +- Compatibility with WebOb 1.0. + +Requirements +------------ + +- Now requires WebOb >= 1.0. + +Backwards Incompatibilities +--------------------------- + +- Due to changes introduced WebOb 1.0, the + ``repoze.bfg.request.make_request_ascii`` event subscriber no longer + works, so it has been removed. This subscriber was meant to be used + in a deployment so that code written before BFG 0.7.0 could run + unchanged. At this point, such code will need to be rewritten to + expect Unicode from ``request.GET``, ``request.POST`` and + ``request.params`` or it will need to be changed to use + ``request.str_POST``, ``request.str_GET`` and/or + ``request.str_params`` instead of the non-``str`` versions of same, + as the non-``str`` versions of the same APIs always now perform + decoding to Unicode. + +Errata +------ + +- A prior changelog entry asserted that the ``INewResponse`` event was + not sent to listeners if the response was not "valid" (if a view or + renderer returned a response object that did not have a + status/headers/app_iter). This is not true in this release, nor was + it true in 1.3a13. + +1.3a13 (2010-09-14) +=================== + +Bug Fixes +--------- + +- The ``traverse`` route predicate could not successfully generate a + traversal path. + +Features +-------- + +- In support of making it easier to configure applications which are + "secure by default", a default permission feature was added. If + supplied, the default permission is used as the permission string to + all view registrations which don't otherwise name a permission. + These APIs are in support of that: + + - A new constructor argument was added to the Configurator: + ``default_permission``. + + - A new method was added to the Configurator: + ``set_default_permission``. + + - A new ZCML directive was added: ``default_permission``. + +- Add a new request API: ``request.add_finished_callback``. Finished + callbacks are called by the router unconditionally near the very end + of request processing. See the "Using Finished Callbacks" section + of the "Hooks" narrative chapter of the documentation for more + information. + +- A ``request.matched_route`` attribute is now added to the request + when a route has matched. Its value is the "route" object that + matched (see the ``IRoute`` interface within + ``repoze.bfg.interfaces`` API documentation for the API of a route + object). + +- The ``exception`` attribute of the request is now set slightly + earlier and in a slightly different set of scenarios, for benefit of + "finished callbacks" and "response callbacks". In previous + versions, the ``exception`` attribute of the request was not set at + all if an exception view was not found. In this version, the + ``request.exception`` attribute is set immediately when an exception + is caught by the router, even if an exception view could not be + found. + +- The ``add_route`` method of a Configurator now accepts a + ``pregenerator`` argument. The pregenerator for the resulting route + is called by ``route_url`` in order to adjust the set of arguments + passed to it by the user for special purposes, such as Pylons + 'subdomain' support. It will influence the URL returned by + ``route_url``. See the ``repoze.bfg.interfaces.IRoutePregenerator`` + interface for more information. + +Backwards Incompatibilities +--------------------------- + +- The router no longer sets the value ``wsgiorg.routing_args`` into + the environ when a route matches. The value used to be something + like ``((), matchdict)``. This functionality was only ever + obliquely referred to in change logs; it was never documented as an + API. + +- The ``exception`` attribute of the request now defaults to ``None``. + In prior versions, the ``request.exception`` attribute did not exist + if an exception was not raised by user code during request + processing; it only began existence once an exception view was + found. + +Deprecations +------------ + +- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event + interface was renamed to + ``repoze.bfg.interfaces.IApplicationCreated``. Likewise, the + ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed + to ``repoze.bfg.events.ApplicationCreated``. The older aliases will + continue to work indefinitely. + +- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was + renamed to ``repoze.bfg.interfaces.IContextFound``. Likewise, the + ``repoze.bfg.events.AfterTraversal`` class was renamed to + ``repoze.bfg.events.ContextFound``. The older aliases will continue + to work indefinitely. + +- References to the WSGI environment values ``bfg.routes.matchdict`` + and ``bfg.routes.route`` were removed from documentation. These + will stick around internally for several more releases, but it is + ``request.matchdict`` and ``request.matched_route`` are now the + "official" way to obtain the matchdict and the route object which + resulted in the match. + +Documentation +------------- + +- Added documentation for the ``default_permission`` ZCML directive. + +- Added documentation for the ``default_permission`` constructor value + and the ``set_default_permission`` method in the Configurator API + documentation. + +- Added a new section to the "security" chapter named "Setting a + Default Permission". + +- Document ``renderer_globals_factory`` and ``request_factory`` + arguments to Configurator constructor. + +- Added two sections to the "Hooks" chapter of the documentation: + "Using Response Callbacks" and "Using Finished Callbacks". + +- Added documentation of the ``request.exception`` attribute to the + ``repoze.bfg.request.Request`` API documentation. + +- Added glossary entries for "response callback" and "finished + callback". + +- The "Request Processing" narrative chapter has been updated to note + finished and response callback steps. + +- New interface in interfaces API documentation: ``IRoutePregenerator``. + +- Added a "The Matched Route" section to the URL Dispatch narrative + docs chapter, detailing the ``matched_route`` attribute. + +1.3a12 (2010-09-08) +=================== + +Bug Fixes +--------- + +- Fix a bug in ``repoze.bfg.url.static_url`` URL generation: if two + resource specifications were used to create two separate static + views, but they shared a common prefix, it was possible that + ``static_url`` would generate an incorrect URL. + +- Fix another bug in ``repoze.bfg.static_url`` URL generation: too + many slashes in generated URL. + +- Prevent a race condition which could result in a ``RuntimeError`` + when rendering a Chameleon template that has not already been + rendered once. This would usually occur directly after a restart, + when more than one person or thread is trying to execute the same + view at the same time: https://bugs.launchpad.net/karl3/+bug/621364 + +Features +-------- + +- The argument to ``repoze.bfg.configuration.Configurator.add_route`` + which was previously called ``path`` is now called ``pattern`` for + better explicability. For backwards compatibility purposes, passing + a keyword argument named ``path`` to ``add_route`` will still work + indefinitely. + +- The ``path`` attribute to the ZCML ``route`` directive is now named + ``pattern`` for better explicability. The older ``path`` attribute + will continue to work indefinitely. + +Documentation +------------- + +- All narrative, API, and tutorial docs which referred to a route + pattern as a ``path`` have now been updated to refer to them as a + ``pattern``. + +- The ``repoze.bfg.interfaces`` API documentation page is now rendered + via ``repoze.sphinx.autointerface``. + +- The URL Dispatch narrative chapter now refers to the ``interfaces`` + chapter to explain the API of an ``IRoute`` object. + +Paster Templates +---------------- + +- The routesalchemy template has been updated to use ``pattern`` in + its route declarations rather than ``path``. + +Dependencies +------------ + +- ``tests_require`` now includes ``repoze.sphinx.autointerface`` as a + dependency. + +Internal +-------- + +- Add an API to the ``Configurator`` named ``get_routes_mapper``. + This returns an object implementing the ``IRoutesMapper`` interface. + +- The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a + ``get_route`` method which returns a single Route object or + ``None``. + +- A new interface ``repoze.bfg.interfaces.IRoute`` was added. The + ``repoze.bfg.urldispatch.Route`` object implements this interface. + +- The canonical attribute for accessing the routing pattern from a + route object is now ``pattern`` rather than ``path``. + +- Use ``hash()`` rather than ``id()`` when computing the "phash" of a + custom route/view predicate in order to allow the custom predicate + some control over which predicates are "equal". + +- Use ``response.headerlist.append`` instead of + ``response.headers.add`` in + ``repoze.bfg.request.add_global_response_headers`` in case the + response is not a WebOb response. + +- The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now + accepts a different ordering of arguments. Previously it was + ``(pattern, name, factory=None, predicates=())``. It is now + ``(name, pattern, factory=None, predicates=())``. This is in + support of consistency with ``configurator.add_route``. + +- The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an + API) now accepts a different ordering of arguments. Previously it + was ``(pattern, name, factory=None, predicates=())``. It is now + ``(name, pattern, factory=None, predicates=())``. This is in + support of consistency with ``configurator.add_route``. + +1.3a11 (2010-09-05) +=================== + +Bug Fixes +--------- + +- Process the response callbacks and the NewResponse event earlier, to + enable mutations to the response to take effect. + +1.3a10 (2010-09-05) +=================== + +Features +-------- + +- A new ``repoze.bfg.request.Request.add_response_callback`` API has + been added. This method is documented in the new + ``repoze.bfg.request`` API chapter. It can be used to influence + response values before a concrete response object has been created. + +- The ``repoze.bfg.interfaces.INewResponse`` interface now includes a + ``request`` attribute; as a result, a handler for INewResponse now + has access to the request which caused the response. + +- Each of the follow methods of the Configurator now allow the + below-named arguments to be passed as "dotted name strings" + (e.g. "foo.bar.baz") rather than as actual implementation objects + that must be imported: + + setup_registry + root_factory, authentication_policy, authorization_policy, + debug_logger, locale_negotiator, request_factory, + renderer_globals_factory + + add_subscriber + subscriber, iface + + derive_view + view + + add_view + view, ``for_``, context, request_type, containment + + add_route() + view, view_for, factory, ``for_``, view_context + + scan + package + + add_renderer + factory + + set_forbidden_view + view + + set_notfound_view + view + + set_request_factory + factory + + set_renderer_globals_factory() + factory + + set_locale_negotiator + negotiator + + testing_add_subscriber + event_iface + +Bug Fixes +--------- + +- The route pattern registered internally for a a local "static view" + (either via the ``static`` ZCML directive or via the + ``add_static_view`` method of the configurator) was incorrect. It + was regsistered for e.g. ``static*traverse``, while it should have + been registered for ``static/*traverse``. Symptom: two static views + could not reliably be added to a system when they both shared the + same path prefix (e.g. ``/static`` and ``/static2``). + +Backwards Incompatibilities +--------------------------- + +- The INewResponse event is now not sent to listeners if the response + returned by view code (or a renderer) is not a "real" response + (e.g. if it does not have ``.status``, ``.headerlist`` and + ``.app_iter`` attribtues). + +Documentation +------------- + +- Add an API chapter for the ``repoze.bfg.request`` module, which + includes documentation for the ``repoze.bfg.request.Request`` class + (the "request object"). + +- Modify the "Request and Response" narrative chapter to reference the + new ``repoze.bfg.request`` API chapter. Some content was moved from + this chapter into the API documentation itself. + +- Various changes to denote that Python dotted names are now allowed + as input to Configurator methods. + +Internal +-------- + +- The (internal) feature which made it possible to attach a + ``global_response_headers`` attribute to the request (which was + assumed to contain a sequence of header key/value pairs which would + later be added to the response by the router), has been removed. + The functionality of + ``repoze.bfg.request.Request.add_response_callback`` takes its + place. + +- The ``repoze.bfg.events.NewResponse`` class's construct has changed: + it now must be created with ``(request, response)`` rather than + simply ``(response)``. + +1.3a9 (2010-08-22) +================== + +Features +-------- + +- The Configurator now accepts a dotted name *string* to a package as + a ``package`` constructor argument. The ``package`` argument was + previously required to be a package *object* (not a dotted name + string). + +- The ``repoze.bfg.configuration.Configurator.with_package`` method + was added. This method returns a new Configurator using the same + application registry as the configurator object it is called + upon. The new configurator is created afresh with its ``package`` + constructor argument set to the value passed to ``with_package``. + This feature will make it easier for future BFG versions to allow + dotted names as arguments in places where currently only object + references are allowed (the work to allow dotted names isntead of + object references everywhere has not yet been done, however). + +- The new ``repoze.bfg.configuration.Configurator.maybe_dotted`` + method resolves a Python dotted name string supplied as its + ``dotted`` argument to a global Python object. If the value cannot + be resolved, a ``repoze.bfg.configuration.ConfigurationError`` is + raised. If the value supplied as ``dotted`` is not a string, the + value is returned unconditionally without any resolution attempted. + +- The new + ``repoze.bfg.configuration.Configurator.absolute_resource_spec`` + method resolves a potentially relative "resource specification" + string into an absolute version. If the value supplied as + ``relative_spec`` is not a string, the value is returned + unconditionally without any resolution attempted. + +Backwards Incompatibilities +--------------------------- + +- The functions in ``repoze.bfg.renderers`` named ``render`` and + ``render_to_response`` introduced in 1.3a6 previously took a set of + ``**values`` arguments for the values to be passed to the renderer. + This was wrong, as renderers don't need to accept only dictionaries + (they can accept any type of object). Now, the value sent to the + renderer must be supplied as a positional argument named ``value``. + The ``request`` argument is still a keyword argument, however. + +- The functions in ``repoze.bfg.renderers`` named ``render`` and + ``render_to_response`` now accept an additonal keyword argument + named ``package``. + +- The ``get_renderer`` API in ``repoze.bfg.renderers`` now accepts a + ``package`` argument. + +Documentation +------------- + +- The ZCML ``include`` directive docs were incorrect: they specified + ``filename`` rather than (the correct) ``file`` as an allowable + attribute. + +Internal +-------- + +- The ``repoze.bfg.resource.resolve_resource_spec`` function can now + accept a package object as its ``pname`` argument instead of just a + package name. + +- The ``_renderer_factory_from_name`` and ``_renderer_from_name`` + methods of the Configurator were removed. These were never APIs. + +- The ``_render``, ``_render_to_response`` and ``_make_response`` + functions with ``repoze.bfg.render`` (added in 1.3a6) have been + removed. + +- A new helper class ``repoze.bfg.renderers.RendererHelper`` was + added. + +- The _map_view function of ``repoze.bfg.configuration`` now takes + only a renderer_name argument instead of both a ``renderer`` and + ``renderer``_name argument. It also takes a ``package`` argument + now. + +- Use ``imp.get_suffixes`` indirection in + ``repoze.bfg.path.package_name`` instead of hardcoded ``.py`` + ``.pyc`` and ``.pyo`` to use for comparison when attemtping to + decide if a directory is a package. + +- Make tests runnable again under Jython (although they do not all + pass currently). + +- The reify decorator now maintains the docstring of the function it + wraps. + +1.3a8 (2010-08-08) +================== + +Features +-------- + +- New public interface: ``repoze.bfg.exceptions.IExceptionResponse``. + This interface is provided by all internal exception classes (such + as ``repoze.bfg.exceptions.NotFound`` and + ``repoze.bfg.exceptions.Forbidden``), instances of which are both + exception objects and can behave as WSGI response objects. This + interface is made public so that exception classes which are also + valid WSGI response factories can be configured to implement them or + exception instances which are also or response instances can be + configured to provide them. + +- New API class: ``repoze.bfg.view.AppendSlashNotFoundViewFactory``. + + There can only be one Not Found view in any ``repoze.bfg`` + application. Even if you use + ``repoze.bfg.view.append_slash_notfound_view`` as the Not Found + view, ``repoze.bfg`` still must generate a ``404 Not Found`` + response when it cannot redirect to a slash-appended URL; this not + found response will be visible to site users. + + If you don't care what this 404 response looks like, and you only + need redirections to slash-appended route URLs, you may use the + ``repoze.bfg.view.append_slash_notfound_view`` object as the Not + Found view. However, if you wish to use a *custom* notfound view + callable when a URL cannot be redirected to a slash-appended URL, + you may wish to use an instance of the + ``repoze.bfg.view.AppendSlashNotFoundViewFactory`` class as the Not + Found view, supplying the notfound view callable as the first + argument to its constructor. For instance:: + + from repoze.bfg.exceptions import NotFound + from repoze.bfg.view import AppendSlashNotFoundViewFactory + + def notfound_view(context, request): + return HTTPNotFound('It aint there, stop trying!') + + custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view) + config.add_view(custom_append_slash, context=NotFound) + + The ``notfound_view`` supplied must adhere to the two-argument view + callable calling convention of ``(context, request)`` (``context`` + will be the exception object). + +Documentation +-------------- + +- Expanded the "Cleaning Up After a Request" section of the URL + Dispatch narrative chapter. + +- Expanded the "Redirecting to Slash-Appended Routes" section of the + URL Dispatch narrative chapter. + +Internal +-------- + +- Previously, two default view functions were registered at + Configurator setup (one for ``repoze.bfg.exceptions.NotFound`` named + ``default_notfound_view`` and one for + ``repoze.bfg.exceptions.Forbidden`` named + ``default_forbidden_view``) to render internal exception responses. + Those default view functions have been removed, replaced with a + generic default view function which is registered at Configurator + setup for the ``repoze.bfg.interfaces.IExceptionResponse`` interface + that simply returns the exception instance; the ``NotFound`` and + ``Forbidden`` classes are now still exception factories but they are + also response factories which generate instances that implement the + new ``repoze.bfg.interfaces.IExceptionResponse`` interface. + +1.3a7 (2010-08-01) +================== + +Features +-------- + +- The ``repoze.bfg.configuration.Configurator.add_route`` API now + returns the route object that was added. + +- A ``repoze.bfg.events.subscriber`` decorator was added. This + decorator decorates module-scope functions, which are then treated + as event listeners after a scan() is performed. See the Events + narrative documentation chapter and the ``repoze.bfg.events`` module + documentation for more information. + +Bug Fixes +--------- + +- When adding a view for a route which did not yet exist ("did not yet + exist" meaning, temporally, a view was added with a route name for a + route which had not yet been added via add_route), the value of the + ``custom_predicate`` argument to ``add_view`` was lost. Symptom: + wrong view matches when using URL dispatch and custom view + predicates together. + +- Pattern matches for a ``:segment`` marker in a URL dispatch route + pattern now always match at least one character. See "Backwards + Incompatibilities" below in this changelog. + +Backwards Incompatibilities +--------------------------- + +- A bug existed in the regular expression to do URL matching. As an + example, the URL matching machinery would cause the pattern + ``/{foo}`` to match the root URL ``/`` resulting in a match + dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might + match the URL ``//edit`` resulting in a match dictionary of + ``{'fud':u''}``. It was always the intent that ``:segment`` markers + in the pattern would need to match *at least one* character, and + never match the empty string. This, however, means that in certain + circumstances, a routing match which your application inadvertently + depended upon may no longer happen. + +Documentation +-------------- + +- Added description of the ``repoze.bfg.events.subscriber`` decorator + to the Events narrative chapter. + +- Added ``repoze.bfg.events.subscriber`` API documentation to + ``repoze.bfg.events`` API docs. + +- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By + Default; BFG Does Not" to the "Design Defense" chapter. + +1.3a6 (2010-07-25) +================== + +Features +-------- + +- New argument to ``repoze.bfg.configuration.Configurator.add_route`` + and the ``route`` ZCML directive: ``traverse``. If you would like + to cause the ``context`` to be something other than the ``root`` + object when this route matches, you can spell a traversal pattern as + the ``traverse`` argument. This traversal pattern will be used as + the traversal path: traversal will begin at the root object implied + by this route (either the global root, or the object returned by the + ``factory`` associated with this route). + + The syntax of the ``traverse`` argument is the same as it is for + ``path``. For example, if the ``path`` provided is + ``articles/:article/edit``, and the ``traverse`` argument provided + is ``/:article``, when a request comes in that causes the route to + match in such a way that the ``article`` match value is '1' (when + the request URI is ``/articles/1/edit``), the traversal path will be + generated as ``/1``. This means that the root object's + ``__getitem__`` will be called with the name ``1`` during the + traversal phase. If the ``1`` object exists, it will become the + ``context`` of the request. The Traversal narrative has more + information about traversal. + + If the traversal path contains segment marker names which are not + present in the path argument, a runtime error will occur. The + ``traverse`` pattern should not contain segment markers that do not + exist in the ``path``. + + A similar combining of routing and traversal is available when a + route is matched which contains a ``*traverse`` remainder marker in + its path. The ``traverse`` argument allows you to associate route + patterns with an arbitrary traversal path without using a a + ``*traverse`` remainder marker; instead you can use other match + information. + + Note that the ``traverse`` argument is ignored when attached to a + route that has a ``*traverse`` remainder marker in its path. + +- A new method of the ``Configurator`` exists: + ``set_request_factory``. If used, this method will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- The ``Configurator`` constructor takes an additional argument: + ``request_factory``. If used, this argument will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- The ``Configurator`` constructor takes an additional argument: + ``request_factory``. If used, this argument will set the factory + used by the ``repoze.bfg`` router to create all request objects. + +- A new method of the ``Configurator`` exists: + ``set_renderer_globals_factory``. If used, this method will set the + factory used by the ``repoze.bfg`` router to create renderer + globals. + +- A new method of the ``Configurator`` exists: ``get_settings``. If + used, this method will return the current settings object (performs + the same job as the ``repoze.bfg.settings.get_settings`` API). + +- The ``Configurator`` constructor takes an additional argument: + ``renderer_globals_factory``. If used, this argument will set the + factory used by the ``repoze.bfg`` router to create renderer + globals. + +- Add ``repoze.bfg.renderers.render``, + ``repoze.bfg.renderers.render_to_response`` and + ``repoze.bfg.renderers.get_renderer`` functions. These are + imperative APIs which will use the same rendering machinery used by + view configurations with a ``renderer=`` attribute/argument to + produce a rendering or renderer. Because these APIs provide a + central API for all rendering, they now form the preferred way to + perform imperative template rendering. Using functions named + ``render_*`` from modules such as ``repoze.bfg.chameleon_zpt`` and + ``repoze.bfg.chameleon_text`` is now discouraged (although not + deprecated). The code the backing older templating-system-specific + APIs now calls into the newer ``repoze.bfg.renderer`` code. + +- The ``repoze.bfg.configuration.Configurator.testing_add_template`` + has been renamed to ``testing_add_renderer``. A backwards + compatibility alias is present using the old name. + +Documentation +------------- + +- The ``Hybrid`` narrative chapter now contains a description of the + ``traverse`` route argument. + +- The ``Hooks`` narrative chapter now contains sections about + changing the request factory and adding a renderer globals factory. + +- The API documentation includes a new module: + ``repoze.bfg.renderers``. + +- The ``Templates`` chapter was updated; all narrative that used + templating-specific APIs within examples to perform rendering (such + as the ``repoze.bfg.chameleon_zpt.render_template_to_response`` + method) was changed to use ``repoze.bfg.renderers.render_*`` + functions. + +Bug Fixes +--------- + +- The ``header`` predicate (when used as either a view predicate or a + route predicate) had a problem when specified with a name/regex + pair. When the header did not exist in the headers dictionary, the + regex match could be fed ``None``, causing it to throw a + ``TypeError: expected string or buffer`` exception. Now, the + predicate returns False as intended. + +Deprecations +------------ + +- The ``repoze.bfg.renderers.rendered_response`` function was never an + official API, but may have been imported by extensions in the wild. + It is officially deprecated in this release. Use + ``repoze.bfg.renderers.render_to_response`` instead. + +- The following APIs are *documentation* deprecated (meaning they are + officially deprecated in documentation but do not raise a + deprecation error upon their usage, and may continue to work for an + indefinite period of time): + + In the ``repoze.bfg.chameleon_zpt`` module: ``get_renderer``, + ``get_template``, ``render_template``, + ``render_template_to_response``. The suggested alternatives are + documented within the docstrings of those methods (which are still + present in the documentation). + + In the ``repoze.bfg.chameleon_text`` module: ``get_renderer``, + ``get_template``, ``render_template``, + ``render_template_to_response``. The suggested alternatives are + documented within the docstrings of those methods (which are still + present in the documentation). + + In general, to perform template-related functions, one should now + use the various methods in the ``repoze.bfg.renderers`` module. + +Backwards Incompatibilities +--------------------------- + +- A new internal exception class (*not* an API) named + ``repoze.bfg.exceptions.PredicateMismatch`` now exists. This + exception is currently raised when no constituent view of a + multiview can be called (due to no predicate match). Previously, in + this situation, a ``repoze.bfg.exceptions.NotFound`` was raised. We + provide backwards compatibility for code that expected a + ``NotFound`` to be raised when no predicates match by causing + ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from + ``NotFound``. This will cause any exception view registered for + ``NotFound`` to be called when a predicate mismatch occurs, as was + the previous behavior. + + There is however, one perverse case that will expose a backwards + incompatibility. If 1) you had a view that was registered as a + member of a multiview 2) this view explicitly raised a ``NotFound`` + exception *in order to* proceed to the next predicate check in the + multiview, that code will now behave differently: rather than + skipping to the next view match, a NotFound will be raised to the + top-level exception handling machinery instead. For code to be + depending upon the behavior of a view raising ``NotFound`` to + proceed to the next predicate match, would be tragic, but not + impossible, given that ``NotFound`` is a public interface. + ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and + cannot be depended upon by application code, so you should not + change your view code to raise ``PredicateMismatch``. Instead, move + the logic which raised the ``NotFound`` exception in the view out + into a custom view predicate. + +- If, when you run your application's unit test suite under BFG 1.3, a + ``KeyError`` naming a template or a ``ValueError`` indicating that a + 'renderer factory' is not registered may is raised + (e.g. ``ValueError: No factory for renderer named '.pt' when looking + up karl.views:templates/snippets.pt``), you may need to perform some + extra setup in your test code. + + The best solution is to use the + ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or, + alternately the deprecated + ``repoze.bfg.testing.registerTemplateRenderer`` or + ``registerDummyRenderer``) API within the code comprising each + individual unit test suite to register a "dummy" renderer for each + of the templates and renderers used by code under test. For + example:: + + config = Configurator() + config.testing_add_renderer('karl.views:templates/snippets.pt') + + This will register a basic dummy renderer for this particular + missing template. The ``testing_add_renderer`` API actually + *returns* the renderer, but if you don't care about how the render + is used, you don't care about having a reference to it either. + + A more rough way to solve the issue exists. It causes the "real" + template implementations to be used while the system is under test, + which is suboptimal, because tests will run slower, and unit tests + won't actually *be* unit tests, but it is easier. Always ensure you + call the ``setup_registry()`` method of the Configurator . Eg:: + + reg = MyRegistry() + config = Configurator(registry=reg) + config.setup_registry() + + Calling ``setup_registry`` only has an effect if you're *passing in* + a ``registry`` argument to the Configurator constructor. + ``setup_registry`` is called by the course of normal operations + anyway if you do not pass in a ``registry``. + + If your test suite isn't using a Configurator yet, and is still + using the older ``repoze.bfg.testing`` APIs name ``setUp`` or + ``cleanUp``, these will register the renderers on your behalf. + + A variant on the symptom for this theme exists: you may already be + dutifully registering a dummy template or renderer for a template + used by the code you're testing using ``testing_register_renderer`` + or ``registerTemplateRenderer``, but (perhaps unbeknownst to you) + the code under test expects to be able to use a "real" template + renderer implementation to retrieve or render *another* template + that you forgot was being rendered as a side effect of calling the + code you're testing. This happened to work because it found the + *real* template while the system was under test previously, and now + it cannot. The solution is the same. + + It may also help reduce confusion to use a *resource specification* + to specify the template path in the test suite and code rather than + a relative path in either. A resource specification is unambiguous, + while a relative path needs to be relative to "here", where "here" + isn't always well-defined ("here" in a test suite may or may not be + the same as "here" in the code under test). + +1.3a5 (2010-07-14) +================== + +Features +-------- + +- New internal exception: ``repoze.bfg.exceptions.URLDecodeError``. + This URL is a subclass of the built-in Python exception named + ``UnicodeDecodeError``. + +- When decoding a URL segment to Unicode fails, the exception raised + is now ``repoze.bfg.exceptions.URLDecodeError`` instead of + ``UnicodeDecodeError``. This makes it possible to register an + exception view invoked specifically when ``repoze.bfg`` cannot + decode a URL. + +Bug Fixes +--------- + +- Fix regression in + ``repoze.bfg.configuration.Configurator.add_static_view``. Before + 1.3a4, view names that contained a slash were supported as route + prefixes. 1.3a4 broke this by trying to treat them as full URLs. + +Documentation +------------- + +- The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to + the exceptions chapter of the API documentation. + +Backwards Incompatibilities +---------------------------- + +- in previous releases, when a URL could not be decoded from UTF-8 + during traversal, a ``TypeError`` was raised. Now the error which + is raised is a ``repoze.bfg.exceptions.URLDecodeError``. + +1.3a4 (2010-07-03) +================== + +Features +-------- + +- Undocumented hook: make ``get_app`` and ``get_root`` of the + ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where + endware may interfere with the default versions. + +- In earlier versions, a custom route predicate associated with a url + dispatch route (each of the predicate functions fed to the + ``custom_predicates`` argument of + ``repoze.bfg.configuration.Configurator.add_route``) has always + required a 2-positional argument signature, e.g. ``(context, + request)``. Before this release, the ``context`` argument was + always ``None``. + + As of this release, the first argument passed to a predicate is now + a dictionary conventionally named ``info`` consisting of ``route``, + and ``match``. ``match`` is a dictionary: it represents the + arguments matched in the URL by the route. ``route`` is an object + representing the route which was matched. + + This is useful when predicates need access to the route match. For + example:: + + def any_of(segment_name, *args): + def predicate(info, request): + if info['match'][segment_name] in args: + return True + return predicate + + num_one_two_or_three = any_of('num, 'one', 'two', 'three') + + add_route('num', '/:num', custom_predicates=(num_one_two_or_three,)) + + The ``route`` object is an object that has two useful attributes: + ``name`` and ``path``. The ``name`` attribute is the route name. + The ``path`` attribute is the route pattern. An example of using + the route in a set of route predicates:: + + def twenty_ten(info, request): + if info['route'].name in ('ymd', 'ym', 'y'): + return info['match']['year'] == '2010' + + add_route('y', '/:year', custom_predicates=(twenty_ten,)) + add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,)) + add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,)) + +- The ``repoze.bfg.url.route_url`` API has changed. If a keyword + ``_app_url`` is present in the arguments passed to ``route_url``, + this value will be used as the protocol/hostname/port/leading path + prefix of the generated URL. For example, using an ``_app_url`` of + ``http://example.com:8080/foo`` would cause the URL + ``http://example.com:8080/foo/fleeb/flub`` to be returned from this + function if the expansion of the route pattern associated with the + ``route_name`` expanded to ``/fleeb/flub``. + +- It is now possible to use a URL as the ``name`` argument fed to + ``repoze.bfg.configuration.Configurator.add_static_view``. When the + name argument is a URL, the ``repoze.bfg.url.static_url`` API will + generate join this URL (as a prefix) to a path including the static + file name. This makes it more possible to put static media on a + separate webserver for production, while keeping static media + package-internal and served by the development webserver during + development. + +Documentation +------------- + +- The authorization chapter of the ZODB Wiki Tutorial + (docs/tutorials/bfgwiki) was changed to demonstrate authorization + via a group rather than via a direct username (thanks to Alex + Marandon). + +- The authorization chapter of the SQLAlchemy Wiki Tutorial + (docs/tutorials/bfgwiki2) was changed to demonstrate authorization + via a group rather than via a direct username. + +- Redirect requests for tutorial sources to + http://docs.repoze.org/bfgwiki-1.3 and + http://docs.repoze.org/bfgwiki2-1.3/ respectively. + +- A section named ``Custom Route Predicates`` was added to the URL + Dispatch narrative chapter. + +- The Static Resources chapter has been updated to mention using + ``static_url`` to generate URLs to external webservers. + +Internal +-------- + +- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new + abstraction revolving around the (still-internal) + ``repoze.bfg.static.StaticURLInfo`` helper class. + +1.3a3 (2010-05-01) +================== + +Paster Templates +---------------- + +- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer + register a ``handle_teardown`` event listener which calls + ``DBSession.remove``. This was found by Chris Withers to be + unnecessary. + +Documentation +------------- + +- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation + was changed to remove the ``handle_teardown`` event listener which + calls ``DBSession.remove``. + +- Any mention of the ``handle_teardown`` event listener as used by the + paster templates was removed from the URL Dispatch narrative chapter. + +- A section entitled Detecting Available Languages was added to the + i18n narrative docs chapter. + +1.3a2 (2010-04-28) +================== + +Features +-------- + +- A locale negotiator no longer needs to be registered explicitly. The + default locale negotiator at + ``repoze.bfg.i18n.default_locale_negotiator`` is now used + unconditionally as... um, the default locale negotiator. + +- The default locale negotiator has become more complex. + + * First, the negotiator looks for the ``_LOCALE_`` attribute of + the request object (possibly set by a view or an event listener). + + * Then it looks for the ``request.params['_LOCALE_']`` value. + + * Then it looks for the ``request.cookies['_LOCALE_']`` value. + +Backwards Incompatibilities +--------------------------- + +- The default locale negotiator now looks for the parameter named + ``_LOCALE_`` rather than a parameter named ``locale`` in + ``request.params``. + +Behavior Changes +---------------- + +- A locale negotiator may now return ``None``, signifying that the + default locale should be used. + +Documentation +------------- + +- Documentation concerning locale negotiation in the + Internationalizationa and Localization chapter was updated. + +- Expanded portion of i18n narrative chapter docs which discuss + working with gettext files. + +1.3a1 (2010-04-26) +================== + +Features +-------- + +- Added "exception views". When you use an exception (anything that + inherits from the Python ``Exception`` builtin) as view context + argument, e.g.:: + + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound + + @bfg_view(context=NotFound) + def notfound_view(request): + return HTTPNotFound() + + For the above example, when the ``repoze.bfg.exceptions.NotFound`` + exception is raised by any view or any root factory, the + ``notfound_view`` view callable will be invoked and its response + returned. + + Other normal view predicates can also be used in combination with an + exception view registration:: + + from repoze.bfg.view import bfg_view + from repoze.bfg.exceptions import NotFound + from webob.exc import HTTPNotFound + + @bfg_view(context=NotFound, route_name='home') + def notfound_view(request): + return HTTPNotFound() + + The above exception view names the ``route_name`` of ``home``, + meaning that it will only be called when the route matched has a + name of ``home``. You can therefore have more than one exception + view for any given exception in the system: the "most specific" one + will be called when the set of request circumstances which match the + view registration. The only predicate that cannot be not be used + successfully is ``name``. The name used to look up an exception + view is always the empty string. + + Existing (pre-1.3) normal views registered against objects + inheriting from ``Exception`` will continue to work. Exception + views used for user-defined exceptions and system exceptions used as + contexts will also work. + + The feature can be used with any view registration mechanism + (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view`` + styles). + + This feature was kindly contributed by Andrey Popp. + +- Use "Venusian" (`http://docs.repoze.org/venusian + <http://docs.repoze.org/venusian>`_) to perform ``bfg_view`` + decorator scanning rather than relying on a BFG-internal decorator + scanner. (Truth be told, Venusian is really just a generalization + of the BFG-internal decorator scanner). + +- Internationalization and localization features as documented in the + narrative documentation chapter entitled ``Internationalization and + Localization``. + +- A new deployment setting named ``default_locale_name`` was added. + If this string is present as a Paster ``.ini`` file option, it will + be considered the default locale name. The default locale name is + used during locale-related operations such as language translation. + +- It is now possible to turn on Chameleon template "debugging mode" + for all Chameleon BFG templates by setting a BFG-related Paster + ``.ini`` file setting named ``debug_templates``. The exceptions + raised by Chameleon templates when a rendering fails are sometimes + less than helpful. ``debug_templates`` allows you to configure your + application development environment so that exceptions generated by + Chameleon during template compilation and execution will contain + more helpful debugging information. This mode is on by default in + all new projects. + +- Add a new method of the Configurator named ``derive_view`` which can + be used to generate a BFG view callable from a user-supplied + function, instance, or class. This useful for external framework and + plugin authors wishing to wrap callables supplied by their users + which follow the same calling conventions and response conventions + as objects that can be supplied directly to BFG as a view callable. + See the ``derive_view`` method in the + ``repoze.bfg.configuration.Configurator`` docs. + +ZCML +---- + +- Add a ``translationdir`` ZCML directive to support localization. + +- Add a ``localenegotiator`` ZCML directive to support localization. + +Deprecations +------------ + +- The exception views feature replaces the need for the + ``set_notfound_view`` and ``set_forbidden_view`` methods of the + ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML + directives. Those methods and directives will continue to work for + the foreseeable future, but they are deprecated in the + documentation. + +Dependencies +------------ + +- A new install-time dependency on the ``venusian`` distribution was + added. + +- A new install-time dependency on the ``translationstring`` + distribution was added. + +- Chameleon 1.2.3 or better is now required (internationalization and + per-template debug settings). + +Internal +-------- + +- View registrations and lookups are now done with three "requires" + arguments instead of two to accomodate orthogonality of exception + views. + +- The ``repoze.bfg.interfaces.IForbiddenView`` and + ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed; + they weren't APIs and they became vestigial with the addition of + exception views. + +- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias + ``repoze.bfg.compat.walk_packages``. These were only required by + internal scanning machinery; Venusian replaced the internal scanning + machinery, so these are no longer required. + +Documentation +------------- + +- Exception view documentation was added to the ``Hooks`` narrative + chapter. + +- A new narrative chapter entitled ``Internationalization and + Localization`` was added. + +- The "Environment Variables and ``ini`` File Settings" chapter was + changed: documentation about the ``default_locale_name`` setting was + added. + +- A new API chapter for the ``repoze.bfg.i18n`` module was added. + +- Documentation for the new ``translationdir`` and + ``localenegotiator`` ZCML directives were added. + +- A section was added to the Templates chapter entitled "Nicer + Exceptions in Templates" describing the result of setting + ``debug_templates = true``. + +Paster Templates +---------------- + +- All paster templates now create a ``setup.cfg`` which includes + commands related to nose testing and Babel message catalog + extraction/compilation. + +- A ``default_locale_name = en`` setting was added to each existing paster + template. + +- A ``debug_templates = true`` setting was added to each existing + paster template. + +Licensing +--------- + +- The Edgewall (BSD) license was added to the LICENSES.txt file, as + some code in the ``repoze.bfg.i18n`` derives from Babel source. + 1.2 (2010-02-10) ================ diff --git a/docs/api/testing.rst b/docs/api/testing.rst index 2fdea6cd7..fc4b76cc7 100644 --- a/docs/api/testing.rst +++ b/docs/api/testing.rst @@ -15,8 +15,6 @@ .. autofunction:: registerView - .. autofunction:: registerViewPermission - .. autofunction:: registerUtility .. autofunction:: registerAdapter @@ -25,8 +23,6 @@ .. autofunction:: registerRoute - .. autofunction:: registerRoutesMapper - .. autofunction:: registerSettings .. autofunction:: setUp diff --git a/docs/authorintro.rst b/docs/authorintro.rst index 8a5387199..c97fbd00d 100644 --- a/docs/authorintro.rst +++ b/docs/authorintro.rst @@ -2,10 +2,10 @@ Author Introduction ===================== -Welcome to "The :mod:`repoze.bfg` Web Application Framework". In this +Welcome to "The :mod:`pyramid` Web Application Framework". In this introduction, I'll describe the audience for this book, I'll describe the book content, I'll provide some context regarding the genesis of -:mod:`repoze.bfg`, and I'll thank some important people. +:mod:`pyramid`, and I'll thank some important people. I hope you enjoy both this book and the software it documents. I've had a blast writing both. @@ -42,7 +42,7 @@ book. For example, the book doesn't try to define common web-related concepts like "URL" or "query string." Likewise, the book describes various interactions in terms of the HTTP protocol, but it does not describe how the HTTP protocol works in detail. Like any good web -framework, though, :mod:`repoze.bfg` shields you from needing to know +framework, though, :mod:`pyramid` shields you from needing to know most of the gory details of web protocols and low-level data structures. As a result, you can usually avoid becoming "blocked" while you read this book even if you don't yet deeply understand web @@ -58,10 +58,10 @@ This book is divided into four major parts: :ref:`narrative_documentation` - This is documentation which describes :mod:`repoze.bfg` concepts in + This is documentation which describes :mod:`pyramid` concepts in narrative form, written in a largely conversational tone. Each narrative documentation chapter describes an isolated - :mod:`repoze.bfg` concept. You should be able to get useful + :mod:`pyramid` concept. You should be able to get useful information out of the narrative chapters if you read them out-of-order, or when you need only a reminder about a particular topic while you're developing an application. @@ -71,18 +71,18 @@ This book is divided into four major parts: Each tutorial builds a sample application or implements a set of concepts with a sample; it then describes the application or concepts in terms of the sample. You should read the tutorials if - you want a guided tour of :mod:`repoze.bfg`. + you want a guided tour of :mod:`pyramid`. :ref:`api_reference` Comprehensive reference material for every public API exposed by - :mod:`repoze.bfg`. The API documentation is organized + :mod:`pyramid`. The API documentation is organized alphabetically by module name. :ref:`zcml_reference` Comprehensive reference material for every :term:`ZCML directive` - provided by :mod:`repoze.bfg`. The ZCML directive documentation is + provided by :mod:`pyramid`. The ZCML directive documentation is organized alphabetically by directive name. .. index:: @@ -90,10 +90,13 @@ This book is divided into four major parts: single: Zope 3 single: Zope 2 single: repoze.bfg genesis + single: pyramid genesis The Genesis of :mod:`repoze.bfg` ================================ +Before the end of 2010, :mod:`pyramid` was known as :mod:`repoze.bfg`. + I wrote :mod:`repoze.bfg` after many years of writing applications using :term:`Zope`. Zope provided me with a lot of mileage: it wasn't until almost a decade of successfully creating applications using it @@ -130,13 +133,16 @@ I decided that in the long term, creating a simpler framework that retained features I had become accustomed to when developing Zope applications was a more reasonable idea than continuing to use any Zope publisher or living with the limitations and unfamiliarities of a -different framework. The result is what is now :mod:`repoze.bfg`. +different framework. The result is what is now :mod:`pyramid`. + +The Genesis of :mod:`pyramid` +============================= -It is immodest to say so, but I believe :mod:`repoze.bfg` has turned -out to be the very best Python web framework available today, bar -none. It combines all the "good parts" from other web frameworks into -a cohesive whole that is reliable, down-to-earth, flexible, speedy, -and well-documented. +What was :mod:`repoze.bfg` has become :mod:`pyramid` as the result of +a coalition built between the :term:`Repoze` and :term:`Pylons` +community throughout the year 2010. By merging technology, we're able +to reduce duplication of effort, and take advantage of more of each +others' technology. .. index:: single: Bicking, Ian diff --git a/docs/changes.rst b/docs/changes.rst index c95a3d72a..a623f0b3f 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -1,4 +1,4 @@ -:mod:`repoze.bfg` Change History +:mod:`pyramid` Change History ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: ../CHANGES.txt diff --git a/docs/conf.py b/docs/conf.py index e8924f73e..eb236826b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# repoze.bfg documentation build configuration file, created by +# pyramid documentation build configuration file, created by # sphinx-quickstart on Wed Jul 16 13:18:14 2008. # # This file is execfile()d with the current directory set to its containing dir. @@ -54,14 +54,14 @@ source_suffix = '.rst' master_doc = 'index' # General substitutions. -project = 'The repoze.bfg Web Application Framework' +project = 'The Pyramid Web Application Development Framework' copyright = '2008-2010, Agendaless Consulting' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. # # The short X.Y version. -version = '1.3a15' +version = '1.0a1' # The full version, including alpha/beta/rc tags. release = version @@ -105,7 +105,7 @@ html_style = 'repoze.css' # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". -#html_title = 'The repoze.bfg Web Application Framework v%release%' +#html_title = 'The Pyramid Web Application Development Framework v%release%' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -174,7 +174,8 @@ latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ - ('latexindex', 'repozebfg.tex', 'The repoze.bfg Web Application Framework', + ('latexindex', 'repozebfg.tex', + 'The Pyramid Web Application Development Framework', 'Chris McDonough', 'manual'), ] @@ -309,7 +310,7 @@ latex_elements = { 'wrapperclass':'book', 'date':'', 'releasename':'Version', - 'title':r'The repoze.bfg Web Application \newline Framework', + 'title':r'The Pyramid Web Application \newline Development Framework', # 'pointsize':'12pt', # uncomment for 12pt version } @@ -373,28 +374,6 @@ def setup(app): app.add_directive('mainmatter', mainmatter, 1, (0, 0, 0)) app.add_directive('backmatter', backmatter, 1, (0, 0, 0)) -# strip "repoze.bfg." from all inline literals - -from sphinx.writers.latex import LaTeXTranslator - -def visit_literal(self, node): - self.no_contractions += 1 - content = self.encode(node.astext().strip()) - self.no_contractions -= 1 - if self.in_title: - self.body.append(r'\texttt{%s}' % content) - elif node.has_key('role') and node['role'] == 'samp': - self.body.append(r'\samp{%s}' % content) - else: - # XXX special treatment of overlong ``repoze.bfg.foo`` - # literals. - if 'repoze.bfg.' in content: - content = content.replace('repoze.bfg.', '') - self.body.append(r'\code{%s}' % content) - raise nodes.SkipNode - -LaTeXTranslator.visit_literal = visit_literal - # turn off all line numbers in latex formatting ## from pygments.formatters import LatexFormatter @@ -410,7 +389,7 @@ LaTeXTranslator.visit_literal = visit_literal # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = 'The repoze.bfg Web Application Framework, Version 1.3' +epub_title = 'The Pyramid Web Application Development Framework, Version 1.0' epub_author = 'Chris McDonough' epub_publisher = 'Agendaless Consulting' epub_copyright = '2008-2010' @@ -427,7 +406,7 @@ epub_scheme = 'ISBN' epub_identifier = '0615345379' # A unique identification for the text. -epub_uid = 'The repoze.bfg Web Application Framework, Version 1.3-v0' +epub_uid = 'The Pyramid Web Application Development Framework, Version 1.0' # HTML files that should be inserted before the pages created by sphinx. # The format is a list of tuples containing the path and title. diff --git a/docs/conventions.rst b/docs/conventions.rst index 020ed6dac..aaa4e8d09 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -75,19 +75,3 @@ discussed on a page, is rendered like so: Sidebar information. -In printed versions of this book, Python modules classes, methods, -functions, and attributes that are part of the :mod:`repoze.bfg` -module are referenced in paragraph text. These are contracted to omit -the ``repoze.bfg`` prefix to reduce redundancy and increase -readability. Therefore, where you might expect: - - .. code-block:: text - - repoze.bfg.configuration.Configurator.add_view (pp. XXX) - -Instead a contracted version will be rendered: - - .. code-block:: text - - configuration.Configurator.add_view (pp. XXX) - diff --git a/docs/copyright.rst b/docs/copyright.rst index 791d69f81..30a544cc4 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -1,7 +1,7 @@ Copyright, Trademarks, and Attributions ======================================= -*The repoze.bfg Web Application Framework, Version 1.2* +*The Pyramid Web Application Development Framework, Version 1.0* by Chris McDonough @@ -26,9 +26,9 @@ similar license to this one. .. note:: - While the :mod:`repoze.bfg` documentation is offered under the + While the :mod:`pyramid` documentation is offered under the Creative Commons Attribution-Nonconmmercial-Share Alike 3.0 United - States License, the :mod:`repoze.bfg` *software* is offered under a + States License, the :mod:`pyramid` *software* is offered under a `less restrictive (BSD-like) license <http://repoze.org/license.html>`_ . @@ -74,21 +74,16 @@ Contacting The Publisher Please send documentation licensing inquiries, translation inquiries, and other business communications to `Agendaless Consulting <mailto:webmaster@agendaless.com>`_. Please send software and other -technical queries to the `repoze-dev maillist -<http://lists.repoze.org/listinfo/repoze-dev>`_. +technical queries to the `Pylons-discuss maillist +<http://groups.google.com/group/pylons-discuss>`_. HTML Version and Source Code ---------------------------- An HTML version of this book is freely available via -http://bfg.repoze.org. +http://pylonshq.com/pyramid. The source code for the examples used in this book are available -within the :mod:`repoze.bfg` software distribution, always available -via http://bfg.repoze.org. - -Errata ------- - -Errata for this book will be placed at `http://bfg.repoze.org/book_errata`. +within the :mod:`pyramid` software distribution, always available +via http://pylonshq.com/pyramid. diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 9ae7c50d6..0e4784c66 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1,9 +1,9 @@ .. _design_defense: -Defending BFG's Design -====================== +Defending Pyramid's Design +========================== -From time to time, challenges to various aspects of :mod:`repoze.bfg` +From time to time, challenges to various aspects of :mod:`pyramid` design are lodged. To give context to discussions that follow, we detail some of the design decisions and trade-offs here. In some cases, we acknowledge that the framework can be made better and we @@ -11,17 +11,17 @@ describe future steps which will be taken to improve it; in some cases we just file the challenge as "noted", as obviously you can't please everyone all of the time. -BFG Uses A Zope Component Architecture ("ZCA") Registry -------------------------------------------------------- +Pyramid Uses A Zope Component Architecture ("ZCA") Registry +----------------------------------------------------------- -:mod:`repoze.bfg` uses a :term:`Zope Component Architecture` (ZCA) +:mod:`pyramid` uses a :term:`Zope Component Architecture` (ZCA) "component registry" as its :term:`application registry` under the -hood. This is a point of some contention. :mod:`repoze.bfg` is of a +hood. This is a point of some contention. :mod:`pyramid` is of a :term:`Zope` pedigree, so it was natural for its developers to use a ZCA registry at its inception. However, we understand that using a ZCA registry has issues and consequences, which we've attempted to address as best we can. Here's an introspection about -:mod:`repoze.bfg` use of a ZCA registry, and the trade-offs its usage +:mod:`pyramid` use of a ZCA registry, and the trade-offs its usage involves. Problems @@ -39,7 +39,7 @@ global API: .. code-block:: python :linenos: - from repoze.bfg.interfaces import ISettings + from pyramid.interfaces import ISettings from zope.component import getUtility settings = getUtility(ISettings) @@ -78,7 +78,7 @@ That's sort of the best answer in this context (a more specific answer would require knowledge of internals). Can there be more than one registry? Yes. So *which* registry does it find the registration in? Well, the "current" registry of course. In terms of -:mod:`repoze.bfg`, the current registry is a thread local variable. +:mod:`pyramid`, the current registry is a thread local variable. Using an API that consults a thread local makes understanding how it works non-local. @@ -91,7 +91,7 @@ nor was it performed imperatively. This is extremely hard to comprehend. Problem number six. Clearly there's some amount of cognitive load here that needs to be -borne by a reader of code that extends the :mod:`repoze.bfg` framework +borne by a reader of code that extends the :mod:`pyramid` framework due to its use of the ZCA, even if he or she is already an expert Python programmer and whom is an expert in the domain of web applications. This is suboptimal. @@ -99,15 +99,15 @@ applications. This is suboptimal. Ameliorations +++++++++++++ -First, the primary amelioration: :mod:`repoze.bfg` *does not expect +First, the primary amelioration: :mod:`pyramid` *does not expect application developers to understand ZCA concepts or any of its APIs*. If an *application* developer needs to understand a ZCA concept or API -during the creation of a :mod:`repoze.bfg` application, we've failed +during the creation of a :mod:`pyramid` application, we've failed on some axis. Instead, the framework hides the presence of the ZCA registry behind special-purpose API functions that *do* use ZCA APIs. Take for -example the ``repoze.bfg.security.authenticated_userid`` function, +example the ``pyramid.security.authenticated_userid`` function, which returns the userid present in the current request or ``None`` if no userid is present in the current request. The application developer calls it like so: @@ -116,7 +116,7 @@ developer calls it like so: .. code-block:: python :linenos: - from repoze.bfg.security import authenticated_userid + from pyramid.security import authenticated_userid userid = authenticated_userid(request) He now has the current user id. @@ -143,7 +143,7 @@ application developers. Application developers should just never know about the ZCA API: they should call a Python function with some object germane to the domain as an argument, and it should returns a result. A corollary that follows is that any reader of an application that has -been written using :mod:`repoze.bfg` needn't understand the ZCA API +been written using :mod:`pyramid` needn't understand the ZCA API either. Hiding the ZCA API from application developers and code readers is a @@ -151,24 +151,24 @@ form of enhancing "domain specificity". No application developer wants to need to understand the minutiae of the mechanics of how a web framework does its thing. People want to deal in concepts that are closer to the domain they're working in: for example, web developers -want to know about *users*, not *utilities*. :mod:`repoze.bfg` uses +want to know about *users*, not *utilities*. :mod:`pyramid` uses the ZCA as an implementation detail, not as a feature which is exposed to end users. However, unlike application developers, *framework developers*, -including people who want to override :mod:`repoze.bfg` functionality +including people who want to override :mod:`pyramid` functionality via preordained framework plugpoints like traversal or view lookup *must* understand the ZCA registry API. -:mod:`repoze.bfg` framework developers were so concerned about +:mod:`pyramid` framework developers were so concerned about conceptual load issues of the ZCA registry API for framework developers that a `replacement registry implementation <http://svn.repoze.org/repoze.component/trunk>`_ named :mod:`repoze.component` was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work -on it was largely abandoned and it is not used in :mod:`repoze.bfg`. -We continued to use a ZCA registry within :mod:`repoze.bfg` because it +on it was largely abandoned and it is not used in :mod:`pyramid`. +We continued to use a ZCA registry within :mod:`pyramid` because it ultimately proved a better fit. .. note:: We continued using ZCA registry rather than disusing it in @@ -181,16 +181,16 @@ ultimately proved a better fit. reinventing the wheel. Making framework developers and extenders understand the ZCA registry -API is a trade-off. We (the :mod:`repoze.bfg` developers) like the +API is a trade-off. We (the :mod:`pyramid` developers) like the features that the ZCA registry gives us, and we have long-ago borne the weight of understanding what it does and how it works. The -authors of :mod:`repoze.bfg` understand the ZCA deeply and can read +authors of :mod:`pyramid` understand the ZCA deeply and can read code that uses it as easily as any other code. But we recognize that developers who my want to extend the framework are not as comfortable with the ZCA registry API as the original developers are with it. So, for the purposes of being kind to -third-party :mod:`repoze.bfg` framework developers in, we've drawn +third-party :mod:`pyramid` framework developers in, we've drawn some lines in the sand. #) In all "core" code, We've made use of ZCA global API functions such @@ -200,25 +200,25 @@ some lines in the sand. .. code-block:: python :linenos: - from repoze.bfg.interfaces import IAuthenticationPolicy + from pyramid.interfaces import IAuthenticationPolicy from zope.component import getUtility policy = getUtility(IAuthenticationPolicy) - :mod:`repoze.bfg` code will usually do: + :mod:`pyramid` code will usually do: .. code-block:: python :linenos: - from repoze.bfg.interfaces import IAuthenticationPolicy - from repoze.bfg.threadlocal import get_current_registry + from pyramid.interfaces import IAuthenticationPolicy + from pyramid.threadlocal import get_current_registry registry = get_current_registry() policy = registry.getUtility(IAuthenticationPolicy) While the latter is more verbose, it also arguably makes it more - obvious what's going on. All of the :mod:`repoze.bfg` core code uses + obvious what's going on. All of the :mod:`pyramid` core code uses this pattern rather than the ZCA global API. -#) We've turned the component registry used by :mod:`repoze.bfg` into +#) We've turned the component registry used by :mod:`pyramid` into something that is accessible using the plain old dictionary API (like the :mod:`repoze.component` API). For example, the snippet of code in the problem section above was: @@ -226,7 +226,7 @@ some lines in the sand. .. code-block:: python :linenos: - from repoze.bfg.interfaces import ISettings + from pyramid.interfaces import ISettings from zope.component import getUtility settings = getUtility(ISettings) @@ -235,7 +235,7 @@ some lines in the sand. .. code-block:: python :linenos: - from repoze.bfg.threadlocal import get_current_registry + from pyramid.threadlocal import get_current_registry registry = get_current_registry() settings = registry['settings'] @@ -258,7 +258,7 @@ some lines in the sand. attributes and the dictionary API. Every Python programmer knows these things, even framework programmers. -While :mod:`repoze.bfg` still uses some suboptimal unnamed utility +While :mod:`pyramid` still uses some suboptimal unnamed utility registrations, future versions of it will where possible disuse these things in favor of straight dictionary assignments and lookups, as demonstrated above, to be kinder to new framework developers. We'll @@ -267,16 +267,16 @@ continue to seek ways to reduce framework developer cognitive load. Rationale +++++++++ -Here are the main rationales involved in the :mod:`repoze.bfg` +Here are the main rationales involved in the :mod:`pyramid` decision to use the ZCA registry: - Pedigree. A nontrivial part of the answer to this question is - "pedigree". Much of the design of :mod:`repoze.bfg` is stolen + "pedigree". Much of the design of :mod:`pyramid` is stolen directly from :term:`Zope`. Zope uses the ZCA registry to do a - number of tricks. :mod:`repoze.bfg` mimics these tricks, and, + number of tricks. :mod:`pyramid` mimics these tricks, and, because the ZCA registry works well for that set of tricks, - :mod:`repoze.bfg` uses it for the same purposes. For example, the - way that :mod:`repoze.bfg` maps a :term:`request` to a :term:`view + :mod:`pyramid` uses it for the same purposes. For example, the + way that :mod:`pyramid` maps a :term:`request` to a :term:`view callable` is lifted almost entirely from Zope. The ZCA registry plays an important role in the particulars of how this request to view mapping is done. @@ -290,12 +290,12 @@ decision to use the ZCA registry: :term:`interface`. - Singularity. There's only one "place" where "application - configuration" lives in a :mod:`repoze.bfg` application: in a + configuration" lives in a :mod:`pyramid` application: in a component registry. The component registry answers questions made to it by the framework at runtime based on the configuration of *an application*. Note: "an application" is not the same as "a process", multiple independently configured copies of the same - :mod:`repoze.bfg` application are capable of running in the same + :mod:`pyramid` application are capable of running in the same process space. - Composability. A ZCA component registry can be populated @@ -308,7 +308,7 @@ decision to use the ZCA registry: extensibility via a well-defined and widely understood plugin architecture. As long as framework developers and extenders understand the ZCA registry, it's possible to extend - :mod:`repoze.bfg` almost arbitrarily. For example, it's relatively + :mod:`pyramid` almost arbitrarily. For example, it's relatively easy to build a ZCML directive that registers several views "all at once", allowing app developers to use that ZCML directive as a "macro" in code that they write. This is somewhat of a @@ -321,26 +321,26 @@ decision to use the ZCA registry: lookups in the code find our mock objects. - Speed. The ZCA registry is very fast for a specific set of complex - lookup scenarios that :mod:`repoze.bfg` uses, having been optimized + lookup scenarios that :mod:`pyramid` uses, having been optimized through the years for just these purposes. The ZCA registry contains optional C code for this purpose which demonstrably has no (or very few) bugs. - Ecosystem. Many existing Zope packages can be used in - :mod:`repoze.bfg` with few (or no) changes due to our use of the ZCA + :mod:`pyramid` with few (or no) changes due to our use of the ZCA registry and :term:`ZCML`. Conclusion ++++++++++ -If you only *develop applications* using :mod:`repoze.bfg`, there's +If you only *develop applications* using :mod:`pyramid`, there's not much to complain about here. You just should never need to understand the ZCA registry or even know about its presence: use -documented :mod:`repoze.bfg` APIs instead. However, you may be an +documented :mod:`pyramid` APIs instead. However, you may be an application developer who doesn't read API documentation because it's unmanly. Instead you read the raw source code, and because you haven't read the documentation, you don't know what functions, classes, and -methods even *form* the :mod:`repoze.bfg` API. As a result, you've +methods even *form* the :mod:`pyramid` API. As a result, you've now written code that uses internals and you've pained yourself into a conceptual corner as a result of needing to wrestle with some ZCA-using implementation detail. If this is you, it's extremely hard @@ -348,9 +348,9 @@ to have a lot of sympathy for you. You'll either need to get familiar with how we're using the ZCA registry or you'll need to use only the documented APIs; that's why we document them as APIs. -If you *extend* or *develop* :mod:`repoze.bfg` (create new ZCML +If you *extend* or *develop* :mod:`pyramid` (create new ZCML directives, use some of the more obscure "ZCML hooks" as described in -:ref:`hooks_chapter`, or work on the :mod:`repoze.bfg` core code), you +:ref:`hooks_chapter`, or work on the :mod:`pyramid` core code), you will be faced with needing to understand at least some ZCA concepts. The ZCA registry API is quirky: we've tried to make it at least slightly nicer by disusing it for common registrations and lookups @@ -359,15 +359,15 @@ will be forever. We know it's quirky, but it's also useful and fundamentally understandable if you take the time to do some reading about it. -BFG Uses Interfaces Too Liberally ---------------------------------- +Pyramid Uses Interfaces Too Liberally +------------------------------------- In this `TOPP Engineering blog entry <http://www.coactivate.org/projects/topp-engineering/blog/2008/10/20/what-bothers-me-about-the-component-architecture/>`_, -Ian Bicking asserts that the way :mod:`repoze.bfg` uses a Zope +Ian Bicking asserts that the way :mod:`pyramid` uses a Zope interface to represent an HTTP request method adds too much indirection for not enough gain. We agreed in general, and for this -reason, :mod:`repoze.bfg` version 1.1 added :term:`view predicate` and +reason, :mod:`pyramid` version 1.1 added :term:`view predicate` and :term:`route predicate` modifiers to view configuration. Predicates are request-specific (or :term:`context` -specific) matching narrowers which don't use interfaces. Instead, each predicate uses a @@ -380,7 +380,7 @@ decorator which mentioned the ``request_method`` predicate: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(name='post_view', request_method='POST', renderer='json') def post_view(request): return 'POSTed' @@ -392,7 +392,7 @@ response: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(name='post_view', request_method='POST', accept='application/json', renderer='json') def post_view(request): @@ -417,7 +417,7 @@ acommodate this by allowing people to define "custom" view predicates: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view from webob import Response def subpath(context, request): @@ -432,27 +432,27 @@ The above view will only match when the first element of the request's .. _zcml_encouragement: -BFG "Encourages Use of ZCML" ----------------------------- +Pyramid "Encourages Use of ZCML" +-------------------------------- :term:`ZCML` is a configuration language that can be used to configure the :term:`Zope Component Architecture` registry that -:mod:`repoze.bfg` uses as its application configuration. +:mod:`pyramid` uses as its application configuration. Quick answer: well, it doesn't *really* encourage the use of ZCML. In -:mod:`repoze.bfg` 1.0 and 1.1, application developers could use +:mod:`pyramid` 1.0 and 1.1, application developers could use decorators for the most common form of configuration. But, yes, a -:mod:`repoze.bfg` 1.0/1.1 application needed to possess a ZCML file +:mod:`pyramid` 1.0/1.1 application needed to possess a ZCML file for it to begin executing successfully even if its only contents were a ``<scan>`` directive that kicked off a scan to find decorated view callables. In the interest of completeness and in the spirit of providing a -lowest common denominator, :mod:`repoze.bfg` 1.2 includes a completely +lowest common denominator, :mod:`pyramid` 1.2 includes a completely imperative mode for all configuration. You will be able to make "single file" apps in this mode, which should help people who need to see everything done completely imperatively. For example, the very -most basic :mod:`repoze.bfg` "helloworld" program has become +most basic :mod:`pyramid` "helloworld" program has become something like: .. code-block:: python @@ -460,7 +460,7 @@ something like: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def hello_world(request): return Response('Hello world!') @@ -477,11 +477,11 @@ In this mode, no ZCML is required for end users. Hopefully this mode will allow people who are used to doing everything imperatively feel more comfortable. -BFG Uses ZCML; ZCML is XML and I Don't Like XML ------------------------------------------------ +Pyramid Uses ZCML; ZCML is XML and I Don't Like XML +--------------------------------------------------- :term:`ZCML` is a configuration language in the XML syntax. Due to -the "imperative configuration" feature (new in :mod:`repoze.bfg` 1.2), +the "imperative configuration" feature (new in :mod:`pyramid` 1.2), you don't need to use ZCML at all if you start a project from scratch. But if you really do want to perform declarative configuration, perhaps because you want to build an extensible application, you will @@ -501,20 +501,20 @@ called *declarations*. For an example: This declaration associates a :term:`view` with a route pattern. -All :mod:`repoze.bfg` declarations are singleton tags, unlike many +All :mod:`pyramid` declarations are singleton tags, unlike many other XML configuration systems. No XML *values* in ZCML are meaningful; it's always just XML tags and attributes. So in the very common case it's not really very much different than an otherwise "flat" configuration format like ``.ini``, except a developer can *create* a directive that requires nesting (none of these exist in -:mod:`repoze.bfg` itself), and multiple "sections" can exist with the +:mod:`pyramid` itself), and multiple "sections" can exist with the same "name" (e.g. two ``<route>`` declarations) must be able to exist simultaneously. You might think some other configuration file format would be better. But all configuration formats suck in one way or another. I personally don't think any of our lives would be markedly better if -the declarative configuration format used by :mod:`repoze.bfg` were +the declarative configuration format used by :mod:`pyramid` were YAML, JSON, or INI. It's all just plumbing that you mostly cut and paste once you've progressed 30 minutes into your first project. Folks who tend to agitate for another configuration file format are @@ -522,13 +522,13 @@ folks that haven't yet spent that 30 minutes. .. _model_traversal_confusion: -BFG Uses "Model" To Represent A Node In The Graph of Objects Traversed ----------------------------------------------------------------------- +Pyramid Uses "Model" To Represent A Node In The Graph of Objects Traversed +-------------------------------------------------------------------------- -The :mod:`repoze.bfg` documentation refers to the graph being +The :mod:`pyramid` documentation refers to the graph being traversed when :term:`traversal` is used as a "model graph". Some of -the :mod:`repoze.bfg` APIs also use the word "model" in them when -referring to a node in this graph (e.g. ``repoze.bfg.url.model_url``). +the :mod:`pyramid` APIs also use the word "model" in them when +referring to a node in this graph (e.g. ``pyramid.url.model_url``). A terminology overlap confuses people who write applications that always use ORM packages such as SQLAlchemy, which has a different @@ -539,62 +539,30 @@ Often model objects must be explicitly manufactured by an ORM as a result of some query performed by a :term:`view`. As a result, it can be unnatural to think of the nodes traversed as "model" objects if you develop your application using traversal and a relational database. -When you develop such applications, the things that :mod:`repoze.bfg` +When you develop such applications, the things that :mod:`pyramid` refers to as "models" in such an application may just be stand-ins that perform a query and generate some wrapper *for* an ORM "model" (or set of ORM models). The graph *might* be composed completely of "model" objects (as defined by the ORM) but it also might not be. The naming impedance mismatch between the way the term "model" is used -to refer to a node in a graph in :mod:`repoze.bfg` and the way the +to refer to a node in a graph in :mod:`pyramid` and the way the term "model" is used by packages like SQLAlchemy is unfortunate. For the purpose of avoiding confusion, if we had it to do all over again, -we might refer to the graph that :mod:`repoze.bfg` traverses a "node +we might refer to the graph that :mod:`pyramid` traverses a "node graph" or "object graph" rather than a "model graph", but since we've baked the name into the API, it's a little late. Sorry. -In our defense, many :mod:`repoze.bfg` applications (especially ones +In our defense, many :mod:`pyramid` applications (especially ones which use :term:`ZODB`) do indeed traverse a graph full of model nodes. Each node in the graph is a separate persistent object that is stored within a database. This was the use case considered when coming up with the "model" terminology. -I Can't Figure Out How "BFG" Is Related to "Repoze" ---------------------------------------------------- +Pyramid Does Traversal, And I Don't Like Traversal +-------------------------------------------------- -When the `Repoze project <http://repoze.org>`_ was first started, -:mod:`repoze.bfg` did not exist. The `website <http://repoze.org>`_ -for the project had (and still has, of this writing) a tag line of -"Plumbing Zope into the WSGI Pipeline", and contained descriptions of -:term:`WSGI` middleware that were inspired by Zope features, and -applications that help :term:`Zope` to run within a WSGI environment. -The original intent was to create a "namespace" of packages -("repoze.*") that contained software that formed a decomposition of -Zope features into more WSGI-friendly components. It was never the -intention of the Repoze project to actually create another web -framework. - -However, as time progressed, the folks who ran the Repoze project -decided to create :mod:`repoze.bfg`, which *is* a web framework. Due -to an early naming mistake, the software composing the framework was -named :mod:`repoze.bfg`. This mistake was not corrected before the -software garnered a significant user base, and in the interest of -backwards compatibility, most likely never will be. While -:mod:`repoze.bfg` uses Zope technology, it is otherwise unrelated to -the original goals of "Repoze" as stated on the repoze.org website. -If we had it to do all over again, the :mod:`repoze.bfg` package would -be named simply :mod:`bfg`. But we don't have it to do all over -again. - -At this point, therefore, the name "Repoze" should be considered -basically just a "brand". Its presence in the name of a package means -nothing except that it has an origin as a piece of software developed -by a member of the Repoze community. - -BFG Does Traversal, And I Don't Like Traversal ----------------------------------------------- - -In :mod:`repoze.bfg`, :term:`traversal` is the act of resolving a URL +In :mod:`pyramid`, :term:`traversal` is the act of resolving a URL path to a :term:`model` object in an object graph. Some people are uncomfortable with this notion, and believe it is wrong. @@ -624,15 +592,15 @@ excellent way to model this, even if the backend is a relational database. In this situation, the graph being traversed is actually less a "model graph" than a site structure. -But the point is ultimately moot. If you use :mod:`repoze.bfg`, and +But the point is ultimately moot. If you use :mod:`pyramid`, and you don't want to model your application in terms of traversal, you needn't use it at all. Instead, use :term:`URL dispatch` to map URL paths to views. -BFG Does URL Dispatch, And I Don't Like URL Dispatch ----------------------------------------------------- +Pyramid Does URL Dispatch, And I Don't Like URL Dispatch +-------------------------------------------------------- -In :mod:`repoze.bfg`, :term:`url dispatch` is the act of resolving a +In :mod:`pyramid`, :term:`url dispatch` is the act of resolving a URL path to a :term:`view` callable by performing pattern matching against some set of ordered route definitions. The route definitions are examined in order: the first pattern which matches is used to @@ -650,7 +618,7 @@ object graph), and traversal is required to reach this code. I'll argue that URL dispatch is ultimately useful, even if you want to use traversal as well. You can actually *combine* URL dispatch and -traversal in :mod:`repoze.bfg` (see :ref:`hybrid_chapter`). One +traversal in :mod:`pyramid` (see :ref:`hybrid_chapter`). One example of such a usage: if you want to emulate something like Zope 2's "Zope Management Interface" UI on top of your object graph (or any administrative interface), you can register a route like ``<route @@ -671,16 +639,16 @@ one-off associations between views and URL paths. Sometimes it's just pointless to add a node to the object graph that effectively represents the entry point for some bit of code. You can just use a route and be done with it. If a route matches, a view associated with -the route will be called; if no route matches, :mod:`repoze.bfg` falls +the route will be called; if no route matches, :mod:`pyramid` falls back to using traversal. -But the point is ultimately moot. If you use :mod:`repoze.bfg`, and +But the point is ultimately moot. If you use :mod:`pyramid`, and you really don't want to use URL dispatch, you needn't use it at all. Instead, use :term:`traversal` exclusively to map URL paths to views, just like you do in :term:`Zope`. -BFG Views Do Not Accept Arbitrary Keyword Arguments ---------------------------------------------------- +Pyramid Views Do Not Accept Arbitrary Keyword Arguments +------------------------------------------------------- Many web frameworks (Zope, TurboGears, Pylons, Django) allow for their variant of a :term:`view callable` to accept arbitrary keyword or @@ -716,11 +684,11 @@ arguments in the request, and the method is called (if possible) with its argument list filled with values mentioned therein. TurboGears and Pylons operate similarly. -:mod:`repoze.bfg` has neither of these features. :mod:`repoze.bfg` +:mod:`pyramid` has neither of these features. :mod:`pyramid` view callables always accept only ``context`` and ``request`` (or just ``request``), and no other arguments. The rationale: this argument specification matching done aggressively can be costly, and -:mod:`repoze.bfg` has performance as one of its main goals, so we've +:mod:`pyramid` has performance as one of its main goals, so we've decided to make people obtain information by interrogating the request object for it in the view body instead of providing magic to do unpacking into the view argument list. The feature itself also just @@ -739,15 +707,15 @@ A similar feature could be implemented to provide the Django-like behavior as a decorator by wrapping the view with a decorator that looks in ``request.matchdict``. -It's possible at some point that :mod:`repoze.bfg` will grow some form +It's possible at some point that :mod:`pyramid` will grow some form of argument matching feature (it would be simple to make it an always-on optional feature that has no cost unless you actually use it) for, but currently it has none. -BFG Provides Too Few "Rails" ----------------------------- +Pyramid Provides Too Few "Rails" +-------------------------------- -By design, :mod:`repoze.bfg` is not a particularly "opinionated" web +By design, :mod:`pyramid` is not a particularly "opinionated" web framework. It has a relatively parsimonious feature set. It contains no built in ORM nor any particular database bindings. It contains no form generation framework. It does not contain a sessioning library. @@ -755,14 +723,14 @@ It has no administrative web user interface. It has no built in text indexing. It does not dictate how you arrange your code. Such opinionated functionality exists in applications and frameworks -built *on top* of :mod:`repoze.bfg`. It's intended that higher-level -systems emerge built using :mod:`repoze.bfg` as a base. See also +built *on top* of :mod:`pyramid`. It's intended that higher-level +systems emerge built using :mod:`pyramid` as a base. See also :ref:`apps_are_extensible`. -BFG Provides Too Many "Rails" ------------------------------ +Pyramid Provides Too Many "Rails" +--------------------------------- -:mod:`repoze.bfg` provides some features that other web frameworks do +:mod:`pyramid` provides some features that other web frameworks do not. Most notably it has machinery which resolves a URL first to a :term:`context` before calling a view (which has the capability to accept the context in its argument list), and a declarative @@ -779,20 +747,20 @@ declarations as :term:`ACL` objects. Having context-sensitive declarative security for individual objects in the object graph is simply required for this class of application. Other frameworks save for Zope just do not have this feature. This is -one of the primary reasons that :mod:`repoze.bfg` was actually +one of the primary reasons that :mod:`pyramid` was actually written. If you don't like this, it doesn't mean you can't use -:mod:`repoze.bfg`. Just ignore this feature and avoid configuring an +:mod:`pyramid`. Just ignore this feature and avoid configuring an authorization or authentication policy and using ACLs. You can build -"Pylons-style" applications using :mod:`repoze.bfg` that use their own +"Pylons-style" applications using :mod:`pyramid` that use their own security model via decorators or plain-old-imperative logic in view code. -BFG Is Too Big --------------- +Pyramid Is Too Big +------------------ -"The :mod:`repoze.bfg` compressed tarball is 1MB. It must be +"The :mod:`pyramid` compressed tarball is 1MB. It must be enormous!" No. We just ship it with test code and helper templates. Here's a @@ -814,7 +782,7 @@ repoze/bfg (except for ``repoze/bfg/tests and repoze/bfg/paster_templates``) 316K -The actual :mod:`repoze.bfg` runtime code is about 10% of the total +The actual :mod:`pyramid` runtime code is about 10% of the total size of the tarball omitting docs, helper templates used for package generation, and test code. Of the approximately 13K lines of Python code in the package, the code that actually has a chance of executing @@ -823,17 +791,17 @@ files, accounts for approximately 3K lines of Python code. This is comparable to Pylons, which ships with a little over 2K lines of Python code, excluding tests. -BFG Has Too Many Dependencies ------------------------------ +Pyramid Has Too Many Dependencies +--------------------------------- This is true. At the time of this writing, the total number of Python -package distributions that :mod:`repoze.bfg` depends upon transitively +package distributions that :mod:`pyramid` depends upon transitively is 14 if you use Python 2.6 or 2.7, or 16 if you use Python 2.4 or 2.5. This is a lot more than zero package distribution dependencies: a metric which various Python microframeworks and Django boast. The :mod:`zope.component` and :mod:`zope.configuration` packages on -which :mod:`repoze.bfg` depends have transitive dependencies on +which :mod:`pyramid` depends have transitive dependencies on several other packages (:mod:`zope.schema`, :mod:`zope.i18n`, :mod:`zope.event`, :mod:`zope.interface`, :mod:`zope.deprecation`, :mod:`zope.i18nmessageid`). We've been working with the Zope @@ -842,16 +810,16 @@ We'd prefer that these packages have fewer packages as transitive dependencies, and that much of the functionality of these packages was moved into a smaller *number* of packages. -:mod:`repoze.bfg` also has its own direct dependencies, such as +:mod:`pyramid` also has its own direct dependencies, such as :term:`Paste`, :term:`Chameleon`, and :term:`WebOb`, and some of these in turn have their own transitive dependencies. -It should be noted that :mod:`repoze.bfg` is positively lithe compared +It should be noted that :mod:`pyramid` is positively lithe compared to :term:`Grok`, a different Zope-based framework. As of this writing, in its default configuration, Grok has 126 package distribution dependencies. The number of dependencies required by -:mod:`repoze.bfg` is many times fewer than Grok (or Zope itself, upon -which Grok is based). :mod:`repoze.bfg` has a number of package +:mod:`pyramid` is many times fewer than Grok (or Zope itself, upon +which Grok is based). :mod:`pyramid` has a number of package distribution dependencies comparable to similarly-targeted frameworks such as Pylons. @@ -859,31 +827,31 @@ We try not to reinvent too many wheels (at least the ones that don't need reinventing), and this comes at the cost of some number of dependencies. However, "number of package distributions" is just not a terribly great metric to measure complexity. For example, the -:mod:`zope.event` distribution on which :mod:`repoze.bfg` depends has +:mod:`zope.event` distribution on which :mod:`pyramid` depends has a grand total of four lines of runtime code. As noted above, we're continually trying to agitate for a collapsing of these sorts of packages into fewer distribution files. -BFG "Cheats" To Obtain Speed ----------------------------- +Pyramid "Cheats" To Obtain Speed +-------------------------------- Complaints have been lodged by other web framework authors at various -times that :mod:`repoze.bfg` "cheats" to gain performance. One +times that :mod:`pyramid` "cheats" to gain performance. One claimed cheating mechanism is our use (transitively) of the C extensions provided by :mod:`zope.interface` to do fast lookups. Another claimed cheating mechanism is the religious avoidance of extraneous function calls. If there's such a thing as cheating to get better performance, we want -to cheat as much as possible. We optimize :mod:`repoze.bfg` +to cheat as much as possible. We optimize :mod:`pyramid` aggressively. This comes at a cost: the core code has sections that could be expressed more readably. As an amelioration, we've commented these sections liberally. -BFG Gets Its Terminology Wrong ("MVC") --------------------------------------- +Pyramid Gets Its Terminology Wrong ("MVC") +------------------------------------------ -"I'm a MVC web framework user, and I'm confused. :mod:`repoze.bfg` +"I'm a MVC web framework user, and I'm confused. :mod:`pyramid` calls the controller a view! And it doesn't have any controllers." People very much want to give web applications the same properties as @@ -949,14 +917,14 @@ reasonable model, given the current constraints of the web. .. _apps_are_extensible: -BFG Applications are Extensible; I Don't Believe In Application Extensibility ------------------------------------------------------------------------------ +Pyramid Applications are Extensible; I Don't Believe In Application Extensibility +--------------------------------------------------------------------------------- -Any :mod:`repoze.bfg` application written obeying certain constraints -is *extensible*. This feature is discussed in the :mod:`repoze.bfg` +Any :mod:`pyramid` application written obeying certain constraints +is *extensible*. This feature is discussed in the :mod:`pyramid` documentation chapter named :ref:`extending_chapter`. It is made possible by the use of the :term:`Zope Component Architecture` and -:term:`ZCML` within :mod:`repoze.bfg`. +:term:`ZCML` within :mod:`pyramid`. "Extensible", in this context, means: @@ -998,7 +966,7 @@ lifetime of a deployment can be difficult and time consuming, and it's often useful to be able to modify an application for a particular deployment in a less invasive way. -If you don't want to think about :mod:`repoze.bfg` application +If you don't want to think about :mod:`pyramid` application extensibility at all, you needn't. You can ignore extensibility entirely. However, if you follow the set of rules defined in :ref:`extending_chapter`, you don't need to *make* your application @@ -1043,23 +1011,23 @@ worth, be contained in one, canonical, well-defined place. Branching an application and continually merging in order to get new features and bugfixes is clearly useful. You can do that with a -:mod:`repoze.bfg` application just as usefully as you can do it with +:mod:`pyramid` application just as usefully as you can do it with any application. But deployment of an application written in -:mod:`repoze.bfg` makes it possible to avoid the need for this even if +:mod:`pyramid` makes it possible to avoid the need for this even if the application doesn't define any plugpoints ahead of time. It's possible that promoters of competing web frameworks dismiss this feature in favor of branching and merging because applications written in their framework of choice aren't extensible out of the box in a comparably fundamental way. -While :mod:`repoze.bfg` application are fundamentally extensible even +While :mod:`pyramid` application are fundamentally extensible even if you don't write them with specific extensibility in mind, if you're moderately adventurous, you can also take it a step further. If you learn more about the :term:`Zope Component Architecture`, you can optionally use it to expose other more domain-specific configuration plugpoints while developing an application. The plugpoints you expose needn't be as coarse as the ones provided automatically by -:mod:`repoze.bfg` itself. For example, you might compose your own +:mod:`pyramid` itself. For example, you might compose your own :term:`ZCML` directive that configures a set of views for a prebaked purpose (e.g. ``restview`` or somesuch) , allowing other people to refer to that directive when they make declarations in the @@ -1069,85 +1037,22 @@ plugpoints for its deployers will need to understand the ZCA or he will need to develop his own similar extensibility system. Ultimately, any argument about whether the extensibility features lent -to applications by :mod:`repoze.bfg` are "good" or "bad" is somewhat +to applications by :mod:`pyramid` are "good" or "bad" is somewhat pointless. You needn't take advantage of the extensibility features -provided by a particular :mod:`repoze.bfg` application in order to +provided by a particular :mod:`pyramid` application in order to affect a modification for a particular set of its deployments. You can ignore the application's extensibility plugpoints entirely, and instead use version control branching and merging to manage application deployment modifications instead, as if you were deploying an application written using any other web framework. -The Name BFG Is Not Safe For Work ---------------------------------- - -"Big Friendly Giant" is not safe for your work? Where do you work? ;-) - -The BFG API Isn't "Flat" ------------------------- - -The :mod:`repoze.bfg` API is organized in such a way that API imports -must come from submodules of the ``repoze.bfg`` namespace. For -instance: - -.. code-block:: python - :linenos: - - from repoze.bfg.settings import get_settings - from repoze.bfg.url import model_url - -Some folks understandably don't want to think about the submodule -organization, and would rather be able to do: - -.. ignore-next-block -.. code-block:: python - :linenos: - - from repoze.bfg import get_settings - from repoze.bfg import model_url - -This would indeed be nice. However, the ``repoze.bfg`` Python package -is a `namespace package <http://www.python.org/dev/peps/pep-0382/>`_. -The ``__init__.py`` of a namespace package cannot contain any -meaningful code such as imports from submodules which would let us -form a flatter API. Sorry. - -Though it makes the API slightly "thinkier", making the ``repoze.bfg`` -package into a namespace package was an early design decision, which -we believe has paid off. The primary goal is to make it possible to -move features *out* of the core ``repoze.bfg`` distribution and into -add-on distributions without breaking existing imports. The -``repoze.bfg.lxml`` distribution is an example of such a package: this -functionality used to live in the core distribution, but we later -decided that a core dependency on ``lxml`` was unacceptable. Because -``repoze.bfg`` is a namespace package, we were able to remove the -``repoze.bfg.lxml`` module from the core and create a distribution -named ``repoze.bfg.lxml`` which contains an eponymous package. We -were then able, via our changelog, to inform people that might have -been depending on the feature that although it no longer shipped in -the core distribution, they could get it back *without changing any -code* by adding an ``install_requires`` line to their application -package's ``setup.py``. - -Often new :mod:`repoze.bfg` features are released as add-on packages -in the ``repoze.bfg`` namespace. Because ``repoze.bfg`` is a -namespace package, if we want to move one of these features *in* to -the core distribition at some point, we can do so without breaking -code which imports from the older package namespace. This is -currently less useful than the ability to move features *out* of the -core distribution, as :mod:`setuptools` does not yet have any concept -of "obsoletes" metadata which we could add to the core distribution. -This means it's not yet possible to declaratively deprecate the older -non-core package in the eyes of tools like ``easy_install``, ``pip`` -and ``buildout``. - -Zope 3 Enforces "TTW" Authorization Checks By Default; BFG Does Not -------------------------------------------------------------------- +Zope 3 Enforces "TTW" Authorization Checks By Default; Pyramid Does Not +----------------------------------------------------------------------- Challenge +++++++++ -:mod:`repoze.bfg` performs automatic authorization checks only at +:mod:`pyramid` performs automatic authorization checks only at :term:`view` execution time. Zope 3 wraps context objects with a `security proxy <http://wiki.zope.org/zope3/WhatAreSecurityProxies>`, which causes Zope 3 to do also security checks during attribute @@ -1160,17 +1065,17 @@ access. I like this, because it means: respect to a context object. #) I want to also expose my model via a REST API using Twisted Web. If - If BFG perform authorization based on attribute access via Zope3's + If Pyramid performed authorization based on attribute access via Zope3's security proies, I could enforce my authorization policy in both - :mod:`repoze.bfg` and in the Twisted-based system the same way. + :mod:`pyramid` and in the Twisted-based system the same way. Defense +++++++ -:mod:`repoze.bfg` was developed by folks familiar with Zope 2, which +:mod:`pyramid` was developed by folks familiar with Zope 2, which has a "through the web" security model. This "TTW" security model was the precursor to Zope 3's security proxies. Over time, as the -:mod:`repoze.bfg` developers (working in Zope 2) created such sites, +:mod:`pyramid` developers (working in Zope 2) created such sites, we found authorization checks during code interpretation extremely useful in a minority of projects. But much of the time, TTW authorization checks usually slowed down the development velocity of @@ -1191,7 +1096,7 @@ notwithstanding, given that Zope 3 security proxies are "viral" by nature, the only requirement to use one is to make sure you wrap a single object in a security proxy and make sure to access that object normally when you want proxy security checks to happen. It is -possible to override the :mod:`repoze.bfg` "traverser" for a given +possible to override the :mod:`pyramid` "traverser" for a given application (see :ref:`changing_the_traverser`). To get Zope3-like behavior, it is possible to plug in a different traverser which returns Zope3-security-proxy-wrapped objects for each traversed object @@ -1210,24 +1115,24 @@ two that are becoming popular. `Bobo <http://bobo.digicool.com/>`_ doesn't describe itself as a microframework, but its intended userbase is much the same. Many others exist. We've actually even (only as a teaching tool, not as any sort of official project) `created one using -BFG <http://bfg.repoze.org/videos#groundhog1>`_. Microframeworks are -small frameworks with one common feature: each allows its users to -create a fully functional application that lives in a single Python -file. - -Some developers and microframework authors point out that BFG's "hello -world" single-file program is longer (by about five lines) than the -equivalent program in their favorite microframework. Guilty as -charged; in a contest of "whose is shortest", BFG indeed loses. - -This loss isn't for lack of trying. BFG aims to be useful in the same -circumstance in which microframeworks claim dominance: single-file -applications. But BFG doesn't sacrifice its ability to credibly -support larger applications in order to achieve hello-world LoC parity -with the current crop of microframeworks. BFG's design instead tries -to avoid some common pitfalls associated with naive declarative -configuration schemes. The subsections which follow explain the -rationale. +BFG <http://bfg.repoze.org/videos#groundhog1>`_ (the precursor to +Pyramid). Microframeworks are small frameworks with one common +feature: each allows its users to create a fully functional +application that lives in a single Python file. + +Some developers and microframework authors point out that Pyramid's +"hello world" single-file program is longer (by about five lines) than +the equivalent program in their favorite microframework. Guilty as +charged; in a contest of "whose is shortest", Pyramid indeed loses. + +This loss isn't for lack of trying. Pyramid aims to be useful in the +same circumstance in which microframeworks claim dominance: +single-file applications. But Pyramid doesn't sacrifice its ability +to credibly support larger applications in order to achieve +hello-world LoC parity with the current crop of microframeworks. +Pyramid's design instead tries to avoid some common pitfalls +associated with naive declarative configuration schemes. The +subsections which follow explain the rationale. .. _you_dont_own_modulescope: @@ -1459,29 +1364,29 @@ almost-all-imperative: gh.add_route(foo, '/foo/') gh.run() -This is a generic mode of operation that is encouraged in the BFG +This is a generic mode of operation that is encouraged in the Pyramid documentation. Some existing microframeworks (Flask, in particular) -allow for it as well. None (other than BFG) *encourage* it. If you -never expect your application to grow beyond two or three or four or -ten modules, it probably doesn't matter very much which mode you use. -If your application grows large, however, imperative configuration can -provide better predictability. +allow for it as well. None (other than Pyramid) *encourage* it. If +you never expect your application to grow beyond two or three or four +or ten modules, it probably doesn't matter very much which mode you +use. If your application grows large, however, imperative +configuration can provide better predictability. .. note:: - Astute readers may notice that BFG has configuration decorators too. - Aha! Don't these decorators have the same problems? No. These - decorators do not populate an external Python module when they are - executed. They only mutate the functions (and classes and methods) - they're attached to. These mutations must later be found during a - "scan" process that has a predictable and structured import phase. - Module-localized mutation is actually the best-case circumstance for - double-imports; if a module only mutates itself and its contents at - import time, if it is imported twice, that's OK, because each - decorator invocation will always be mutating an independent copy of - the object its attached to, not a shared resource like a registry in - another module. This has the effect that double-registrations will - never be performed. + Astute readers may notice that Pyramid has configuration decorators + too. Aha! Don't these decorators have the same problems? No. + These decorators do not populate an external Python module when they + are executed. They only mutate the functions (and classes and + methods) they're attached to. These mutations must later be found + during a "scan" process that has a predictable and structured import + phase. Module-localized mutation is actually the best-case + circumstance for double-imports; if a module only mutates itself and + its contents at import time, if it is imported twice, that's OK, + because each decorator invocation will always be mutating an + independent copy of the object its attached to, not a shared + resource like a registry in another module. This has the effect + that double-registrations will never be performed. Routes (Usually) Need Relative Ordering +++++++++++++++++++++++++++++++++++++++ @@ -1637,15 +1542,16 @@ myframework.threadlocals import get_request; request = get_request()`` even though the latter is more explicit. It would be *most* explicit if the microframeworks did not use thread -local variables at all. BFG view functions are passed a request -object; many of BFG's APIs require that an explicit request object be -passed to them. It is *possible* to retrieve the current BFG request -as a threadlocal variable but it is a "in case of emergency, break -glass" type of activity. This explicitness makes BFG view functions -more easily unit testable, as you don't need to rely on the framework -to manufacture suitable "dummy" request (and other similarly-scoped) -objects during test setup. It also makes them more likely to work on -arbitrary systems, such as async servers that do no monkeypatching. +local variables at all. Pyramid view functions are passed a request +object; many of Pyramid's APIs require that an explicit request object +be passed to them. It is *possible* to retrieve the current Pyramid +request as a threadlocal variable but it is a "in case of emergency, +break glass" type of activity. This explicitness makes Pyramid view +functions more easily unit testable, as you don't need to rely on the +framework to manufacture suitable "dummy" request (and other +similarly-scoped) objects during test setup. It also makes them more +likely to work on arbitrary systems, such as async servers that do no +monkeypatching. Explicitly WSGI +++++++++++++++ @@ -1653,10 +1559,10 @@ Explicitly WSGI Some microframeworks offer a ``run()`` method of an application object that executes a default server configuration for easy execution. -BFG doesn't currently try to hide the fact that its router is a WSGI -application behind a convenience ``run()`` API. It just tells people -to import a WSGI server and use it to serve up their BFG application -as per the documentation of that WSGI server. +Pyramid doesn't currently try to hide the fact that its router is a +WSGI application behind a convenience ``run()`` API. It just tells +people to import a WSGI server and use it to serve up their Pyramid +application as per the documentation of that WSGI server. The extra lines saved by abstracting away the serving step behind ``run()`` seem to have driven dubious second-order decisions related @@ -1686,20 +1592,12 @@ can interface with a WSGI application is placed on the server developer, not the web framework developer, making it more likely to be timely and correct. -All of the above said, BFG version 1.3 may offer a ``run()`` - like -shortcut serving API which executes a WSGI server. But I might also -chicken out and not add it: I'd rather not deal with needing to supply -support answers like `this one -<http://twitter.com/bottlepy/status/20451760706>`_. If I add such a -method, it will likely be named less attractively to indicate it is -only a shortcut. - -:meth:`repoze.bfg.configuration.Configurator.begin` and :meth:`repoze.bfg.configuration.Configurator.end` methods +:meth:`pyramid.configuration.Configurator.begin` and :meth:`pyramid.configuration.Configurator.end` methods +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -The methods :meth:`repoze.bfg.configuration.Configurator.begin` and -:meth:`repoze.bfg.configuration.Configurator.end` are used to bracket -the configuration phase of a :mod:`repoze.bfg` application. +The methods :meth:`pyramid.configuration.Configurator.begin` and +:meth:`pyramid.configuration.Configurator.end` are used to bracket +the configuration phase of a :mod:`pyramid` application. These exist because existing legacy third party *configuration* (not runtime) code relies on a threadlocal stack being populated. The @@ -1707,13 +1605,13 @@ runtime) code relies on a threadlocal stack being populated. The method pops it back off. For the simplest applications, these lines are actually not required. -I *could* omit them from every BFG hello world app without ill effect. -However, when users use certain configuration methods (ones not -represented in the hello world app), calling code will begin to fail -when it is not bracketed between a ``begin()`` and an ``end()``. It -is just easier to tell users that this bracketing is required than to -try to explain to them which circumstances it is actually required and -which it is not, because the explanation is often torturous. +I *could* omit them from every Pyramid hello world app without ill +effect. However, when users use certain configuration methods (ones +not represented in the hello world app), calling code will begin to +fail when it is not bracketed between a ``begin()`` and an ``end()``. +It is just easier to tell users that this bracketing is required than +to try to explain to them which circumstances it is actually required +and which it is not, because the explanation is often torturous. The effectively-required execution of these two methods is a wholly bogus artifact of an early bad design decision which encouraged @@ -1728,7 +1626,7 @@ removed from the documenation. Wrapping Up +++++++++++ -Here's a diagrammed version of the simplest repoze.bfg application, +Here's a diagrammed version of the simplest pyramid application, where comments take into account what we've discussed in the :ref:`microframeworks_smaller_hello_world` section. @@ -1742,7 +1640,7 @@ where comments take into account what we've discussed in the return Response('Hello world!') if __name__ == '__main__': - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator() # no global application object. config.begin() # bogus, but required. config.add_view(hello_world) # explicit non-decorator registration diff --git a/docs/glossary.rst b/docs/glossary.rst index 5aa6c15de..dfc40c407 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -400,7 +400,7 @@ Glossary A list of element "left over" after the :term:`router` has performed a successful traversal to a view. The subpath is a sequence of strings, e.g. ``['left', 'over', 'names']``. Within - BFG applications that use URL dispatch rather than traversal, you + Pyramid applications that use URL dispatch rather than traversal, you can use ``*subpath`` in the route pattern to influence the subpath. See :ref:`star_subpath` for more information. diff --git a/docs/index.rst b/docs/index.rst index 5aa2e8b99..3b5d204cc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,13 @@ .. _index: -======================================== -The repoze.bfg Web Application Framework -======================================== +================================================= +The pyramid Web Application Development Framework +================================================= -:mod:`repoze.bfg` is a small, fast, down-to-earth Python web -application framework. It is developed as part of the `Repoze -<http://repoze.org>`_ project by `Agendaless Consulting -<http://agendaless.com>`_ and other contributors. It is licensed -under a `BSD-like license <http://repoze.org/license.html>`_. +:mod:`pyramid` is a small, fast, down-to-earth Python web application +development framework. It is developed as part of the `Pylons +<http://pylonshq.com>`_ project. It is licensed under a `BSD-like +license <http://repoze.org/license.html>`_. Front Matter ============ @@ -19,21 +18,11 @@ Front Matter copyright.rst conventions.rst -"What's New" Documents -====================== - -.. toctree:: - :maxdepth: 2 - - whatsnew-1.3 - whatsnew-1.2 - whatsnew-1.1 - Narrative documentation ======================= Narrative documentation in chapter form explaining how to use -:mod:`repoze.bfg`. +:mod:`pyramid`. .. toctree:: :maxdepth: 2 @@ -69,15 +58,15 @@ Narrative documentation in chapter form explaining how to use Tutorials ========= -Detailed tutorials explaining how to use :mod:`repoze.bfg` to build -various types of applications and how to deploy :mod:`repoze.bfg` +Detailed tutorials explaining how to use :mod:`pyramid` to build +various types of applications and how to deploy :mod:`pyramid` applications to various platforms. .. toctree:: :maxdepth: 2 - tutorials/bfgwiki/index.rst - tutorials/bfgwiki2/index.rst + tutorials/wiki/index.rst + tutorials/wiki2/index.rst tutorials/cmf/index.rst tutorials/gae/index.rst tutorials/modwsgi/index.rst @@ -89,7 +78,7 @@ Reference Material ================== Reference material includes API documentation and documentation of -every :mod:`repoze.bfg` :term:`ZCML directive`. +every :mod:`pyramid` :term:`ZCML directive`. .. toctree:: :maxdepth: 2 @@ -116,6 +105,12 @@ Design Documentation Sample Applications =================== +.. warning:: + + These applications are for an older version of :mod:`pyramid`, + which was named :mod:`repoze.bfg`. We'll be updating them soon to + use :mod:`pyramid`. + `repoze.cluegun <http://svn.repoze.org/repoze.cluegun/trunk/>`_ is a simple pastebin application based on Rocky Burt's `ClueBin <http://pypi.python.org/pypi/ClueBin/0.2.3>`_. It demonstrates form @@ -162,25 +157,25 @@ commenting, and file uploads. See the `KARL site Support and Development ======================= -The `BFG web site <http://bfg.repoze.org>`_ is the main online source -of :mod:`repoze.bfg` support and development information. +The `Pyramid web site <http://pylonshq.com/pyramid>`_ is the main +online source of :mod:`pyramid` support and development information. -To report bugs, use the `bug tracker <http://bfg.repoze.org/trac>`_. +To report bugs, use the `issue tracker +<http://github.com/Pylons/pyramid/issues>`_. If you've got questions that aren't answered by this documentation, -contact the `Repoze-dev maillist -<http://lists.repoze.org/listinfo/repoze-dev>`_ or join the `#repoze -IRC channel <irc://irc.freenode.net/#repoze>`_. +contact the `Pylons-discuss maillist +<http://groups.google.com/group/pylons-discuss>`_ or join the `#pylons +IRC channel <irc://irc.freenode.net/#pylons>`_. -Browse and check out tagged and trunk versions of :mod:`repoze.bfg` -via the `Repoze Subversion repository -<http://svn.repoze.org/repoze.bfg/>`_. To check out the trunk -via Subversion, use this command:: +Browse and check out tagged and trunk versions of :mod:`pyramid` via +the `Pyramid GitHub repository <http://github.com/Pylons/pyramid/>`_. +To check out the trunk via ``git``, use this command:: - svn co http://svn.repoze.org/repoze.bfg/trunk repoze.bfg + git clone git@github.com:Pylons/pyramid.git -To find out how to become a contributor to :mod:`repoze.bfg`, please -see the `contributor's page <http://repoze.org/contributing.html>`_. +To find out how to become a contributor to :mod:`pyramid`, please see +the `contributor's page <http://repoze.org/contributing.html>`_. Index and Glossary ================== diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 917e09bba..2bc052e7e 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,7 +1,7 @@ .. _latexindex: @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :mod:`repoze.bfg` Web Application Framework +The :mod:`pyramid` Web Application Framework @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ .. frontmatter:: @@ -63,8 +63,8 @@ Tutorials .. toctree:: :maxdepth: 1 - tutorials/bfgwiki/index.rst - tutorials/bfgwiki2/index.rst + tutorials/wiki/index.rst + tutorials/wiki2/index.rst tutorials/gae/index.rst tutorials/modwsgi/index.rst tutorials/zeo/index.rst diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst index e81cf8192..a7f9d1e82 100644 --- a/docs/tutorials/wiki/background.rst +++ b/docs/tutorials/wiki/background.rst @@ -13,6 +13,6 @@ To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD variant, etc) *or* he will need a Windows system of any kind. -This tutorial targets :mod:`pyramid` version 1.3. +This tutorial targets :mod:`pyramid` version 1.0. Have fun! diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst deleted file mode 100644 index e9f975373..000000000 --- a/docs/whatsnew-1.1.rst +++ /dev/null @@ -1,802 +0,0 @@ -What's New In :mod:`repoze.bfg` 1.1 -=================================== - -This article explains the new features in :mod:`repoze.bfg` version -1.1 as compared to the previous 1.0 release. It also documents -backwards incompatibilities between the two versions and deprecations -added to 1.1, as well as software dependency changes and notable -documentation additions. - -Major Feature Additions ------------------------ - -The major feature additions of 1.1 are: - -- Allow the use of additional :term:`view predicate` parameters to - more finely control view matching. - -- Allow the use of :term:`route predicate` parameters to more finely - control route matching. - -- Make it possible to write views that use a :term:`renderer`. - -- Make it possible to write views that use a "wrapper view". - -- Added ``<static>`` ZCML directive which registers a view which - serves up files in a package directory. - -- A new API function: ``repoze.bfg.url.static_url`` is available to - compute the path of static resources. - -- View configurations can now name an ``attr`` representing the method - or attribute of the view callable that should be called to return a - response. - -- ``@bfg_view`` decorators may now be stacked, allowing for the same - view callable to be associated with multiple different view - configurations without resorting to ZCML for view configuration. - -- ``@bfg_view`` decorators may now be placed on a class method. - -- ``paster bfgshell`` now supports IPython if it is found in the - Python environment invoking Paster. - -- Commonly executed codepaths have been accelerated. - -.. _view_predicates_in_1dot1: - -View Predicates -~~~~~~~~~~~~~~~ - -:mod:`repoze.bfg` 1.0, :term:`view configuration` allowed relatively -coarse matching of a :term:`request` to a :term:`view callable`. -Individual view configurations could match the same URL depending on -the :term:`context` and the URL path, as well as a limited number of -other request values. - -For example, two view configurations mentioning the same :term:`view -name` could be spelled via a ``@bfg_view`` decorator with a different -``for_`` parameter. The view ultimately chosen would be based on the -:term:`context` type based on the ``for_`` attribute like so: - -.. ignore-next-block -.. code-block:: python - - from webob import Response - from repoze.bfg.view import bfg_view - from myapp.models import Document - from myapp.models import Folder - - @bfg_view(name='index.html', for_=Document) - def document_view(context, request): - return Response('document view') - - @bfg_view(name='index.html', for_=Folder) - def folder_view(context, request): - return Response('folder view') - -In the above configuration, the ``document_view`` :term:`view -callable` will be chosen when the :term:`context` is of the class -``myapp.models.Document``, while the ``folder_view`` view callable -will be chosen when the context is of class ``myapp.models.Folder``. - -There were a number of other attributes that could influence the -choosing of view callables, such as ``request_type``, and others. -However, the matching algorithm was rather limited. - -In :mod:`repoze.bfg` 1.1, this facility has been enhanced via the -availability of additional :term:`view predicate` attributes. For -example, one view predicate new to 1.1 is ``containment``, which -implies that the view will be called when the class or interface -mentioned as ``containment`` is present with respect to any instance -in the :term:`lineage` of the context: - -.. ignore-next-block -.. code-block:: python - - from webob import Response - from repoze.bfg.view import bfg_view - from myapp.models import Document - from myapp.models import Folder - from myapp.models import Blog - from myapp.models import Calendar - - @bfg_view(name='index.html', for_=Document, containment=Blog) - def blog_document_view(context, request): - return Response('blog document view') - - @bfg_view(name='index.html', for_=Folder, containment=Blog) - def blog_folder_view(context, request): - return Response('blog folder view') - - @bfg_view(name='index.html', for_=Document, containment=Calendar) - def calendar_document_view(context, request): - return Response('calendar document view') - - @bfg_view(name='index.html', for_=Folder, containment=Calendar) - def calendar_folder_view(context, request): - return Response('calendar folder view') - -As might be evident in the above example, you can use the -``containment`` predicate to arrange for different view callables to -be called based on the lineage of the context. In the above example, -the ``blog_document_view`` will be called when the context is of the -class ``myapp.models.Document`` and the containment has an instance of -the class ``myapp.models.Blog`` in it. But when all else is equal, -except the containment has an instance of the class -``myapp.models.Calendar`` in it instead of ``myapp.models.Blog``, the -``calendar_document_view`` will be called instead. - -All view predicates configurable via the ``@bfg_view`` decorator are -available via :term:`ZCML` :term:`view configuration` as well. - -Additional new 1.1 view predicates besides ``containment`` are: - -``request_method`` - - True if the specified value (e.g. GET/POST/HEAD/PUT/DELETE) is the - request.method value. - -``request_param`` - - True if the specified value is present in the request.GET or - request.POST multidicts. - -``xhr`` - - True if the request.is_xhr attribute is ``True``, meaning that the - request has an ``X-Requested-With`` header with the value - ``XMLHttpRequest`` - -``accept`` - - True if the value of this attribute represents matches one or more - mimetypes in the ``Accept`` HTTP request header. - -``header`` - - True if the value of this attribute represents an HTTP header name - or a header name/value pair present in the request. - -``path_info`` - - True if the value of this attribute (a regular expression pattern) - matches the ``PATH_INFO`` WSGI environment variable. - -All other existing view configuration parameters from 1.0 still exist. - -Any number of view predicates can be specified in a view -configuration. All view predicates in a view configuration must be -True for a view callable to be invoked. If one does not evaluate to -True, the view will not be invoked, and view matching will continue, -until all potential matches are exhausted (and the Not Found view is -invoked). - -.. _route_predicates_in_1dot1: - -Route Predicates -~~~~~~~~~~~~~~~~ - -In :mod:`repoze.bfg` 1.0, a :term:`route` would match or not match -based on only one value: the ``PATH_INFO`` value of the WSGI -environment, as specified by the ``path`` parameter of the ``<route>`` -ZCML directive. - -In 1.1, matching can be more finely controlled via the use of one or -more :term:`route predicate` attributes. - -The additional route predicates in 1.1 are: - -``xhr`` - - True if the request.is_xhr attribute is ``True``, meaning that the - request has an ``X-Requested-With`` header with the value - ``XMLHttpRequest``. - -``request_method`` - - True if the specified value (e.g. GET/POST/HEAD/PUT/DELETE) is the - request.method value. - -``path_info`` - - True if the value of this attribute (a regular expression pattern) - matches the ``PATH_INFO`` WSGI environment variable. - -``request_param`` - - True if the specified value is present in either of the - ``request.GET`` or ``request.POST`` multidicts. - -``header`` - - True if the value of this attribute represents an HTTP header name - or a header name/value pair present in the request. - -``accept`` - - True if the value of this attribute represents matches one or more - mimetypes in the ``Accept`` HTTP request header. - -All other existing route configuration parameters from 1.0 still exist. - -Any number of route predicates can be specified in a route -configuration. All route predicates in a route configuration must be -True for a route to match a request. If one does not evaluate to -True, the route will not be invoked, and route matching will continue, -until all potential routes are exhausted (at which point, traversal is -attempted). - -View Renderers -~~~~~~~~~~~~~~ - -In :mod:`repoze.bfg` 1.0 and prior, views were required to return a -:term:`response` object unconditionally. - -In :mod:`repoze.bfg` 1.1, a :term:`view configuration` can name a -:term:`renderer`. A renderer can either be a template or a token that -is associated with a serialization technique (e.g. ``json``). When a -view configuration names a renderer, the view can return a data -structure understood by the renderer (such as a dictionary), and the -renderer will convert the data structure to a response on the behalf -of the developer. - -View configuration can vary the renderer associated with a view via -the ``renderer`` attribute to the configuration. For example, this -ZCML associates the ``json`` renderer with a view: - -.. code-block:: xml - :linenos: - - <view - view=".views.my_view" - renderer="json" - /> - -The ``@bfg_view`` decorator can also associate a view callable with a -renderer: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - - @bfg_view(renderer='json') - def my_view(context, request): - return {'abc':123} - -The ``json`` renderer renders view return values to a :term:`JSON` -serialization. - -Another built-in renderer uses the :term:`Chameleon` templating -language to render a dictionary to a response. For example: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - - @bfg_view(renderer='templates/my_template.pt') - def my_view(context, request): - return {'abc':123} - -See :ref:`built_in_renderers` for the available built-in renderers. - -If the ``view`` callable associated with a ``view`` directive returns -a Response object (an object with the attributes ``status``, -``headerlist`` and ``app_iter``), any renderer associated with the -``view`` declaration is ignored, and the response is passed back to -BFG unmolested. For example, if your view callable returns an -``HTTPFound`` response, no renderer will be employed. - -.. code-block:: python - :linenos: - - from webob.exc import HTTPFound - from repoze.bfg.view import bfg_view - - @bfg_view(renderer='templates/my_template.pt') - def my_view(context, request): - return HTTPFound(location='http://example.com') # renderer avoided - -Additional renderers can be added to the system as necessary via a -ZCML directive (see :ref:`adding_and_overriding_renderers`). - -If you do not define a ``renderer`` attribute in view configuration -for a view, no renderer is associated with the view. In such a -configuration, an error is raised when a view does not return an -object which implements :term:`Response` interface, as was the case -under BFG 1.0. - -Views Which Use Wrappers -~~~~~~~~~~~~~~~~~~~~~~~~ - -In :mod:`repoze.bfg` 1.1, view configuration may specify a ``wrapper`` -attribute. For example: - -.. code-block:: xml - :linenos: - - <view - name="one" - view=".views.wrapper_view" - /> - - <view - name="two" - view=".views.my_view" - wrapper="one" - /> - -The ``wrapper`` attribute of a view configuration is a :term:`view -name` (*not* an object dotted name). It specifies *another* view -callable declared elsewhere in :term:`view configuration`. In the -above example, the wrapper of the ``two`` view is the ``one`` view. - -The wrapper view will be called when after the wrapped view is -invoked; it will receive the response body of the wrapped view as the -``wrapped_body`` attribute of its own request, and the response -returned by this view as the ``wrapped_response`` attribute of its own -request. - -Using a wrapper makes it possible to "chain" views together to form a -composite response. The response of the outermost wrapper view will -be returned to the user. - -The wrapper view will be found as any view is found: see -:ref:`view_lookup`. The "best" wrapper view will be found based on -the lookup ordering: "under the hood" this wrapper view is looked up -via ``repoze.bfg.view.render_view_to_response(context, request, -'wrapper_viewname')``. The context and request of a wrapper view is -the same context and request of the inner view. - -If the ``wrapper`` attribute is unspecified in a view configuration, -no view wrapping is done. - -The ``@bfg_view`` decorator accepts a ``wrapper`` parameter, mirroring -its ZCML view configuration counterpart. - -``<static>`` ZCML Directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A new ZCML directive named ``static`` has been added. Inserting a -``static`` declaration in a ZCML file will cause static resources to -be served at a configurable URL. - -Here's an example of a ``static`` directive that will serve files up -from the ``templates/static`` directory of the :mod:`repoze.bfg` -application containing the following configuration at the URL -``/static``. - -.. code-block:: xml - :linenos: - - <static - name="static" - path="templates/static" - /> - -Using the ``static`` ZCML directive is now the preferred way to serve -static resources (such as JavaScript and CSS files) within a -:mod:`repoze.bfg` application. Previous strategies for serving static -resources will still work, however. - -New ``static_url`` API -~~~~~~~~~~~~~~~~~~~~~~ - -The new ``repoze.bfg.url.static_url`` API generates a fully qualified -URL to a static resource available via a path exposed via the -``<static>`` ZCML directive (see :ref:`static_resources_section`). -For example, if a ``<static>`` directive is in ZCML configuration like -so: - -.. code-block:: xml - :linenos: - - <static - name="static" - path="templates/static" - /> - -You can generate a URL to a resource which lives within the -``templates/static`` subdirectory using the ``static_url`` API like -so: - -.. ignore-next-block -.. code-block:: python - :linenos: - - from repoze.bfg.url import static_url - url = static_url('templates/static/example.css', request) - -Use of the ``static_url`` API prevents the developer from needing to -hardcode path values in template URLs. - -``attr`` View Configuration Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The view machinery defaults to using the ``__call__`` method of the -view callable (or the function itself, if the view callable is a -function) to obtain a response. - -In :mod:`repoze.bfg` 1.1, the ``attr`` view configuration value allows -you to vary the attribute of a view callable used to obtain the -response. - -For example, if your view is a class, and the class has a method named -``index`` and you want to use this method instead of the class' -``__call__`` method to return the response, you'd say ``attr="index"`` -in the view configuration for the view. - -Specifying ``attr`` is most useful when the view definition is a -class. For example: - -.. code-block:: xml - :linenos: - - <view - view=".views.MyViewClass" - attr="index" - /> - -The referenced ``MyViewClass`` might look like so: - -.. code-block:: python - :linenos: - - from webob import Response - - class MyViewClass(object): - def __init__(context, request): - self.context = context - self.request = request - - def index(self): - return Response('OK') - -The ``index`` method of the class will be used to obtain a response. - -``@bfg_view`` Decorators May Now Be Stacked -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - - @bfg_view(name='edit') - @bfg_view(name='change') - def edit(context, request): - pass - -This makes it possible to associate more than one view configuration -with a single callable without requiring any ZCML. - -Stacking ``@bfg_view`` decorators was not possible in -:mod:`repoze.bfg` 1.0. - -``@bfg_view`` Decorators May Now Be Applied to A Class Method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In :mod:`repoze.bfg` 1.0, the ``@bfg_view`` decorator could not be -used on class methods. In 1.1, the ``@bfg_view`` decorator can be -used against a class method: - -.. code-block:: python - :linenos: - - from webob import Response - from repoze.bfg.view import bfg_view - - class MyView(object): - def __init__(self, context, request): - self.context = context - self.request = request - - @bfg_view(name='hello') - def amethod(self): - return Response('hello from %s!' % self.context) - -When the bfg_view decorator is used against a class method, a view is -registered for the *class* (it's a "class view" where the "attr" -happens to be the name of the method it is attached to), so the class -it's defined within must have a suitable constructor: one that accepts -``context, request`` or just ``request``. - -IPython Support -~~~~~~~~~~~~~~~ - -If it is installed in the environment used to run :mod:`repoze.bfg`, -an `IPython <http://ipython.scipy.org/moin/>`_ shell will be opened -when the ``paster bfgshell`` command is invoked. - -Common Codepaths Have Been Accelerated -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:mod:`repoze.bfg` 1.1 is roughly 10% - 20% faster in commonly executed -codepaths than :mod:`repoze.bfg` 1.0 was on average. Accelerated APIs -include ``repoze.bfg.location.lineage``, ``repoze.bfg.url.model_url``, -and ``repoze.bfg.url.route_url``. Other internal (non-API) functions -were similarly accelerated. - -Minor Miscellaneous Feature Additions -------------------------------------- - -- 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_INFO`` *plus* a slash matches any route's path, do an HTTP - redirect to the slash-appended PATH_INFO. Note that this will - *lose* ``POST`` data information (turning it into a GET), so you - shouldn't rely on this to redirect POST requests. - -- 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. - -- 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. - -- 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. - -- Virtual hosting narrative docs chapter updated with info about - ``mod_wsgi``. - -- Added "Creating Integration Tests" section to unit testing narrative - documentation chapter. As a result, the name of the unittesting - chapter is now "Unit and Integration Testing". - -- 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. - -- Added a tutorial which explains how to use ``repoze.session`` - (ZODB-based sessions) in a ZODB-based repoze.bfg app. - -- Added a tutorial which explains how to add ZEO to a ZODB-based - ``repoze.bfg`` application. - -- Added a tutorial which explains how to run a ``repoze.bfg`` - application under `mod_wsgi <http://code.google.com/p/modwsgi/>`_. - See "Running a repoze.bfg Application under mod_wsgi" in the - tutorials section of the documentation. - -- 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. - -- 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.exceptions.Unauthorized`` and - ``repoze.bfg.exceptions.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. - -- Add a new event type: ``repoze.bfg.events.AfterTraversal``. Events - of this type will be sent after traversal is completed, but before - any view code is invoked. Like ``repoze.bfg.events.NewRequest``, - This event will have a single attribute: ``request`` representing - the current request. Unlike the request attribute of - ``repoze.bfg.events.NewRequest`` however, during an AfterTraversal - event, the request object will possess attributes set by the - traverser, most notably ``context``, which will be the context used - when a view is found and invoked. The interface - ``repoze.bfg.events.IAfterTraversal`` can be used to subscribe to - the event. For example:: - - <subscriber for="repoze.bfg.interfaces.IAfterTraversal" - handler="my.app.handle_after_traverse"/> - - Like any framework event, a subscriber function should expect one - parameter: ``event``. - -- A ``repoze.bfg.testing.registerRoutesMapper`` testing facility has - been 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. - -Backwards Incompatibilities ---------------------------- - -- The ``authtkt`` authentication policy ``remember`` method now no - longer honors ``token`` or ``userdata`` keyword arguments. - -- 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 ``from zope.component import getSiteManager``. Import of - ``get_registry`` should be done as ``from repoze.bfg.threadlocal - import get_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. - -- In 0.8a7, the return value expected from an object implementing - ``ITraverserFactory`` was changed from a sequence of values to a - dictionary containing the keys ``context``, ``view_name``, - ``subpath``, ``traversed``, ``virtual_root``, ``virtual_root_path``, - and ``root``. Until now, old-style traversers which returned a - sequence have continued to work but have generated a deprecation - warning. In this release, traversers which return a sequence - instead of a dictionary will no longer work. - -- The interfaces ``IPOSTRequest``, ``IGETRequest``, ``IPUTRequest``, - ``IDELETERequest``, and ``IHEADRequest`` have been removed from the - ``repoze.bfg.interfaces`` module. These were not documented as APIs - post-1.0. Instead of using one of these, use a ``request_method`` - ZCML attribute or ``request_method`` bfg_view decorator parameter - containing an HTTP method name (one of ``GET``, ``POST``, ``HEAD``, - ``PUT``, ``DELETE``) instead of one of these interfaces if you were - using one explicitly. Passing a string in the set (``GET``, - ``HEAD``, ``PUT``, ``POST``, ``DELETE``) as a ``request_type`` - argument will work too. Rationale: instead of relying on interfaces - attached to the request object, BFG now uses a "view predicate" to - determine the request type. - -- Views registered without the help of the ZCML ``view`` directive are - now responsible for performing their own authorization checking. - -- The ``registry_manager`` backwards compatibility alias importable - from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been - removed. If you are trying to use the registry manager within a - debug script of your own, use a combination of the - "repoze.bfg.paster.get_app" and "repoze.bfg.scripting.get_root" APIs - instead. - -- The ``INotFoundAppFactory`` interface has been removed; it has - been deprecated since repoze.bfg 0.9. If you have something like - the following in your ``configure.zcml``:: - - <utility provides="repoze.bfg.interfaces.INotFoundAppFactory" - component="helloworld.factories.notfound_app_factory"/> - - Replace it with something like:: - - <notfound - view="helloworld.views.notfound_view"/> - - See "Changing the Not Found View" in the "Hooks" chapter of the - documentation for more information. - -- The ``IUnauthorizedAppFactory`` interface has been removed; it has - been deprecated since repoze.bfg 0.9. If you have something like - the following in your ``configure.zcml``:: - - <utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory" - component="helloworld.factories.unauthorized_app_factory"/> - - Replace it with something like:: - - <forbidden - view="helloworld.views.forbidden_view"/> - - See "Changing the Forbidden View" in the "Hooks" chapter of the - documentation for more information. - -- ``ISecurityPolicy``-based security policies, deprecated since - repoze.bfg 0.9, have been removed. If you have something like this - in your ``configure.zcml``, it will no longer work:: - - <utility - provides="repoze.bfg.interfaces.ISecurityPolicy" - factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy" - /> - - If ZCML like the above exists in your application, you will receive - an error at startup time. Instead of the above, you'll need - something like:: - - <remoteuserauthenticationpolicy/> - <aclauthorizationpolicy/> - - This is just an example. See the "Security" chapter of the - repoze.bfg documentation for more information about configuring - security policies. - -- The ``repoze.bfg.scripting.get_root`` function now expects a - ``request`` object as its second argument rather than an - ``environ``. - -Deprecations and Behavior Differences -------------------------------------- - -- 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 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 order in which the router calls the request factory and the root - factory has been reversed. The request factory is now called first; - the resulting request is passed to the root factory. - -- 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 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. - -- 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. - -Dependency Changes ------------------- - -- When used under Python < 2.6, BFG now has an installation time - dependency on the ``simplejson`` package. - diff --git a/docs/whatsnew-1.2.rst b/docs/whatsnew-1.2.rst deleted file mode 100644 index 9b446f4b8..000000000 --- a/docs/whatsnew-1.2.rst +++ /dev/null @@ -1,364 +0,0 @@ -What's New In :mod:`repoze.bfg` 1.2 -=================================== - -This article explains the new features in :mod:`repoze.bfg` version -1.2 as compared to the previous 1.1 release. It also documents -backwards incompatibilities between the two versions and deprecations -added to 1.2, as well as software dependency changes and notable -documentation additions. - -Major Feature Additions ------------------------ - -The major feature addition in 1.2 is an :term:`imperative -configuration` mode. This implies: - -- A :mod:`repoze.bfg` application can now be contained within a single - Python file. - -- Developers are no longer required to use or understand :term:`ZCML` - to create a :mod:`repoze.bfg` application (ZCML is, however still - supported). - -The simplest possible :mod:`repoze.bfg` 1.2 application is: - - .. code-block:: python - :linenos: - - from webob import Response - from paste.httpserver import serve - from repoze.bfg.configuration import Configurator - - def hello_world(request): - return Response('Hello world!') - - if __name__ == '__main__': - config = Configurator() - config.begin() - config.add_view(hello_world) - config.end() - app = config.make_wsgi_app() - serve(app) - -This feature tends to make :mod:`repoze.bfg` competitive with -"microframeworks" such as `Bottle <http://bottle.paws.de/>`_ and -`Tornado <http://www.tornadoweb.org/>`_. :mod:`repoze.bfg` has a good -deal of functionality that most microframeworks lack, so this is -hopefully a "best of both worlds" feature. - -Imperative configuration is also useful while writing tests. - -For an introduction to imperative configuration mode, see -:ref:`configuration_narr`. - -Minor Feature Additions ------------------------ - -- Jython compatibility (at least when ``repoze.bfg.jinja2`` is used as - the templating engine; Chameleon does not work under Jython). - -- Read logging configuration from PasteDeploy config file ``loggers`` - section (and related) when ``paster bfgshell`` is invoked. - -- The ``AuthTktAuthenticationPolicy`` now accepts two additional - constructor arguments: ``path`` and ``http_only``. - -- The :func:`repoze.bfg.testing.setUp` function now accepts three - extra optional keyword arguments: ``registry``, ``request`` and - ``hook_zca``. - - If the ``registry`` argument is not ``None``, the argument will be - treated as the registry that is set as the "current registry" (it - will be returned by - :func:`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 - :func:`repoze.bfg.threadlocal.get_current_request`) for the duration - of the test; it defaults to ``None``. - - If ``hook_zca`` is ``True`` (the default), the - :func:`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 :func:`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 :func:`repoze.bfg.testing.tearDown` function now accepts an - ``unhook_zca`` argument. If this argument is ``True`` (the - default), :func:`zope.component.getSiteManager.reset` will be - called. This will cause the result of the - :func:`zope.component.getSiteManager` function to be the global ZCA - registry (the result of :func:`zope.component.getGlobalSiteManager`) - once again. - -- When the :exc:`repoze.bfg.exceptions.NotFound` or - :exc:`repoze.bfg.exceptions.Forbidden` error is raised from within a - custom :term:`root factory` or the factory of a :term:`route`, the - appropriate response is 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 - :term:`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. - -- :class:`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 - :func:`zope.interface.alsoProvides`). - -- Read logging configuration from PasteDeploy config file ``loggers`` - section (and related) when ``paster bfgshell`` is invoked. - -- View registration via ZCML now accepts an attribute 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". - -Backwards Incompatibilites --------------------------- - -- Unit tests which use :func:`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 - :func:`repoze.bfg.threadlocal.get_current_registry` when no other - registry had been pushed on to the threadlocal stack was the - :data:`zope.component.globalregistry.base` global registry (aka the - result of :func:`zope.component.getGlobalSiteManager()`). In - :mod:`repoze.bfg` 1.2+, however, the registry returned in this - situation is the new module-scope - :data:`repoze.bfg.registry.global_registry` object. The - :func:`zope.testing.cleanup.cleanUp` function clears the - :data:`zope.component.globalregistry.base` global registry - unconditionally. However, it does not know about the - :data:`repoze.bfg.registry.global_registry` object, so it does not - clear it. - - If you use the :func:`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) :func:`repoze.bfg.testing.setUp`, you will - need to replace all calls to :func:`zope.testing.cleanup.cleanUp` - with a call to :func:`repoze.bfg.testing.setUp`. - - If replacing all calls to :func:`zope.testing.cleanup.cleanUp` with - a call to :func:`repoze.bfg.testing.setUp` is infeasible, you can - put the below-mentioned bit of code somewhere that is executed - exactly **once** (*not* for each test in a test suite). Placing - this in the ``__init__.py`` of your package or the ``__init__.py`` - of a ``tests`` subpackage would be a reasonable place):: - - import zope.testing.cleanup - from repoze.bfg.testing import setUp - zope.testing.cleanup.addCleanUp(setUp) - -- When there is no "current registry" in the - :data:`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 :func:`repoze.bfg.testing.setUp` or - :meth:`repoze.bfg.configuration.Configurator.begin` 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 - :func:`zope.component.getGlobalSiteManager`, which is an instance of - the :class:`zope.component.registry.Component` class. In this - release, however, the global registry returns a globally importable - instance of the :class:`repoze.bfg.registry.Registry` class. This - registry instance can always be imported as - :data:`repoze.bfg.registry.global_registry`. - - Effectively, this means that when you call - :func:`repoze.bfg.threadlocal.get_current_registry` when no "real" - request or bounded unit test is in effect, you will always get back - the global registry that lives in - :data:`repoze.bfg.registry.global_registry`. It also means that - :mod:`repoze.bfg` APIs that *call* - :func:`repoze.bfg.threadlocal.get_current_registry` will use this - registry. - - This change was made because :mod:`repoze.bfg` now expects the - registry it uses to have a slightly different API than a bare - instance of :class:`zope.component.registry.Components`. - -- View registration no longer registers a - :class:`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 :func:`repoze.bfg.router.make_app` callable no longer accepts an - ``authentication_policy`` nor an ``authorization_policy`` argument. - These features were deprecated in version 1.0 and have been removed. - -- The ``route`` ZCML directive now no longer accepts the - ``request_type``, ``view_request_type``, ``view_header``, - ``view_accept``, ``view_xhr``, ``view_path_info``, - ``view_request_method``, ``view_request_param``, or - ``view_containment`` attributes. 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. - -- Because the ``repoze.bfg`` package now includes implementations of - the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it - is now an error to have ``<include package="repoze.zcml" - file="meta.zcml"/>`` in the ZCML of a ``repoze.bfg`` application. A - ZCML conflict error will be raised if your ZCML does so. This - shouldn't be an issue for "normal" installations; it has always been - the responsibility of the :mod:`repoze.bfg.includes` ZCML to include - this file in the past; it now just doesn't. - -- The :func:`repoze.bfg.testing.zcml_configure` API was removed. Use - the :meth:`repoze.bfg.configuration.Configurator.load_zcml` API - instead. - -- The :mod:`repoze.bfg.templating` module has been removed; it had - been deprecated in 1.1 and hasn't possessed any APIs since before - 1.0. - -- Remove magical feature of :meth:`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. - -- 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. - -Deprecations and Behavior Differences -------------------------------------- - -- If you disuse the legacy :func:`repoze.bfg.router.make_app` function - in favor of - :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app`, and you - also want to use the "global" ZCA API (``getUtility``, - ``getAdapter``, ``getSiteManager``, etc), you will need to "hook" - the ZCA before calling methods of the configurator using the - ``sethook`` method of the ``getSiteManager`` API, e.g.:: - - from zope.component import getSiteManager - from repoze.bfg.configuration import Configurator - from repoze.bfg.threadlocal import get_current_registry - from mypackage.models import get_root - - def app(global_config, **settings): - config = Configurator(root_factory=get_root, settings=settings) - getSiteManager.sethook(get_current_registry) - zcml_file = settings.get('configure_zcml', 'configure.zcml') - config.load_zcml(zcml_file) - return config.make_wsgi_app() - - The :func:`repoze.bfg.router.make_app` function does this on your - behalf for backward compatibility purposes. - -- The :func:`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 - :class:`repoze.bfg.configuration.Configurator` class is now the - preferred way to generate a WSGI application. - - Note that :func:`repoze.bfg.router.make_app` calls - ``zope.component.getSiteManager.sethook( - repoze.bfg.threadlocal.get_current_registry)`` on the caller's - behalf, hooking ZCA global API lookups, for backwards compatibility - purposes. If you disuse ``make_app``, your calling code will need - to perform this call itself, at least if your application uses the - ZCA global API (``getSiteManager``, ``getAdapter``, etc). - -Dependency Changes ------------------- - -- A dependency on the ``martian`` package has been removed (its - functionality is replaced internally). - -- A dependency on the ``repoze.zcml`` package has been removed (its - functionality is replaced internally). - -- A dependency on the ``sourcecodegen`` package has been removed. - -- :mod:`repoze.bfg` now depends on :term:`WebOb` 0.9.7 or better. - -- 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 :class:`repoze.bfg.configuration.Configurator`. - -Documentation Enhancements --------------------------- - -- This documentation has been published in `printed form - <http://bfg.repoze.org/book>`_ under the title *The repoze.bfg Web - Application Framework, Version 1.2*. It was reworked and - restructured extensively for this publication. `Show your support - for BFG by buying a copy! <http://bfg.repoze.org/book>`_. - -- 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". - -- :mod:`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 :class:`repoze.bfg.configuration.Configurator` - class, and demonstrates a simplified "imperative-mode" - configuration; doing :mod:`repoze.bfg` application configuration - imperatively was previously much more difficult. - -- The "ZCML Hooks" chapter has been renamed to "Hooks" - (:ref:`hooks_chapter`); 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 (:ref:`unittesting_chapter`). - -- Remove explanation of changing the request type in a new request - event subscriber in the "Events" narrative documentation chapter, as - other predicates are now usually an easier way to get this done. - -- Added "Thread Locals" narrative chapter to documentation, and added - a API chapter documenting the :mod:`repoze.bfg.threadlocals` module. - -- Added a "Special Exceptions" section to the "Views" narrative - documentation chapter explaining the effect of raising - :exc:`repoze.bfg.exceptions.NotFound` and - :exc:`repoze.bfg.exceptions.Forbidden` from within view code. - -- Add a narrative documentation chapter named :ref:`zca_chapter`. - -- Created new top-level documentation section named - :ref:`zcml_directives`. This section contains detailed ZCML - directive information, some of which was removed from various - narrative chapters. - -Licensing Changes ------------------ - -- The publication of the documentation as a printed book required an - explicit documentation licensing change: the documentation (the - content in the "docs" directory) is now offered under the `Creative - Commons Attribution-Noncommercial-Share Alike 3.0 United States - License <http://creativecommons.org/licenses/by-nc-sa/3.0/us/>`_. - This is only a documentation licensing change: the :mod:`repoze.bfg` - software itself (everything except the contents of the "docs" - directory) is still offered under `a BSD-like license - <http://repoze.org/license.html>`_. - diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst deleted file mode 100644 index 8447f8e38..000000000 --- a/docs/whatsnew-1.3.rst +++ /dev/null @@ -1,771 +0,0 @@ -What's New In :mod:`repoze.bfg` 1.3 -=================================== - -This article explains the new features in :mod:`repoze.bfg` version -1.3 as compared to the previous 1.2 release. It also documents -backwards incompatibilities between the two versions and deprecations -added to 1.3, as well as software dependency changes and notable -documentation additions. - -Major Feature Additions ------------------------ - -The major feature additions in 1.3 are: - -- *Internationalization* (i18n) and *localization* (l10n) services - -- *Exception views* - -Internationalization and Localization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:mod:`repoze.bfg` 1.3 offers internationalization (i18n) and -localization (l10n) subsystems that can be used to translate the text -of buttons, the text of error messages and other software- and -template-defined values into the native language of a user of your -application. - -:mod:`repoze.bfg` i18n / l10n framework includes: - -- Support for :term:`translation string` specifications. - -- Tools allowing you to specify and work with :term:`gettext` - :term:`message catalog` files to allow for text translation. - -- :term:`Locale name` negotiation features. - -- Translation and pluralization services. - -For detailed documentation about :mod:`repoze.bfg` -internationalization and localization features, see -:ref:`i18n_chapter`. - -Exception Views -~~~~~~~~~~~~~~~~ - -In :mod:`repoze.bfg` 1.3+, when you use an exception (anything that -inherits from the Python :exc:`Exception` builtin) as view context -argument, e.g.: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound) - def notfound_view(request): - return HTTPNotFound() - -For the above example, when the :exc:`repoze.bfg.exceptions.NotFound` -exception is raised by any view or any root factory, the -``notfound_view`` view callable will be invoked and its response -returned. - -Other normal view predicates can also be used in combination with an -exception view registration: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound - from webob.exc import HTTPNotFound - - @bfg_view(context=NotFound, route_name='home') - def notfound_view(request): - return HTTPNotFound() - -The above exception view names the ``route_name`` of ``home``, meaning -that it will only be called when the route matched has a name of -``home``. You can therefore have more than one exception view for any -given exception in the system: the "most specific" one will be called -when the set of request circumstances 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 :class:`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 -:meth:`repoze.bfg.configuration.Configurator.add_view` styles). - -This feature was kindly contributed by Andrey Popp. - -Minor Feature Additions ------------------------ - -- Use :term:`Venusian` to perform ``@bfg_view`` decorator scanning - rather than relying on a BFG-internal decorator scanner. This means - that user-defined decorators can be defined and found during - :mod:`repoze.bfg` scanning. See - :ref:`registering_configuration_decorators` for more information. - -- 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 - newly generated projects. See also :ref:`debug_templates_section`. - -- A new API method named - :meth:`repoze.bfg.configuration.Configurator.derive_view` was - added. This API 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. - -- Prior to 1.3, a *route predicate* had no access to route pattern - matching information and had no way to know which route was matched. - As of 1.3a4, each of the predicate callables fed to the - ``custom_predicates`` argument of - :meth:`repoze.bfg.configuration.Configurator.add_route` or the - ``custom_predicates`` ZCML attribute can be a callable accepting two - arguments. The first argument passed to a custom predicate is a - dictionary conventionally named ``info``. The second argument is - the current :term:`request` object. The ``info`` dictionary has a - number of contained values: ``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. See also - :ref:`custom_route_predicates`. In prior versions, the ``info`` - argument was always ``None``. - -- The :func:`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 - :meth:`repoze.bfg.configuration.Configurator.add_static_view`. When - the name argument is a URL, the :func:`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. - -- New argument to - :class:`repoze.bfg.configuration.Configurator.add_route` and the - ZCML ``route`` directive: ``traverse``. If you would like to cause - the :term:`context` to be something other than the :term:`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). See - :class:`repoze.bfg.configuration.Configurator.add_route` for more - information (the ``traverse`` argument). - -- A new method exists: - :meth:`repoze.bfg.configuration.Configurator.set_request_factory`. - If used, this method will set the factory used by the - :mod:`repoze.bfg` router to create all request objects. - -- The :class:`repoze.bfg.configuration.Configurator` constructor takes - an additional argument: ``request_factory``. If used, this argument - will set the factory used by the :mod:`repoze.bfg` router to create - all request objects. - -- A new method exists - :meth:`repoze.bfg.configuration.Configurator.set_renderer_globals_factory`. - If used, this method will set the factory used by the - :mod:`repoze.bfg` router to create renderer globals. - -- A new method exists: - :meth:`repoze.bfg.configuration.Configurator.get_settings`. If - used, this method will return the current settings object (performs - the same job as the :func:`repoze.bfg.settings.get_settings` API). - -- The :class:`repoze.bfg.configuration.Configurator` constructor takes - an additional argument: ``renderer_globals_factory``. If used, this - argument will set the factory used by the :mod:`repoze.bfg` router - to create renderer globals. - -- Add :func:`repoze.bfg.renderers.render`, - :func:`repoze.bfg.renderers.render_to_response` and - :func:`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 :mod:`repoze.bfg.chameleon_zpt` - and :mod:`repoze.bfg.chameleon_text` is now discouraged (although - not deprecated). The code the backing older - templating-system-specific APIs now calls into the newer - :mod:`repoze.bfg.renderer` code. - -- The - :meth:`repoze.bfg.configuration.Configurator.testing_add_template` - method has been renamed to - :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`. - A backwards compatibility alias is present using the old name. - -- When decoding a URL segment to Unicode fails, the exception raised - is now :exc:`repoze.bfg.exceptions.URLDecodeError` instead of - :exc:`UnicodeDecodeError`. This makes it possible to register an - exception view invoked specifically when :mod:`repoze.bfg` cannot - decode a URL. - -- A :func:`repoze.bfg.events.subscriber` decorator was added. This - decorator can be used to decorates module-scope functions, which are - then treated as event listeners after a scan() is performed. See - the :ref:`events_chapter` documentation chapter and the - :mod:`repoze.bfg.events` module documentation for more information. - -- The :func:`repoze.bfg.configuration.Configurator.add_route` API now - returns the route object that was added. - -- New API class: - :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory`. - - There can only be one :term:`Not Found view` in any - :mod:`repoze.bfg` application. Even if you use - :func:`repoze.bfg.view.append_slash_notfound_view` as the Not Found - view, :mod:`repoze.bfg` still must generate a ``404 Not Found`` - response when it cannot redirect to a slash-appended URL; this not - found response will be visible to site users. - - If you don't care what this 404 response looks like, and only you - need redirections to slash-appended route URLs, you may use the - :func:`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 - :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` class as the - Not Found view, supplying a :term:`view callable` to be used as the - custom notfound view as the first argument to its constructor. For - instance: - - .. code-block:: python - - from repoze.bfg.exceptions import NotFound - from repoze.bfg.view import AppendSlashNotFoundViewFactory - - def notfound_view(context, request): - return HTTPNotFound('It aint there, stop trying!') - - custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view) - config.add_view(custom_append_slash, context=NotFound) - - The ``notfound_view`` supplied must adhere to the two-argument view - callable calling convention of ``(context, request)`` (``context`` - will be the exception object). - -- The :class:`repoze.bfg.configuration.Configurator` constructor now - accepts a dotted name *string* to a package as a ``package`` - argument. The ``package`` argument was previously required to be a - package *object* (not a dotted name string). - -- The :meth:`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``. - -- The :meth:`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 :exc:`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 - :meth:`repoze.bfg.configuration.Configurator.absolute_resource_spec` - method resolves a potentially relative :term:`resource - specification` string into an absolute version. - -- A new :meth:`repoze.bfg.request.Request.add_response_callback` API - has been added. It can be used to influence response values before - a concrete response object has been created. See the - :ref:`using_response_callbacks` for more information. - -- The :class:`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 - :class:`repoze.bfg.configuration.Configurator` now allow the - below-named arguments to be passed as "dotted name strings" - (e.g. "foo.bar.baz") rather than as actual implementation objects - that must be imported: - - setup_registry - root_factory, authentication_policy, authorization_policy, - debug_logger, locale_negotiator, request_factory, - renderer_globals_factory - - add_subscriber - subscriber, iface - - derive_view - view - - add_view - view, ``for_``, context, request_type, containment - - add_route() - view, view_for, factory, ``for_``, view_context - - scan - package - - add_renderer - factory - - set_forbidden_view - view - - set_notfound_view - view - - set_request_factory - factory - - set_renderer_globals_factory() - factory - - set_locale_negotiator - negotiator - - testing_add_subscriber - event_iface - -- The argument to - :meth:`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 (see - :ref:`route_directive`) is now named ``pattern`` for better - explicability. The older ``path`` attribute will continue to work - indefinitely. - -- The ``routesalchemy`` paster template has been updated to use - ``pattern`` in its route declarations rather than ``path``. - -- 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 - :class:`repoze.bfg.configuration.Configurator`: - ``default_permission``. - - - A new method was added: - :meth:`repoze.bfg.configuration.Configurator.set_default_permission`. - - - A new ZCML directive was added: :ref:`default_permission_directive`. - -- Add a new request API: - :meth:`repoze.bfg.request.Request.add_finished_callback`. Finished - callbacks are called by the router unconditionally near the very end - of request processing. See the :ref:`using_finished_callbacks` for - more information. - -- A ``matched_route`` attribute is now added to the :term:`request` - object when a route has matched. Its value is the :term:`route` - object that matched (see :class:`repoze.bfg.interfaces.IRoute` for - the API of a route object). - -- The ``exception`` attribute of the :term:`request` is now set - slightly earlier and in a slightly different set of scenarios by the - router, 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 :meth:`repoze.bfg.configuration.Configurator.add_route` method - now accepts a ``pregenerator`` argument. The pregenerator for the - resulting route is called by :func:`repoze.bfg.url.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 - :class:`repoze.bfg.interfaces.IRoutePregenerator` for more - information. - -- Compatibility with WebOb 1.0 (now requires WebOb >= 1.0). - -- The :meth:`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 :meth:`repoze.bfg.traversal.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. - -Backwards Incompatibilities ---------------------------- - -- In previous releases, when a URL could not be decoded from UTF-8 - during traversal, a :exc:`TypeError` was raised. Now the error - which is raised is :exc:`repoze.bfg.exceptions.URLDecodeError`. - -- 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 :exc:`repoze.bfg.exceptions.NotFound` exception - was raised. We provide backwards compatibility for code that - expected a ``NotFound`` to be raised when no predicates match by - causing ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from - ``NotFound``. This will cause any exception view registered for - ``NotFound`` to be called when a predicate mismatch occurs, as was - the previous behavior. - - There is however, one perverse case that will expose a backwards - incompatibility. If 1) you had a view that was registered as a - member of a multiview 2) this view explicitly raised a ``NotFound`` - exception *in order to* proceed to the next predicate check in the - multiview, that code will now behave differently: rather than - skipping to the next view match, a NotFound will be raised to the - top-level exception handling machinery instead. For code to be - depending upon the behavior of a view raising ``NotFound`` to - proceed to the next predicate match, would be tragic, but not - impossible, given that ``NotFound`` is a public interface. - ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and - cannot be depended upon by application code, so you should not - change your view code to raise ``PredicateMismatch``. Instead, move - the logic which raised the ``NotFound`` exception in the view out - into a custom view predicate. - -- If, when you run your application's unit test suite under BFG 1.3, a - ``KeyError`` naming a template or a ``ValueError`` indicating that a - 'renderer factory' is not registered may is raised - (e.g. ``ValueError: No factory for renderer named '.pt' when looking - up karl.views:templates/snippets.pt``), you may need to perform some - extra setup in your test code. - - The best solution is to use the - :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer` - (or, alternately the deprecated - :func:`repoze.bfg.testing.registerTemplateRenderer` or - `repoze.bfg.testing.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: - - .. code-block:: python - - config = Configurator() - config.testing_add_renderer('karl.views:templates/snippets.pt') - - This will register a basic dummy renderer for this particular - missing template. The - :meth:`repoze.bfg.configuration.Configurator.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 - :meth:`repoze.bfg.configuration.Configurator.setup_registry` - method. For example: - - .. code-block:: python - - reg = MyRegistry() - config = Configurator(registry=reg) - config.setup_registry() - - Calling :meth:`repoze.bfg.configuration.Configurator.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 :mod:`repoze.bfg.testing` APIs name - :func:`repoze.bfg.testng.setUp` or - :func:`repoze.bfg.testng.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 - :meth:`repoze.bfg.configuration.Configurator.testing_register_renderer` - or :func:`repoze.bfg.testing.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 :term:`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). - -- A bug existed in the regular expression to do URL matching. As an - example, the URL matching machinery would cause the pattern - ``/{foo}`` to match the root URL ``/`` resulting in a match - dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might - match the URL ``//edit`` resulting in a match dictionary of - ``{'fud':u''}``. It was always the intent that ``:segment`` markers - in the pattern would need to match *at least one* character, and - never match the empty string. This, however, means that in certain - circumstances, a routing match which your application inadvertently - depended upon may no longer happen. - -- 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. - -- Due to changes introduced WebOb 1.0, the - ``repoze.bfg.request.make_request_ascii`` event subscriber no longer - worked, 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. - -Deprecations and Behavior Differences -------------------------------------- - -- The exception views feature replaces the need for the - ``set_notfound_view`` and ``set_forbidden_view`` methods of the - :class:`repoze.bfg.configuration.Configurator` as well as the - :ref:`notfound_directive` and :ref:`forbidden_directive` ZCML - directives. Those methods and directives will continue to work for - the foreseeable future, but they are deprecated in the - documentation. - -- 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 - :func:`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 :mod:`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 :mod:`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 :mod:`repoze.bfg.renderers` module. - -- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event - interface was renamed to - :class:`repoze.bfg.interfaces.IApplicationCreated`. Likewise, the - ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed - to :class:`repoze.bfg.events.ApplicationCreated`. The older aliases - will continue to work indefinitely. - -- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was - renamed to :class:`repoze.bfg.interfaces.IContextFound`. Likewise, - the ``repoze.bfg.events.AfterTraversal`` class was renamed to - :class:`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. - -Dependency Changes ------------------- - -- A new install-time dependency on the ``venusian`` distribution was - added. - -- A new install-time dependency on the ``translationstring`` - distribution was added (internationalization). - -- Chameleon 1.2.3 or better is now required (internationalization and - per-template debug settings). - -- :mod:`repoze.bfg` ``tests_require`` now includes - ``repoze.sphinx.autointerface`` as a dependency. - -Documentation Enhancements --------------------------- - -- Exception view documentation was added to the :ref:`hooks_chapter` - narrative chapter. - -- A new narrative chapter entitled :ref:`i18n_chapter` was added. - -- The :ref:`environment_chapter` chapter was changed: documentation - about the ``default_locale_name`` setting was added. - -- A new API chapter for the :ref:`i18n_module` module was added. - -- Documentation for the new :ref:`translationdir_directive` and - :ref:`localenegotiator_directive` ZCML directives were added. - -- A section :ref:`custom_route_predicates` was added to the URL - Dispatch narrative chapter. - -- The :ref:`static_resources_section` and - :ref:`generating_static_resource_urls` sections of the Static - Resources chapter have been updated to mention using - :func:`repoze.bfg.url.static_url` to generate URLs to external - webservers. - -- Documentation for registering a new configuration decorator was - added in :ref:`registering_configuration_decorators`. - -- The authorization chapter of the :ref:`bfg_wiki_tutorial` was - changed to demonstrate authorization via a group rather than via a - direct username. - -- The authorization chapter of the :ref:`bfg_sql_wiki_tutorial` was - changed to demonstrate authorization via a group rather than via a - direct username. - -- The :ref:`hooks_chapter` chapter now contains a section about - changing the request factory. - -- The :ref:`hooks_chapter` chapter now contains sections about - changing the request factory and adding a renderer globals factory. - -- The :ref:`hybrid_chapter` chapter now contains a description of the - ``traverse`` route argument. - -- The API documentation includes a new module: - :mod:`repoze.bfg.renderers`. - -- The :ref:`templates` chapter was updated; all narrative that used - templating-specific APIs within examples to perform rendering (such - as the :func:`repoze.bfg.chameleon_zpt.render_template_to_response` - method) was changed to use :mod:`repoze.bfg.renderers` ``render_*`` - functions. - -- Added description of the :class:`repoze.bfg.events.subscriber` - decorator to the :ref:`events_chapter` narrative documentation - chapter. - -- Added :class:`repoze.bfg.events.subscriber` API documentation to - :mod:`repoze.bfg.events` API docs. - -- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By - Default; BFG Does Not" to the :ref:`design_defense` chapter. - -- Expanded the :ref:`cleaning_up_after_a_request` section of the URL - Dispatch narrative chapter. - -- Expanded the :ref:`redirecting_to_slash_appended_routes` section of - the URL Dispatch narrative chapter. - -- Add an API chapter for the :mod:`repoze.bfg.request` module, which - includes documentation for the :class:`repoze.bfg.request.Request` - class (the "request object"). - -- Modify the :ref:`webob_chapter` narrative chapter to reference the - new :mod:`repoze.bfg.request` API chapter. Some content was moved - from this chapter into the API documentation itself. - -- Various changes to denote that Python dotted names are now allowed - as input to Configurator methods. - -- All narrative, API, and tutorial docs which referred to a route - pattern as a ``path`` have now been updated to refer to them as a - ``pattern``. - -- The :mod:`repoze.bfg.interfaces` API documentation page is now - rendered via ``repoze.sphinx.autointerface``. - -- The :ref:`urldispatch_chapter` chapter now refers to the - :mod:`repoze.bfg.interfaces` chapter to explain the API of an - :class:`repoze.bfg.interfaces.IRoute` object. - -- Added documentation for the :ref:`default_permission_directive` ZCML - directive. - -- Added documentation for the ``default_permission`` parameter of the - :class:`repoze.bfg.configuration.Configurator` constructor and the - :meth:`repoze.bfg.configuration.Configurator.set_default_permission`` - method. - -- Added a new section to the :ref:`security_chapter` named - :ref:`setting_a_default_permission`. - -- Document ``renderer_globals_factory`` and ``request_factory`` - arguments to the :class:`repoze.bfg.configuration.Configurator` - constructor. - -- Added two sections to the "Hooks" chapter of the documentation: - :ref:`using_response_callbacks` and :ref:`using_finished_callbacks`. - -- Added documentation of the ``request.exception`` attribute to the - :class:`repoze.bfg.request.Request` API documentation. - -- The :ref:`router_chapter` narrative chapter has been updated to note - finished and response callback steps. - -- New interface in interfaces API documentation: - :class:`repoze.bfg.interfaces.IRoutePregenerator`. - -- Added a "The Matched Route" section to the - :ref:`urldispatch_chapter` narrative docs chapter, detailing the - ``matched_route`` attribute. - -Licensing Changes ------------------ - -- The Edgewall (BSD) license was added to the LICENSES.txt file, as - some code in the :mod:`repoze.bfg.i18n` module derives from - :term:`Babel` source. diff --git a/docs/zcml/.#include.rst b/docs/zcml/.#include.rst deleted file mode 120000 index 0e27a9e93..000000000 --- a/docs/zcml/.#include.rst +++ /dev/null @@ -1 +0,0 @@ -chrism@thinko.17096:1287927276
\ No newline at end of file diff --git a/pyramid/testing.py b/pyramid/testing.py index 0e24cff7c..c6695e07b 100644 --- a/pyramid/testing.py +++ b/pyramid/testing.py @@ -1,34 +1,26 @@ import copy -import types from webob import Response from zope.configuration.xmlconfig import _clearContext -from zope.deprecation import deprecated - from zope.interface import implements from zope.interface import Interface from zope.interface import alsoProvides from pyramid.interfaces import IRequest -from pyramid.interfaces import IRoutesMapper from pyramid.interfaces import ISecuredView from pyramid.interfaces import IView from pyramid.interfaces import IViewClassifier -from pyramid.interfaces import IViewPermission from pyramid.configuration import Configurator from pyramid.exceptions import Forbidden from pyramid.registry import Registry -from pyramid.security import Allowed from pyramid.security import Authenticated -from pyramid.security import Denied from pyramid.security import Everyone from pyramid.security import has_permission from pyramid.threadlocal import get_current_registry from pyramid.threadlocal import manager -from pyramid.urldispatch import RoutesMapper from pyramid.zcml import zcml_configure # API zcml_configure # prevent pyflakes from complaining @@ -183,34 +175,6 @@ def registerView(name, result='', view=None, for_=(Interface, Interface), _secure.__permitted__ = permitted return registerAdapter(_secure, for_, ISecuredView, name) -def registerViewPermission(name, result=True, viewpermission=None, - for_=(Interface, Interface)): - """ Registers a :mod:`repoze.bfg` 'view permission' object under a - name implied by the ``name`` argument. - - .. warning:: This function was deprecated in repoze.bfg 1.1; it - has no real effect in 1.2+. - """ - if result is True: - result = Allowed('message') - else: - result = Denied('message') - if viewpermission is None: - def viewpermission(context, request): - return result - return registerAdapter(viewpermission, for_, IViewPermission, name) - -deprecated('registerViewPermission', - 'registerViewPermission has been deprecated. As of repoze.bfg ' - 'version 1.1, view functions are now responsible for protecting ' - 'their own execution. A call to this function won\'t prevent a ' - 'view from being executed by the repoze.bfg router, nor ' - 'will the ``repoze.bfg.security.view_execution_permitted`` function ' - 'use the permission registered with this function. Instead,' - 'to register a view permission during testing, use the ' - '``repoze.bfg.testing.registerView`` directive with a ' - '``permission`` argument.') - def registerUtility(impl, iface=Interface, name=''): """ Register a ZCA utility component. @@ -313,28 +277,6 @@ def registerRoute(pattern, name, factory=None): config = Configurator(registry=reg) return config.add_route(name, pattern, factory=factory) -def registerRoutesMapper(root_factory=None): - """ Register a routes 'mapper' object. - - .. note:: This API was added in :mod:`repoze.bfg` version 1.1. - - .. warning:: This API is deprecated in :mod:`repoze.bfg` 1.2: - a route mapper is no longer required to be present for - successful system operation. - """ - mapper = RoutesMapper() - reg = get_current_registry() - reg.registerUtility(mapper, IRoutesMapper) - return mapper - -deprecated('registerRoutesMapper', - 'registerRoutesMapper has been deprecated. As of repoze.bfg ' - 'version 1.2, a route mapper is not required to be registered ' - 'for normal system operation; if you actually do want a route to ' - 'be registered, use the ' - '``repoze.bfg.configuration.Configurator.add_route`` ' - 'method; this will cause a route mapper to be registered also.') - def registerSettings(dictarg=None, **kw): """Register one or more 'setting' key/value pairs. A setting is a single key/value pair in the dictionary-ish object returned from diff --git a/pyramid/tests/test_testing.py b/pyramid/tests/test_testing.py index b43fea597..05f9ad518 100644 --- a/pyramid/tests/test_testing.py +++ b/pyramid/tests/test_testing.py @@ -190,34 +190,6 @@ class Test_registerView(TestBase): result = render_view_to_response(None, request, 'moo.html') self.assertEqual(result.app_iter, ['123']) - def test_registerViewPermission_defaults(self): - from zope.interface import Interface - from pyramid.interfaces import IViewPermission - from pyramid import testing - testing.registerViewPermission('moo.html') - result = self.registry.getMultiAdapter( - (Interface, Interface), IViewPermission, 'moo.html') - self.assertEqual(result, True) - - def test_registerViewPermission_denying(self): - from zope.interface import Interface - from pyramid.interfaces import IViewPermission - from pyramid import testing - testing.registerViewPermission('moo.html', result=False) - result = self.registry.getMultiAdapter( - (Interface, Interface), IViewPermission, 'moo.html') - self.assertEqual(result, False) - - def test_registerViewPermission_custom(self): - from zope.interface import Interface - from pyramid.interfaces import IViewPermission - def viewperm(context, request): - return True - from pyramid import testing - testing.registerViewPermission('moo.html', viewpermission=viewperm) - result = self.registry.getMultiAdapter( - (Interface, Interface), IViewPermission, 'moo.html') - self.assertEqual(result, True) class Test_registerAdapter(TestBase): def test_registerAdapter(self): @@ -289,14 +261,6 @@ class Test_registerRoute(TestBase): self.assertEqual(route_url('home', request, pagename='abc'), 'http://example.com/abc') -class Test_registerRoutesMapper(TestBase): - def test_registerRoutesMapper(self): - from pyramid.interfaces import IRoutesMapper - from pyramid.testing import registerRoutesMapper - result = registerRoutesMapper() - mapper = self.registry.getUtility(IRoutesMapper) - self.assertEqual(result, mapper) - class Test_registerSettings(TestBase): def test_registerSettings(self): from pyramid.interfaces import ISettings |