From a9688fb087d41d08c5bc1f645765bec6b79d71d0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 20 Jan 2011 23:51:24 -0500 Subject: add first cut of whatsnew document --- docs/whatsnew-1.0.rst | 722 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 722 insertions(+) create mode 100644 docs/whatsnew-1.0.rst (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst new file mode 100644 index 000000000..d6ceb7de3 --- /dev/null +++ b/docs/whatsnew-1.0.rst @@ -0,0 +1,722 @@ +What's New In Pyramid 1.0 +========================= + +This article explains the new features in Pyramid version 1.0 as compared to +its predecessor, :mod:`repoze.bfg` 1.3. It also documents backwards +incompatibilities between the two versions and deprecations added to Pyramid +1.0, as well as software dependency changes and notable documentation +additions. + +Major Feature Additions +----------------------- + +The major feature additions in Pyramid 1.0 are: + +- New name and branding association with the Pylons Project. + +- Paster template improvements + +- Terminology changes + +- Better platform compatibility and support + +- Direct built-in support for the Mako templating language. + +- Built-in support for sessions. + +- Updated URL dispatch features + +- Better imperative extensibility + +- ZCML externalized + +- Better support for global template variables during rendering + +- View mappers + +- Testing system improvements + +- Authentication support improvements + +- Documentation improvements + +New Name and Branding +~~~~~~~~~~~~~~~~~~~~~ + +The name of ``repoze.bfg`` has been changed to Pyramid. The project +is now branded under a new entity, "The Pylons Project". The Pylons Project +is the project name for a collection of web-framework-related technologies. +Pyramid was the first package in the Pylons Project. Other packages to the +collection have been added over time, such as support packages useful for +Pylons 1 users as well as ex-Zope users. Pyramid is the successor to both +:mod:`repoze.bfg` and :term:`Pylons` version 1. + +The Pyramid codebase is derived almost entirely from :mod:`repoze.bfg` +with some changes made for the sake of Pylons 1 compatibility. + +Pyramid is technically backwards incompatible with :mod:`repoze.bfg`, as it +has a new package name, so older imports from the ``repoze.bfg`` module will +fail if you do nothing to your existing :mod:`repoze.bfg` application. +However, you won't have to do much to use your existing BFG applications on +Pyramid. There's automation which will change most of your import statements +and ZCML declarations. See +http://docs.pylonshq.com/pyramid/dev/tutorials/bfg/index.html for upgrade +instructions. + +Pylons 1 users will need to do more work to use Pyramid, as Pyramid shares no +"DNA" with Pylons. It is hoped that over time documentation and upgrade code +will be developed to help Pylons 1 users transition to Pyramid more easily. + +:mod:`repoze.bfg` version 1.3 will be its last major release. Minor updates +will be made for critical bug fixes. Pylons version 1 will continue to see +maintenance releases, as well. + +The Repoze project will continue to exist. Repoze will be able to regain its +original focus: bringing Zope technologies to WSGI. The popularity of +:mod:`repoze.bfg` as its own web framework hindered this goal. + +We hope that people are attracted at first by the spirit of cooperation +demonstrated by the Pylons Project and the merging of development +communities. It takes humility to sacrifice a little sovereignty and work +together. The opposite, forking or splintering of projects, is much more +common in the open source world. We feel there is a limited amount of oxygen +in the space of "top-tier" Python web frameworks and we don’t do the Python +community a service by over-crowding. By merging the :mod:`repoze.bfg` and +the philosophically-similar Pylons communities, both gain an expanded +audience and a stronger chance of future success. + +Paster Template Improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Normalized all paster templates: each now uses the name ``main`` to + represent the function that returns a WSGI application, each now uses + WebError, each now has roughly the same shape of development.ini style. + +- All preexisting paster templates now use "imperative" configuration + (``starter``, ``routesalchemy``, ``alchemy``, ``zodb``). + +- The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy`` + paster templates now use a default "commit veto" hook when configuring the + ``repoze.tm2`` transaction manager in ``development.ini``. This prevents a + transaction from being committed when the response status code is within + the 400 or 500 ranges. See also + http://docs.repoze.org/tm2/#using-a-commit-veto. + +- The paster templates now have much nicer CSS and graphics. + +Terminology Changes +~~~~~~~~~~~~~~~~~~~ + +- The Pyramid concept previously known as "model" is now known as "resource". + As a result: + + - The following API changes have been made:: + + pyramid.url.model_url -> + pyramid.url.resource_url + + pyramid.traversal.find_model -> + pyramid.url.find_resource + + pyramid.traversal.model_path -> + pyramid.traversal.resource_path + + pyramid.traversal.model_path_tuple -> + pyramid.traversal.resource_path_tuple + + pyramid.traversal.ModelGraphTraverser -> + pyramid.traversal.ResourceTreeTraverser + + pyramid.config.Configurator.testing_models -> + pyramid.config.Configurator.testing_resources + + pyramid.testing.registerModels -> + pyramid.testing.registerResources + + pyramid.testing.DummyModel -> + pyramid.testing.DummyResource + + - All documentation which previously referred to "model" now refers to + "resource". + + - The ``starter`` and ``starter_zcml`` paster templates now have a + ``resources.py`` module instead of a ``models.py`` module. + + - Positional argument names of various APIs have been changed from + ``model`` to ``resource``. + + Backwards compatibility shims have been left in place in all cases. They + will continue to work "forever". + +- The Pyramid concept previously known as "resource" is now known as "asset". + As a result: + + - The (non-API) module previously known as ``pyramid.resource`` is now + known as ``pyramid.asset``. + + - All docs that previously referred to "resource specification" now refer + to "asset specification". + + - The following API changes were made:: + + pyramid.config.Configurator.absolute_resource_spec -> + pyramid.config.Configurator.absolute_asset_spec + + pyramid.config.Configurator.override_resource -> + pyramid.config.Configurator.override_asset + + - The ZCML directive previously known as ``resource`` is now known as + ``asset``. + + - The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or + ``reload_resources`` (config file) is now known, respectively, as + ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. + + Backwards compatibility shims have been left in place in all cases. + +Better Platform Compatibility and Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Make test suite pass on Jython (requires PasteScript trunk, presumably to + be 1.7.4). + +- Make test suite pass on PyPy (Chameleon doesn't work). + +Sessions +~~~~~~~~ + +- Using ``request.session`` now returns a (dictionary-like) session + object if a session factory has been configured. + +- New argument to configurator: ``session_factory``. + +- New method on configurator: ``set_session_factory`` + +- New API methods in ``pyramid.session``: ``signed_serialize`` and + ``signed_deserialize``. + +- Added flash messaging, as described in the "Flash Messaging" narrative + documentation chapter. + +- Added CSRF token generation, as described in the narrative chapter entitled + "Preventing Cross-Site Request Forgery Attacks". + +Mako +~~~~ + +- Added Mako TemplateLookup settings for ``mako.error_handler``, + ``mako.default_filters``, and ``mako.imports``. + +- New boolean Mako settings variable ``mako.strict_undefined``. See `Mako + Context Variables + `_ for + its meaning. + +URL Dispatch +~~~~~~~~~~~~ + +- URL Dispatch now allows for replacement markers to be located anywhere + in the pattern, instead of immediately following a ``/``. + +- URL Dispatch now uses the form ``{marker}`` to denote a replace marker in + the route pattern instead of ``:marker``. The old colon-style marker syntax + is still accepted for backwards compatibility. The new format allows a + regular expression for that marker location to be used instead of the + default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the + marker to be digits. + +- Add a new API ``pyramid.url.current_route_url``, which computes a URL based + on the "current" route (if any) and its matchdict values. + +- Add ``paster proute`` command which displays a summary of the routing + table. See the narrative documentation section within the "URL Dispatch" + chapter entitled "Displaying All Application Routes". + +- Added ``debug_routematch`` configuration setting that logs matched routes + (including the matchdict and predicates). + +- Add a ``pyramid.url.route_path`` API, allowing folks to generate relative + URLs. Calling ``route_path`` is the same as calling + ``pyramid.url.route_url`` with the argument ``_app_url`` equal to the empty + string. + +- Add a ``pyramid.request.Request.route_path`` API. This is a convenience + method of the request which calls ``pyramid.url.route_url``. + +- Added class vars ``matchdict`` and ``matched_route`` to + ``pyramid.request.Request``. Each is set to ``None``. + +ZCML Externalized +~~~~~~~~~~~~~~~~~ + +- The ``load_zcml`` method of a Configurator has been removed from the + Pyramid core. Loading ZCML is now a feature of the ``pyramid_zcml`` + package, which can be downloaded from PyPI. Documentation for the package + should be available via + http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how + to add a configuration statement to your ``main`` block to reobtain this + method. You will also need to add an ``install_requires`` dependency upon + ``pyramid_zcml`` to your ``setup.py`` file. + +- The ``bfg2pyramid`` script now converts ZCML include tags that have + ``repoze.bfg.includes`` as a package attribute to the value + ``pyramid_zcml``. For example, ```` + will be converted to ````. + +- The ``pyramid.includes`` subpackage has been removed. ZCML files which use + include the package ``pyramid.includes`` (e.g. ````) now must include the ``pyramid_zcml`` + package instead (e.g. ````). + +- The "Declarative Configuration" narrative chapter has been removed (it was + moved to the ``pyramid_zcml`` package). + +- Most references to ZCML in narrative chapters have been removed or + redirected to ``pyramid_zcml`` locations. + +- The ``starter_zcml`` paster template has been moved to the ``pyramid_zcml`` + package. + +- The ``make_app`` function has been removed from the ``pyramid.router`` + module. It continues life within the ``pyramid_zcml`` package. This + leaves the ``pyramid.router`` module without any API functions. + +Imperative Two-Phase Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Imperative two-phase configuration with conflict detection. + +- Add ``add_directive`` method to configurator, which allows framework + extenders to add methods to the configurator (ala ZCML directives). + +- When ``Configurator.include`` is passed a *module* as an argument, it + defaults to attempting to find and use a callable named ``includeme`` + within that module. This makes it possible to use + ``config.include('some.module')`` rather than + ``config.include('some.module.somefunc')`` as long as the include function + within ``some.module`` is named ``includeme``. + +- The new ``pyramid.config.Configurator` class has API methods that the older + ``pyramid.configuration.Configurator`` class did not: ``with_context`` (a + classmethod), ``include``, ``action``, and ``commit``. These methods exist + for imperative application extensibility purposes. + +- Surrounding application configuration with ``config.begin()`` and + ``config.end()`` is no longer necessary. All paster templates have been + changed to no longer call these functions. + +Better Support for Global Template Variables During Rendering +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- New event type: ``pyramid.interfaces.IBeforeRender``. An object of this type + is sent as an event before a renderer is invoked (but after the + application-level renderer globals factory added via + ``pyramid.configurator.configuration.set_renderer_globals_factory``, if any, + has injected its own keys). Applications may now subscribe to the + ``IBeforeRender`` event type in order to introspect the and modify the set of + renderer globals before they are passed to a renderer. The event object + iself has a dictionary-like interface that can be used for this purpose. For + example:: + + from repoze.events import subscriber + from pyramid.interfaces import IRendererGlobalsEvent + + @subscriber(IRendererGlobalsEvent) + def add_global(event): + event['mykey'] = 'foo' + + If a subscriber attempts to add a key that already exist in the renderer + globals dictionary, a ``KeyError`` is raised. This limitation is due to the + fact that subscribers cannot be ordered relative to each other. The set of + keys added to the renderer globals dictionary by all subscribers and + app-level globals factories must be unique. + +View Mappers +~~~~~~~~~~~~ + +- New constructor argument to Configurator: ``default_view_mapper``. Useful + to create systems that have alternate view calling conventions. A view + mapper allows objects that are meant to be used as view callables to have + an arbitrary argument list and an arbitrary result. The object passed as + ``default_view_mapper`` should implement the + ``pyramid.interfaces.IViewMapperFactory`` interface. + +- add a ``set_view_mapper`` API to Configurator. Has + the same result as passing ``default_view_mapper`` to the Configurator + constructor. + +- ``config.add_view`` now accepts a ``mapper`` keyword argument, which should + either be ``None``, a string representing a Python dotted name, or an + object which is an ``IViewMapperFactory``. This feature is not useful for + "civilians", only for extension writers. + +Testing Support Improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``pyramid.testing.setUp`` and ``pyramid.testing.tearDown`` have been + undeprecated. They are now the canonical setup and teardown APIs for test + configuration, replacing "direct" creation of a Configurator. This is a + change designed to provide a facade that will protect against any future + Configurator deprecations. + +- Add ``charset`` attribute to ``pyramid.testing.DummyRequest`` + (unconditionally ``UTF-8``). + +- Instances of ``pyramid.testing.DummyRequest`` now have a ``session`` + object, which is mostly a dictionary, but also implements the other session + API methods for flash and CSRF. + +- ``pyramid.testing.DummyRequest`` now has a class variable, + ``query_string``, which defaults to the empty string. + +- The ``pyramid.testing.setUp`` function now accepts an ``autocommit`` + keyword argument, which defaults to ``True``. If it is passed ``False``, + the Config object returned by ``setUp`` will be a non-autocommiting Config + object. + +Authentication Support Improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The ``pyramid.interfaces.IAuthenticationPolicy`` interface now specifies an + ``unauthenticated_userid`` method. This method supports an important + optimization required by people who are using persistent storages which do + not support object caching and whom want to create a "user object" as a + request attribute. + +- A new API has been added to the ``pyramid.security`` module named + ``unauthenticated_userid``. This API function calls the + ``unauthenticated_userid`` method of the effective security policy. + +- An ``unauthenticated_userid`` method has been added to the dummy + authentication policy returned by + ``pyramid.config.Configurator.testing_securitypolicy``. It returns the + same thing as that the dummy authentication policy's + ``authenticated_userid`` method. + +- The class ``pyramid.authentication.AuthTktCookieHelper`` is now an API. + This class can be used by third-party authentication policy developers to + help in the mechanics of authentication cookie-setting. + +- The AuthTktAuthenticationPolicy now accepts a ``tokens`` parameter via + ``pyramid.security.remember``. The value must be a sequence of strings. + Tokens are placed into the auth_tkt "tokens" field and returned in the + auth_tkt cookie. + +Documentation Improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Casey Duncan, a good friend, and an excellent technical writer has given us + the gift of professionally editing the entire Pyramid documentation set. + Any faults in the documentation are the development team's, and all + improvements are his. + +- The "Resource Location and View Lookup" chapter has been replaced with a + variant of Rob Miller's "Much Ado About Traversal" (originally published at + http://blog.nonsequitarian.org/2010/much-ado-about-traversal/). + +- Many users have contributed documentation fixes and improvements including + Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, + Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, + Joachim Krebs, Xavier Spriet, Reed O'Brien, William Chambers, Charlie + Choiniere, and Jamaludin Ahmad. + +Minor Feature Additions +----------------------- + +- The ``settings`` object which used to be available only when + ``request.settings.get_settings`` was called is now available as + ``registry.settings`` (e.g. ``request.registry.settings`` in view code). + +- ``config.add_view`` now accepts a ``decorator`` keyword argument, a callable + which will decorate the view callable before it is added to the registry. + +- Allow static renderer provided during view registration to be overridden at + request time via a request attribute named ``override_renderer``, which + should be the name of a previously registered renderer. Useful to provide + "omnipresent" RPC using existing rendered views. + +- If a resource implements a ``__resource_url__`` method, it will be called + as the result of invoking the ``pyramid.url.resource_url`` function to + generate a URL, overriding the default logic. See the new "Generating The + URL Of A Resource" section within the Resources narrative chapter. + +- The name ``registry`` is now available in a ``pshell`` environment by + default. It is the application registry object. + +- Add support for json on GAE by catching ``NotImplementedError`` and + importing simplejson from django.utils. + +- Add ``pyramid.httpexceptions`` module, which is a facade for the + ``webob.exc`` module. + +- New class: ``pyramid.response.Response``. This is a pure facade for + ``webob.Response`` (old code need not change to use this facade, it's + existence is mostly for vanity and documentation-generation purposes). + +- The request now has a new attribute: ``tmpl_context`` for benefit of + Pylons users. + +- New interface: ``pyramid.interfaces.IRendererInfo``. An object of this type + is passed to renderer factory constructors (see "Backwards + Incompatibilities"). + +- New API method: ``pyramid.settings.asbool``. + +- New API methods for ``pyramid.request.Request``: ``model_url``, + ``route_url``, and ``static_url``. These are simple passthroughs for their + respective functions in ``pyramid.url``. + +Backwards Incompatibilities +--------------------------- + +- When a ``pyramid.exceptions.Forbidden`` error is raised, its status code + now ``403 Forbidden``. It was previously ``401 Unauthorized``, for + backwards compatibility purposes with ``repoze.bfg``. This change will + cause problems for users of Pyramid with ``repoze.who``, which intercepts + ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass + through. Those deployments will need to configure ``repoze.who`` to also + react to ``403 Forbidden``. + +- ``paster bfgshell`` is now known as ``paster pshell``. + +- There is no longer an ``IDebugLogger`` registered as a named utility + with the name ``repoze.bfg.debug``. + +- The logger which used to have the name of ``repoze.bfg.debug`` now + has the name ``pyramid.debug``. + +- The deprecated API ``pyramid.testing.registerViewPermission`` + has been removed. + +- The deprecated API named ``pyramid.testing.registerRoutesMapper`` + has been removed. + +- The deprecated API named ``pyramid.request.get_request`` was removed. + +- The deprecated API named ``pyramid.security.Unauthorized`` was + removed. + +- The deprecated API named ``pyramid.view.view_execution_permitted`` + was removed. + +- The deprecated API named ``pyramid.view.NotFound`` was removed. + +- The ``bfgshell`` paster command is now named ``pshell``. + +- The Venusian "category" for all built-in Venusian decorators + (e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now + ``pyramid`` instead of ``bfg``. + +- ``pyramid.renderers.rendered_response`` function removed; use + ``render_pyramid.renderers.render_to_response`` instead. + +- Renderer factories now accept a *renderer info object* rather than an + absolute resource specification or an absolute path. The object has the + following attributes: ``name`` (the ``renderer=`` value), ``package`` (the + 'current package' when the renderer configuration statement was found), + ``type``: the renderer type, ``registry``: the current registry, and + ``settings``: the deployment settings dictionary. + + Third-party ``repoze.bfg`` renderer implementations that must be ported to + Pyramid will need to account for this. + + This change was made primarily to support more flexible Mako template + rendering. + +- The presence of the key ``repoze.bfg.message`` in the WSGI environment when + an exception occurs is now deprecated. Instead, code which relies on this + environ value should use the ``exception`` attribute of the request + (e.g. ``request.exception[0]``) to retrieve the message. + +- The values ``bfg_localizer`` and ``bfg_locale_name`` kept on the request + during internationalization for caching purposes were never APIs. These + however have changed to ``localizer`` and ``locale_name``, respectively. + +- The default ``cookie_name`` value of the ``authtktauthenticationpolicy`` ZCML + now defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). + +- The default ``cookie_name`` value of the + ``pyramid.authentication.AuthTktAuthenticationPolicy`` constructor now + defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). + +- The ``request_type`` argument to the ``view`` ZCML directive, the + ``pyramid.configuration.Configurator.add_view`` method, or the + ``pyramid.view.view_config`` decorator (nee ``bfg_view``) is no longer + permitted to be one of the strings ``GET``, ``HEAD``, ``PUT``, ``POST`` or + ``DELETE``, and now must always be an interface. Accepting the + method-strings as ``request_type`` was a backwards compatibility strategy + servicing repoze.bfg 1.0 applications. Use the ``request_method`` + parameter instead to specify that a view a string request-method predicate. + +- The ``pyramid.testing.zcml_configure`` API has been removed. It had been + advertised as removed since repoze.bfg 1.2a1, but hadn't actually been. + +- All environment variables which used to be prefixed with ``BFG_`` are now + prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now + ``PYRAMID_DEBUG_NOTFOUND``) + +- Since the ``pyramid.interfaces.IAuthenticationPolicy`` interface now + specifies that a policy implementation must implement an + ``unauthenticated_userid`` method, all third-party custom authentication + policies now must implement this method. It, however, will only be called + when the global function named ``pyramid.security.unauthenticated_userid`` + is invoked, so if you're not invoking that, you will not notice any issues. + +- The ``configure_zcml`` setting within the deployment settings (within + ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any + meaning. + +Deprecations and Behavior Differences +------------------------------------- + +- The ``pyramid.settings.get_settings`` API is now deprecated. Use + ``pyramid.threadlocals.get_current_registry().settings`` instead or use the + ``settings`` attribute of the registry available from the request + (``request.registry.settings``). + +- The decorator previously known as ``pyramid.view.bfg_view`` is now + known most formally as ``pyramid.view.view_config`` in docs and + paster templates. + +- Obtaining the ``settings`` object via + ``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, + obtain the ``settings`` object via the ``registry.settings`` attribute. A + backwards compatibility shim was added to the registry object to register + the settings object as an ISettings utility when ``setattr(registry, + 'settings', foo)`` is called, but it will be removed in a later release. + +- Obtaining the ``settings`` object via ``pyramid.settings.get_settings`` is + now deprecated. Obtain it as the ``settings`` attribute of the registry + now (obtain the registry via ``pyramid.threadlocal.get_registry`` or as + ``request.registry``). + +- ``pyramid.configuration.Configurator`` is now deprecated. Use + ``pyramid.config.Configurator``, passing its constructor + ``autocommit=True`` instead. The ``pyramid.configuration.Configurator`` + alias will live for a long time, as every application uses it, but its + import now issues a deprecation warning. The + ``pyramid.config.Configurator`` class has the same API as + ``pyramid.configuration.Configurator`` class, which it means to replace, + except by default it is a *non-autocommitting* configurator. The + now-deprecated ``pyramid.configuration.Configurator`` will autocommit every + time a configuration method is called. The ``pyramid.configuration`` + module remains, but it is deprecated. Use ``pyramid.config`` instead. + +Dependency Changes +------------------ + +- Depend on Venusian >= 0.5 (for scanning conflict exception decoration). + +Documentation Enhancements +-------------------------- + +- Added a ``pyramid.httpexceptions`` API documentation chapter. + +- Added a ``pyramid.session`` API documentation chapter. + +- Added a ``Session Objects`` narrative documentation chapter. + +- Added an API chapter for the ``pyramid.personality`` module. + +- Added an API chapter for the ``pyramid.response`` module. + +- All documentation which previously referred to ``webob.Response`` now uses + ``pyramid.response.Response`` instead. + +- The documentation has been overhauled to use imperative configuration, + moving declarative configuration (ZCML) explanations to a separate + narrative chapter ``declarative.rst``. + +- The ZODB Wiki tutorial was updated to take into account changes to the + ``pyramid_zodb`` paster template. + +- The SQL Wiki tutorial was updated to take into account changes to the + ``pyramid_routesalchemy`` paster template. + +- Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now + have a SessionFactory abstraction which competes with it, and maintaining + documentation on both ways to do it is a distraction. + +- Merged many wording, readability, and correctness changes to narrative + documentation chapters from https://github.com/caseman/pyramid (up to and + including "Models" narrative chapter). + +- "Sample Applications" section of docs changed to note existence of Cluegun, + Shootout and Virginia sample applications, ported from their repoze.bfg + origin packages. + +- Add ``pyramid.interfaces.ITemplateRenderer`` interface to Interfaces API + chapter (has ``implementation()`` method, required to be used when getting + at Chameleon macros). + +- Add a "Modifying Package Structure" section to the project narrative + documentation chapter (explain turning a module into a package). + +- Added "Debugging Route Matching" section to the urldispatch narrative + documentation chapter. + +- Added reference to ``PYRAMID_DEBUG_ROUTEMATCH`` envvar and + ``debug_routematch`` config file setting to the Environment narrative docs + chapter. + +- Direct Jython users to Mako rather than Jinja2 in "Install" narrative + chapter. + +- Added an example of ``WebTest`` functional testing to the testing narrative + chapter. + +- Rearranged chapter ordering by popular demand (URL dispatch first, then + traversal). Put hybrid chapter after views chapter. + +- Split off "Renderers" as its own chapter from "Views" chapter in narrative + documentation. + +- Added "Generating The URL Of A Resource" section to the Resources narrative + chapter (includes information about overriding URL generation using + ``__resource_url__``). + +- Added "Generating the Path To a Resource" section to the Resources + narrative chapter. + +- Added "Finding a Resource by Path" section to the Resources narrative + chapter. + +- Added "Obtaining the Lineage of a Resource" to the Resources narrative + chapter. + +- Added "Determining if a Resource is In The Lineage of Another Resource" to + Resources narrative chapter. + +- Added "Finding the Root Resource" to Resources narrative chapter. + +- Added "Finding a Resource With a Class or Interface in Lineage" to + Resources narrative chapter. + +- Added a "Flash Messaging" narrative documentation chapter. + +- Added a narrative chapter entitled "Preventing Cross-Site Request Forgery + Attacks". + +- Changed the "ZODB + Traversal Wiki Tutorial" based on changes to + ``pyramid_zodb`` Paster template. + +- Added "Advanced Configuration" narrative chapter which documents how to + deal with configuration conflicts, two-phase configuration, ``include`` and + ``commit``. + +- Add "Pyramid Provides More Than One Way to Do It" to Design Defense + documentation. + +- Added narrative documentation section within the "URL Dispatch" chapter + entitled "Displaying All Application Routes" (for ``paster proutes`` + command). + +- The (weak) "Converting a CMF Application to Pyramid" tutorial has been + removed from the tutorials section. It was moved to the + ``pyramid_tutorials`` Github repository. + +- Split views chapter into 2: View Callables and View Configuration. + +- Reorder Renderers and Templates chapters after View Callables but before + View Configuration. + -- cgit v1.2.3 From 9f85588d5b9f4a76fb499b56de824936c2c75b64 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 20 Jan 2011 23:52:36 -0500 Subject: promise less --- docs/whatsnew-1.0.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index d6ceb7de3..1baa1f5df 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -145,8 +145,7 @@ Terminology Changes - Positional argument names of various APIs have been changed from ``model`` to ``resource``. - Backwards compatibility shims have been left in place in all cases. They - will continue to work "forever". + Backwards compatibility shims have been left in place in all cases. - The Pyramid concept previously known as "resource" is now known as "asset". As a result: -- cgit v1.2.3 From ef2ce559d68bc1e7edd6542a3c6a0167ecdd9dc2 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 21 Jan 2011 01:07:05 -0500 Subject: update whatsnew --- docs/whatsnew-1.0.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 1baa1f5df..0b5d36260 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -401,6 +401,10 @@ Authentication Support Improvements Tokens are placed into the auth_tkt "tokens" field and returned in the auth_tkt cookie. +- Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults + to ``True``. If it is set to ``False``, the feature of the policy which + sets a cookie with a wilcard domain will be turned off. + Documentation Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From c88d441533c46c80d3e08572013973446308ebd5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 21 Jan 2011 04:04:45 -0500 Subject: - Added "What's New in Pyramid 1.0" chapter to HTML rendering of documentation. --- docs/whatsnew-1.0.rst | 558 ++++++++++++++++++-------------------------------- 1 file changed, 195 insertions(+), 363 deletions(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 0b5d36260..b804eebbd 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -14,6 +14,8 @@ The major feature additions in Pyramid 1.0 are: - New name and branding association with the Pylons Project. +- BFG conversion script + - Paster template improvements - Terminology changes @@ -43,8 +45,8 @@ The major feature additions in Pyramid 1.0 are: New Name and Branding ~~~~~~~~~~~~~~~~~~~~~ -The name of ``repoze.bfg`` has been changed to Pyramid. The project -is now branded under a new entity, "The Pylons Project". The Pylons Project +The name of ``repoze.bfg`` has been changed to Pyramid. The project is also +now a subproject of a new entity, "The Pylons Project". The Pylons Project is the project name for a collection of web-framework-related technologies. Pyramid was the first package in the Pylons Project. Other packages to the collection have been added over time, such as support packages useful for @@ -85,15 +87,28 @@ community a service by over-crowding. By merging the :mod:`repoze.bfg` and the philosophically-similar Pylons communities, both gain an expanded audience and a stronger chance of future success. +BFG Conversion Script +~~~~~~~~~~~~~~~~~~~~~ + +The ``bfg2pyramid`` conversion script performs a mostly automated conversion +of an existing :mod:`repoze.bfg` application to Pyramid. The process is +described in :ref:`converting_a_bfg_app`. + Paster Template Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Normalized all paster templates: each now uses the name ``main`` to - represent the function that returns a WSGI application, each now uses - WebError, each now has roughly the same shape of development.ini style. +- The paster templates now have much nicer CSS and graphics. + +- The ``development.ini`` generated by all paster templates is now configured + to use the :term:`WebError` interactive exception debugger by default. + +- All paster templates have been normalized: each now uses the name ``main`` + to represent the function that returns a WSGI application, and each now has + roughly the same shape of development.ini style. - All preexisting paster templates now use "imperative" configuration - (``starter``, ``routesalchemy``, ``alchemy``, ``zodb``). + (``starter``, ``routesalchemy``, ``alchemy``, ``zodb``) instead of ZCML + configuration. - The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy`` paster templates now use a default "commit veto" hook when configuring the @@ -102,15 +117,12 @@ Paster Template Improvements the 400 or 500 ranges. See also http://docs.repoze.org/tm2/#using-a-commit-veto. -- The paster templates now have much nicer CSS and graphics. - Terminology Changes ~~~~~~~~~~~~~~~~~~~ - The Pyramid concept previously known as "model" is now known as "resource". - As a result: - - - The following API changes have been made:: + As a result, the following API renames have been made. Backwards + compatibility shims for the old names have been left in place in all cases:: pyramid.url.model_url -> pyramid.url.resource_url @@ -136,27 +148,18 @@ Terminology Changes pyramid.testing.DummyModel -> pyramid.testing.DummyResource - - All documentation which previously referred to "model" now refers to - "resource". +- All documentation which previously referred to "model" now refers to + "resource". - - The ``starter`` and ``starter_zcml`` paster templates now have a - ``resources.py`` module instead of a ``models.py`` module. +- The ``starter`` paster template now has a resources.py`` module instead + of a ``models.py`` module. - - Positional argument names of various APIs have been changed from - ``model`` to ``resource``. - - Backwards compatibility shims have been left in place in all cases. +- Positional argument names of various APIs have been changed from + ``model`` to ``resource``. - The Pyramid concept previously known as "resource" is now known as "asset". - As a result: - - - The (non-API) module previously known as ``pyramid.resource`` is now - known as ``pyramid.asset``. - - - All docs that previously referred to "resource specification" now refer - to "asset specification". - - - The following API changes were made:: + As a result, the following API changes were made. Backwards compatibility + shims have been left in place as necessary:: pyramid.config.Configurator.absolute_resource_spec -> pyramid.config.Configurator.absolute_asset_spec @@ -164,52 +167,44 @@ Terminology Changes pyramid.config.Configurator.override_resource -> pyramid.config.Configurator.override_asset - - The ZCML directive previously known as ``resource`` is now known as - ``asset``. - - The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or - ``reload_resources`` (config file) is now known, respectively, as - ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. +- The (non-API) module previously known as ``pyramid.resource`` is now + known as ``pyramid.asset``. + +- All docs that previously referred to "resource specification" now refer + to "asset specification". - Backwards compatibility shims have been left in place in all cases. +- The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or + ``reload_resources`` (config file) is now known, respectively, as + ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. Better Platform Compatibility and Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Make test suite pass on Jython (requires PasteScript trunk, presumably to - be 1.7.4). - -- Make test suite pass on PyPy (Chameleon doesn't work). +We've made Pyramid's test suite pass on both Jython and PyPy. However, +Chameleon doesn't work on either, so you'll need to use Mako or Jinja2 +templates on these platforms. Sessions ~~~~~~~~ -- Using ``request.session`` now returns a (dictionary-like) session - object if a session factory has been configured. - -- New argument to configurator: ``session_factory``. - -- New method on configurator: ``set_session_factory`` +Pyramid now has built-in sessioning support, documented in +:ref:`sessions_chapter`. The sessioning implementation is pluggable. It +also provides flash messaging and cross-site-scripting prevention features. -- New API methods in ``pyramid.session``: ``signed_serialize`` and - ``signed_deserialize``. +Using ``request.session`` now returns a (dictionary-like) session object if +a :term:`session factory` has been configured. -- Added flash messaging, as described in the "Flash Messaging" narrative - documentation chapter. - -- Added CSRF token generation, as described in the narrative chapter entitled - "Preventing Cross-Site Request Forgery Attacks". +A new argument to the Configurator constructor exists: ``session_factory`` +and a new method on the configurator exists: +:meth:`pyramid.config.Configurator.set_session_factory`. Mako ~~~~ -- Added Mako TemplateLookup settings for ``mako.error_handler``, - ``mako.default_filters``, and ``mako.imports``. - -- New boolean Mako settings variable ``mako.strict_undefined``. See `Mako - Context Variables - `_ for - its meaning. +In addition to Chameleon templating, Pyramid now also provides built-in +support for :term:`Mako` templating. See :ref:`mako_templates` for more +information. URL Dispatch ~~~~~~~~~~~~ @@ -224,48 +219,40 @@ URL Dispatch default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the marker to be digits. -- Add a new API ``pyramid.url.current_route_url``, which computes a URL based - on the "current" route (if any) and its matchdict values. +- Addded a new API :func:`pyramid.url.current_route_url`, which computes a + URL based on the "current" route (if any) and its matchdict values. -- Add ``paster proute`` command which displays a summary of the routing - table. See the narrative documentation section within the "URL Dispatch" - chapter entitled "Displaying All Application Routes". +- Added a ``paster proute`` command which displays a summary of the routing + table. See the narrative documentation section entitled + :ref:`displaying_application_routes`. -- Added ``debug_routematch`` configuration setting that logs matched routes - (including the matchdict and predicates). +- Added ``debug_routematch`` configuration setting (settable in your ``.ini`` + file) that logs matched routes including the matchdict and predicates. -- Add a ``pyramid.url.route_path`` API, allowing folks to generate relative - URLs. Calling ``route_path`` is the same as calling - ``pyramid.url.route_url`` with the argument ``_app_url`` equal to the empty - string. +- Add a :func:`pyramid.url.route_path` API, allowing folks to generate + relative URLs. Calling ``route_path`` is the same as calling + :func:`pyramid.url.route_url` with the argument ``_app_url`` equal to the + empty string. -- Add a ``pyramid.request.Request.route_path`` API. This is a convenience - method of the request which calls ``pyramid.url.route_url``. +- Add a :meth:`pyramid.request.Request.route_path` API. This is a + convenience method of the request which calls + :func:`pyramid.url.route_url`. - Added class vars ``matchdict`` and ``matched_route`` to - ``pyramid.request.Request``. Each is set to ``None``. + :class:`pyramid.request.Request`. Each is set to ``None`` when a route + isn't matched during a request. ZCML Externalized ~~~~~~~~~~~~~~~~~ - The ``load_zcml`` method of a Configurator has been removed from the - Pyramid core. Loading ZCML is now a feature of the ``pyramid_zcml`` + Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` package, which can be downloaded from PyPI. Documentation for the package should be available via - http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how - to add a configuration statement to your ``main`` block to reobtain this + http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how to + add a configuration statement to your ``main`` block to reobtain this method. You will also need to add an ``install_requires`` dependency upon - ``pyramid_zcml`` to your ``setup.py`` file. - -- The ``bfg2pyramid`` script now converts ZCML include tags that have - ``repoze.bfg.includes`` as a package attribute to the value - ``pyramid_zcml``. For example, ```` - will be converted to ````. - -- The ``pyramid.includes`` subpackage has been removed. ZCML files which use - include the package ``pyramid.includes`` (e.g. ````) now must include the ``pyramid_zcml`` - package instead (e.g. ````). + the ``pyramid_zcml`` distribution to your ``setup.py`` file. - The "Declarative Configuration" narrative chapter has been removed (it was moved to the ``pyramid_zcml`` package). @@ -276,46 +263,34 @@ ZCML Externalized - The ``starter_zcml`` paster template has been moved to the ``pyramid_zcml`` package. -- The ``make_app`` function has been removed from the ``pyramid.router`` - module. It continues life within the ``pyramid_zcml`` package. This - leaves the ``pyramid.router`` module without any API functions. - Imperative Two-Phase Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Imperative two-phase configuration with conflict detection. - -- Add ``add_directive`` method to configurator, which allows framework - extenders to add methods to the configurator (ala ZCML directives). +To support application extensibility, the :app:`Pyramid` +:term:`Configurator`, by default, now detects configuration conflicts and +allows you to include configuration imperatively from other packages or +modules. It also, by default, performs configuration in two separate phases. +This allows you to ignore relative configuration statement ordering in some +circumstances. See :ref:`advconfig_narr` for more information. -- When ``Configurator.include`` is passed a *module* as an argument, it - defaults to attempting to find and use a callable named ``includeme`` - within that module. This makes it possible to use - ``config.include('some.module')`` rather than - ``config.include('some.module.somefunc')`` as long as the include function - within ``some.module`` is named ``includeme``. +The :meth:`pyramid.config.Configurator.add_directive` allows framework +extenders to add methods to the configurator, which allows extenders to avoid +subclassing a Configurator just to add methods. See :ref:`add_directive` for +more info. -- The new ``pyramid.config.Configurator` class has API methods that the older - ``pyramid.configuration.Configurator`` class did not: ``with_context`` (a - classmethod), ``include``, ``action``, and ``commit``. These methods exist - for imperative application extensibility purposes. - -- Surrounding application configuration with ``config.begin()`` and - ``config.end()`` is no longer necessary. All paster templates have been - changed to no longer call these functions. +Surrounding application configuration with ``config.begin()`` and +``config.end()`` is no longer necessary. All paster templates have been +changed to no longer call these functions. Better Support for Global Template Variables During Rendering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- New event type: ``pyramid.interfaces.IBeforeRender``. An object of this type - is sent as an event before a renderer is invoked (but after the - application-level renderer globals factory added via - ``pyramid.configurator.configuration.set_renderer_globals_factory``, if any, - has injected its own keys). Applications may now subscribe to the - ``IBeforeRender`` event type in order to introspect the and modify the set of - renderer globals before they are passed to a renderer. The event object - iself has a dictionary-like interface that can be used for this purpose. For - example:: +A new event type named :class:`pyramid.interfaces.IBeforeRender` is now sent +as an event before a renderer is invoked. Applications may now subscribe to +the ``IBeforeRender`` event type in order to introspect the and modify the +set of renderer globals before they are passed to a renderer. The event +object iself has a dictionary-like interface that can be used for this +purpose. For example:: from repoze.events import subscriber from pyramid.interfaces import IRendererGlobalsEvent @@ -324,84 +299,47 @@ Better Support for Global Template Variables During Rendering def add_global(event): event['mykey'] = 'foo' - If a subscriber attempts to add a key that already exist in the renderer - globals dictionary, a ``KeyError`` is raised. This limitation is due to the - fact that subscribers cannot be ordered relative to each other. The set of - keys added to the renderer globals dictionary by all subscribers and - app-level globals factories must be unique. - View Mappers ~~~~~~~~~~~~ -- New constructor argument to Configurator: ``default_view_mapper``. Useful - to create systems that have alternate view calling conventions. A view - mapper allows objects that are meant to be used as view callables to have - an arbitrary argument list and an arbitrary result. The object passed as - ``default_view_mapper`` should implement the - ``pyramid.interfaces.IViewMapperFactory`` interface. - -- add a ``set_view_mapper`` API to Configurator. Has - the same result as passing ``default_view_mapper`` to the Configurator - constructor. - -- ``config.add_view`` now accepts a ``mapper`` keyword argument, which should - either be ``None``, a string representing a Python dotted name, or an - object which is an ``IViewMapperFactory``. This feature is not useful for - "civilians", only for extension writers. +A "view mapper" subsystem has been extracted, which allows framework +extenders to control how view callables are constructed and called. This +feature is not useful for "civilians", only for extension writers. See +:ref:`using_a_view_mapper` for more information. Testing Support Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``pyramid.testing.setUp`` and ``pyramid.testing.tearDown`` have been - undeprecated. They are now the canonical setup and teardown APIs for test - configuration, replacing "direct" creation of a Configurator. This is a - change designed to provide a facade that will protect against any future - Configurator deprecations. - -- Add ``charset`` attribute to ``pyramid.testing.DummyRequest`` - (unconditionally ``UTF-8``). - -- Instances of ``pyramid.testing.DummyRequest`` now have a ``session`` - object, which is mostly a dictionary, but also implements the other session - API methods for flash and CSRF. - -- ``pyramid.testing.DummyRequest`` now has a class variable, - ``query_string``, which defaults to the empty string. - -- The ``pyramid.testing.setUp`` function now accepts an ``autocommit`` - keyword argument, which defaults to ``True``. If it is passed ``False``, - the Config object returned by ``setUp`` will be a non-autocommiting Config - object. +The :func:`pyramid.testing.setUp`` and :func:`pyramid.testing.tearDown` APIs +have been undeprecated. They are now the canonical setup and teardown APIs +for test configuration, replacing "direct" creation of a Configurator. This +is a change designed to provide a facade that will protect against any future +Configurator deprecations. Authentication Support Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The ``pyramid.interfaces.IAuthenticationPolicy`` interface now specifies an - ``unauthenticated_userid`` method. This method supports an important - optimization required by people who are using persistent storages which do - not support object caching and whom want to create a "user object" as a - request attribute. +- The :class:`pyramid.interfaces.IAuthenticationPolicy` interface now + specifies an ``unauthenticated_userid`` method. This method supports an + important optimization required by people who are using persistent storages + which do not support object caching and whom want to create a "user object" + as a request attribute. -- A new API has been added to the ``pyramid.security`` module named +- A new API has been added to the :mod:`pyramid.security` module named ``unauthenticated_userid``. This API function calls the ``unauthenticated_userid`` method of the effective security policy. -- An ``unauthenticated_userid`` method has been added to the dummy - authentication policy returned by - ``pyramid.config.Configurator.testing_securitypolicy``. It returns the - same thing as that the dummy authentication policy's - ``authenticated_userid`` method. +- The class :class:`pyramid.authentication.AuthTktCookieHelper` is now an + API. This class can be used by third-party authentication policy + developers to help in the mechanics of authentication cookie-setting. -- The class ``pyramid.authentication.AuthTktCookieHelper`` is now an API. - This class can be used by third-party authentication policy developers to - help in the mechanics of authentication cookie-setting. +- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now accepts + a ``tokens`` parameter via :func:`pyramid.security.remember`. The value + must be a sequence of strings. Tokens are placed into the auth_tkt + "tokens" field and returned in the auth_tkt cookie. -- The AuthTktAuthenticationPolicy now accepts a ``tokens`` parameter via - ``pyramid.security.remember``. The value must be a sequence of strings. - Tokens are placed into the auth_tkt "tokens" field and returned in the - auth_tkt cookie. - -- Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults +- Added a ``wild_domain`` argument to + :class:`pyramid.authentication.AuthTktAuthenticationPolicy`, which defaults to ``True``. If it is set to ``False``, the feature of the policy which sets a cookie with a wilcard domain will be turned off. @@ -426,12 +364,13 @@ Documentation Improvements Minor Feature Additions ----------------------- -- The ``settings`` object which used to be available only when - ``request.settings.get_settings`` was called is now available as - ``registry.settings`` (e.g. ``request.registry.settings`` in view code). +- The ``settings`` dictionary passed to the Configurator is now available as + ``config.registry.settings`` in configuration code and + ``request.registry.settings`` in view code). -- ``config.add_view`` now accepts a ``decorator`` keyword argument, a callable - which will decorate the view callable before it is added to the registry. +- :meth:`pyramid.config.Configurator.add_view` now accepts a ``decorator`` + keyword argument, a callable which will decorate the view callable before + it is added to the registry. - Allow static renderer provided during view registration to be overridden at request time via a request attribute named ``override_renderer``, which @@ -439,92 +378,69 @@ Minor Feature Additions "omnipresent" RPC using existing rendered views. - If a resource implements a ``__resource_url__`` method, it will be called - as the result of invoking the ``pyramid.url.resource_url`` function to - generate a URL, overriding the default logic. See the new "Generating The - URL Of A Resource" section within the Resources narrative chapter. + as the result of invoking the :func:`pyramid.url.resource_url` function to + generate a URL, overriding the default logic. See + :ref:`generating_the_url_of_a_resource` for more information. - The name ``registry`` is now available in a ``pshell`` environment by default. It is the application registry object. -- Add support for json on GAE by catching ``NotImplementedError`` and - importing simplejson from django.utils. +- Added support for json on Google App Engine by catching + :exc:`NotImplementedError` and importing ``simplejson`` from + ``django.utils``. -- Add ``pyramid.httpexceptions`` module, which is a facade for the +- Added the :mod:`pyramid.httpexceptions` module, which is a facade for the ``webob.exc`` module. -- New class: ``pyramid.response.Response``. This is a pure facade for +- New class: :class:`pyramid.response.Response`. This is a pure facade for ``webob.Response`` (old code need not change to use this facade, it's existence is mostly for vanity and documentation-generation purposes). - The request now has a new attribute: ``tmpl_context`` for benefit of Pylons users. -- New interface: ``pyramid.interfaces.IRendererInfo``. An object of this type - is passed to renderer factory constructors (see "Backwards - Incompatibilities"). - -- New API method: ``pyramid.settings.asbool``. - -- New API methods for ``pyramid.request.Request``: ``model_url``, +- New API methods for :class:`pyramid.request.Request`: ``model_url``, ``route_url``, and ``static_url``. These are simple passthroughs for their - respective functions in ``pyramid.url``. + respective functions in :mod:`pyramid.url`. Backwards Incompatibilities --------------------------- -- When a ``pyramid.exceptions.Forbidden`` error is raised, its status code - now ``403 Forbidden``. It was previously ``401 Unauthorized``, for - backwards compatibility purposes with ``repoze.bfg``. This change will - cause problems for users of Pyramid with ``repoze.who``, which intercepts - ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass - through. Those deployments will need to configure ``repoze.who`` to also - react to ``403 Forbidden``. +- When a :class:`pyramid.exceptions.Forbidden` error is raised, its status + code now ``403 Forbidden``. It was previously ``401 Unauthorized``, for + backwards compatibility purposes with :mod:`repoze.bfg`. This change will + cause problems for users of Pyramid with :mod:`repoze.who`, which + intercepts ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to + pass through. Those deployments will need to configure :mod:`repoze.who` + to also react to ``403 Forbidden``. -- ``paster bfgshell`` is now known as ``paster pshell``. +- The ``paster bfgshell`` command is now known as ``paster pshell``. -- There is no longer an ``IDebugLogger`` registered as a named utility +- There is no longer an ``IDebugLogger`` object registered as a named utility with the name ``repoze.bfg.debug``. -- The logger which used to have the name of ``repoze.bfg.debug`` now - has the name ``pyramid.debug``. - -- The deprecated API ``pyramid.testing.registerViewPermission`` - has been removed. - -- The deprecated API named ``pyramid.testing.registerRoutesMapper`` - has been removed. - -- The deprecated API named ``pyramid.request.get_request`` was removed. - -- The deprecated API named ``pyramid.security.Unauthorized`` was - removed. - -- The deprecated API named ``pyramid.view.view_execution_permitted`` - was removed. - -- The deprecated API named ``pyramid.view.NotFound`` was removed. - -- The ``bfgshell`` paster command is now named ``pshell``. +- These deprecated APIs have been removed: + ``pyramid.testing.registerViewPermission``, + ``pyramid.testing.registerRoutesMapper``, ``pyramid.request.get_request``, + ``pyramid.security.Unauthorized``, + ``pyramid.view.view_execution_permitted``, ``pyramid.view.NotFound`` - The Venusian "category" for all built-in Venusian decorators (e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now ``pyramid`` instead of ``bfg``. -- ``pyramid.renderers.rendered_response`` function removed; use - ``render_pyramid.renderers.render_to_response`` instead. +- The ``pyramid.renderers.rendered_response`` function removed; use + :func:`pyramid.renderers.render_to_response` instead. - Renderer factories now accept a *renderer info object* rather than an absolute resource specification or an absolute path. The object has the following attributes: ``name`` (the ``renderer=`` value), ``package`` (the 'current package' when the renderer configuration statement was found), ``type``: the renderer type, ``registry``: the current registry, and - ``settings``: the deployment settings dictionary. - - Third-party ``repoze.bfg`` renderer implementations that must be ported to - Pyramid will need to account for this. - - This change was made primarily to support more flexible Mako template - rendering. + ``settings``: the deployment settings dictionary. Third-party + ``repoze.bfg`` renderer implementations that must be ported to Pyramid will + need to account for this. This change was made primarily to support more + flexible Mako template rendering. - The presence of the key ``repoze.bfg.message`` in the WSGI environment when an exception occurs is now deprecated. Instead, code which relies on this @@ -535,51 +451,57 @@ Backwards Incompatibilities during internationalization for caching purposes were never APIs. These however have changed to ``localizer`` and ``locale_name``, respectively. -- The default ``cookie_name`` value of the ``authtktauthenticationpolicy`` ZCML - now defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). - - The default ``cookie_name`` value of the - ``pyramid.authentication.AuthTktAuthenticationPolicy`` constructor now - defaults to ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). - -- The ``request_type`` argument to the ``view`` ZCML directive, the - ``pyramid.configuration.Configurator.add_view`` method, or the - ``pyramid.view.view_config`` decorator (nee ``bfg_view``) is no longer - permitted to be one of the strings ``GET``, ``HEAD``, ``PUT``, ``POST`` or - ``DELETE``, and now must always be an interface. Accepting the - method-strings as ``request_type`` was a backwards compatibility strategy - servicing repoze.bfg 1.0 applications. Use the ``request_method`` - parameter instead to specify that a view a string request-method predicate. + :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now defaults to + ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). -- The ``pyramid.testing.zcml_configure`` API has been removed. It had been - advertised as removed since repoze.bfg 1.2a1, but hadn't actually been. +- The :func:`pyramid.testing.zcml_configure` API has been removed. It had + been advertised as removed since :mod:`repoze.bfg` 1.2a1, but hadn't + actually been. - All environment variables which used to be prefixed with ``BFG_`` are now prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now ``PYRAMID_DEBUG_NOTFOUND``) -- Since the ``pyramid.interfaces.IAuthenticationPolicy`` interface now +- Since the :class:`pyramid.interfaces.IAuthenticationPolicy` interface now specifies that a policy implementation must implement an ``unauthenticated_userid`` method, all third-party custom authentication policies now must implement this method. It, however, will only be called - when the global function named ``pyramid.security.unauthenticated_userid`` - is invoked, so if you're not invoking that, you will not notice any issues. + when the global function named + :func:`pyramid.security.unauthenticated_userid` is invoked, so if you're + not invoking that, you will not notice any issues. - The ``configure_zcml`` setting within the deployment settings (within ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any meaning. +- The ``make_app`` function has been removed from the :mod:`pyramid.router` + module. It continues life within the ``pyramid_zcml`` package. This + leaves the :mod:`pyramid.router` module without any API functions. + Deprecations and Behavior Differences ------------------------------------- -- The ``pyramid.settings.get_settings`` API is now deprecated. Use +- :class:`pyramid.configuration.Configurator` is now deprecated. Use + :class:`pyramid.config.Configurator`, passing its constructor + ``autocommit=True`` instead. The + :class:`pyramid.configuration.Configurator` alias will live for a long + time, as every application uses it, but its import now issues a deprecation + warning. The :class:`pyramid.config.Configurator` class has the same API + as the :class:`pyramid.configuration.Configurator` class, which it means to + replace, except by default it is a *non-autocommitting* configurator. The + now-deprecated ``pyramid.configuration.Configurator`` will autocommit every + time a configuration method is called. The :mod:`pyramid.configuration` + module remains, but it is deprecated. Use :mod:`pyramid.config` instead. + +- The :func:`pyramid.settings.get_settings` API is now deprecated. Use ``pyramid.threadlocals.get_current_registry().settings`` instead or use the ``settings`` attribute of the registry available from the request (``request.registry.settings``). -- The decorator previously known as ``pyramid.view.bfg_view`` is now - known most formally as ``pyramid.view.view_config`` in docs and - paster templates. +- The decorator previously known as ``pyramid.view.bfg_view`` is now known + most formally as :class:`pyramid.view.view_config` in docs and paster + templates. - Obtaining the ``settings`` object via ``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, @@ -588,22 +510,10 @@ Deprecations and Behavior Differences the settings object as an ISettings utility when ``setattr(registry, 'settings', foo)`` is called, but it will be removed in a later release. -- Obtaining the ``settings`` object via ``pyramid.settings.get_settings`` is - now deprecated. Obtain it as the ``settings`` attribute of the registry - now (obtain the registry via ``pyramid.threadlocal.get_registry`` or as - ``request.registry``). - -- ``pyramid.configuration.Configurator`` is now deprecated. Use - ``pyramid.config.Configurator``, passing its constructor - ``autocommit=True`` instead. The ``pyramid.configuration.Configurator`` - alias will live for a long time, as every application uses it, but its - import now issues a deprecation warning. The - ``pyramid.config.Configurator`` class has the same API as - ``pyramid.configuration.Configurator`` class, which it means to replace, - except by default it is a *non-autocommitting* configurator. The - now-deprecated ``pyramid.configuration.Configurator`` will autocommit every - time a configuration method is called. The ``pyramid.configuration`` - module remains, but it is deprecated. Use ``pyramid.config`` instead. +- Obtaining the ``settings`` object via :func:`pyramid.settings.get_settings` + is now deprecated. Obtain it instead as the ``settings`` attribute of the + registry now (obtain the registry via + :func:`pyramid.threadlocal.get_registry` or as ``request.registry``). Dependency Changes ------------------ @@ -613,113 +523,35 @@ Dependency Changes Documentation Enhancements -------------------------- -- Added a ``pyramid.httpexceptions`` API documentation chapter. +- Added a :mod:`pyramid.httpexceptions` API documentation chapter. -- Added a ``pyramid.session`` API documentation chapter. +- Added a :mod:`pyramid.session` API documentation chapter. -- Added a ``Session Objects`` narrative documentation chapter. +- Added an API chapter for the :mod:`pyramid.response` module. -- Added an API chapter for the ``pyramid.personality`` module. - -- Added an API chapter for the ``pyramid.response`` module. +- Added a :ref:`sessions_chapter` narrative documentation chapter. - All documentation which previously referred to ``webob.Response`` now uses - ``pyramid.response.Response`` instead. + :class:`pyramid.response.Response` instead. - The documentation has been overhauled to use imperative configuration, - moving declarative configuration (ZCML) explanations to a separate - narrative chapter ``declarative.rst``. - -- The ZODB Wiki tutorial was updated to take into account changes to the - ``pyramid_zodb`` paster template. - -- The SQL Wiki tutorial was updated to take into account changes to the - ``pyramid_routesalchemy`` paster template. + moving declarative configuration (ZCML) explanations to an external + package, :term:`pyramid_zcml`. - Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now have a SessionFactory abstraction which competes with it, and maintaining documentation on both ways to do it is a distraction. -- Merged many wording, readability, and correctness changes to narrative - documentation chapters from https://github.com/caseman/pyramid (up to and - including "Models" narrative chapter). - -- "Sample Applications" section of docs changed to note existence of Cluegun, - Shootout and Virginia sample applications, ported from their repoze.bfg - origin packages. - -- Add ``pyramid.interfaces.ITemplateRenderer`` interface to Interfaces API - chapter (has ``implementation()`` method, required to be used when getting - at Chameleon macros). - -- Add a "Modifying Package Structure" section to the project narrative - documentation chapter (explain turning a module into a package). - -- Added "Debugging Route Matching" section to the urldispatch narrative - documentation chapter. - -- Added reference to ``PYRAMID_DEBUG_ROUTEMATCH`` envvar and - ``debug_routematch`` config file setting to the Environment narrative docs - chapter. - -- Direct Jython users to Mako rather than Jinja2 in "Install" narrative - chapter. - - Added an example of ``WebTest`` functional testing to the testing narrative - chapter. - -- Rearranged chapter ordering by popular demand (URL dispatch first, then - traversal). Put hybrid chapter after views chapter. - -- Split off "Renderers" as its own chapter from "Views" chapter in narrative - documentation. - -- Added "Generating The URL Of A Resource" section to the Resources narrative - chapter (includes information about overriding URL generation using - ``__resource_url__``). - -- Added "Generating the Path To a Resource" section to the Resources - narrative chapter. - -- Added "Finding a Resource by Path" section to the Resources narrative - chapter. - -- Added "Obtaining the Lineage of a Resource" to the Resources narrative - chapter. + chapter at :ref:`functional_tests`. -- Added "Determining if a Resource is In The Lineage of Another Resource" to - Resources narrative chapter. - -- Added "Finding the Root Resource" to Resources narrative chapter. - -- Added "Finding a Resource With a Class or Interface in Lineage" to - Resources narrative chapter. - -- Added a "Flash Messaging" narrative documentation chapter. - -- Added a narrative chapter entitled "Preventing Cross-Site Request Forgery - Attacks". - -- Changed the "ZODB + Traversal Wiki Tutorial" based on changes to - ``pyramid_zodb`` Paster template. - -- Added "Advanced Configuration" narrative chapter which documents how to - deal with configuration conflicts, two-phase configuration, ``include`` and - ``commit``. +- Extended the Resources chapter with examples of calls to resource-related + APIs. - Add "Pyramid Provides More Than One Way to Do It" to Design Defense documentation. -- Added narrative documentation section within the "URL Dispatch" chapter - entitled "Displaying All Application Routes" (for ``paster proutes`` - command). - - The (weak) "Converting a CMF Application to Pyramid" tutorial has been removed from the tutorials section. It was moved to the ``pyramid_tutorials`` Github repository. -- Split views chapter into 2: View Callables and View Configuration. - -- Reorder Renderers and Templates chapters after View Callables but before - View Configuration. - -- cgit v1.2.3 From 6482f7bc2891d51916237f763c80b6f50f5039a1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 24 Jan 2011 23:17:49 -0500 Subject: stray tilde --- docs/whatsnew-1.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index b804eebbd..5d7167908 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -310,7 +310,7 @@ feature is not useful for "civilians", only for extension writers. See Testing Support Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`pyramid.testing.setUp`` and :func:`pyramid.testing.tearDown` APIs +The :func:`pyramid.testing.setUp` and :func:`pyramid.testing.tearDown` APIs have been undeprecated. They are now the canonical setup and teardown APIs for test configuration, replacing "direct" creation of a Configurator. This is a change designed to provide a facade that will protect against any future -- cgit v1.2.3 From d3a028f3eab91f9bb26761af59fa1d71085a2921 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 25 Jan 2011 01:28:09 -0500 Subject: add example of reconfiguring challenge decider for r.who users --- docs/whatsnew-1.0.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 5d7167908..91253b29b 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -412,7 +412,15 @@ Backwards Incompatibilities cause problems for users of Pyramid with :mod:`repoze.who`, which intercepts ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass through. Those deployments will need to configure :mod:`repoze.who` - to also react to ``403 Forbidden``. + to also react to ``403 Forbidden``. To do so, use a repoze.who + ``challenge_decider`` that looks like this:: + + import zope.interface + from repoze.who.interfaces import IChallengeDecider + + def challenge_decider(environ, status, headers): + return status.startswith('403') or status.startswith('401') + zope.interface.directlyProvides(challenge_decider, IChallengeDecider) - The ``paster bfgshell`` command is now known as ``paster pshell``. -- cgit v1.2.3 From a2b9b6895eed73e0cf1733587005bbb69df0330f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 30 Jan 2011 15:06:09 -0500 Subject: add notes about documentation changes --- docs/whatsnew-1.0.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 91253b29b..4df1946a1 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -561,5 +561,17 @@ Documentation Enhancements - The (weak) "Converting a CMF Application to Pyramid" tutorial has been removed from the tutorials section. It was moved to the - ``pyramid_tutorials`` Github repository. + ``pyramid_tutorials`` Github repository at + http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/. + +- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" + tutorials out of core documentation and into the Pyramid Tutorials site + (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/). + +- Removed API documentation for deprecated ``pyramid.testing`` APIs named + ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, + ``registerEventListener``, ``registerTemplateRenderer``, + ``registerDummyRenderer``, ``registerView``, ``registerUtility``, + ``registerAdapter``, ``registerSubscriber``, ``registerRoute``, and + ``registerSettings``. -- cgit v1.2.3 From 754f1d627ef0c7210a0b1fa1c297b6ea46391899 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 31 Jan 2011 09:15:44 -0500 Subject: rendering --- docs/whatsnew-1.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/whatsnew-1.0.rst') diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 4df1946a1..4a41840eb 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -151,7 +151,7 @@ Terminology Changes - All documentation which previously referred to "model" now refers to "resource". -- The ``starter`` paster template now has a resources.py`` module instead +- The ``starter`` paster template now has a ``resources.py`` module instead of a ``models.py`` module. - Positional argument names of various APIs have been changed from -- cgit v1.2.3