diff options
Diffstat (limited to 'docs/narr')
| -rw-r--r-- | docs/narr/configuration.rst | 20 | ||||
| -rw-r--r-- | docs/narr/extending.rst | 6 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 2 | ||||
| -rw-r--r-- | docs/narr/project.rst | 15 | ||||
| -rw-r--r-- | docs/narr/security.rst | 6 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 22 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 24 | ||||
| -rw-r--r-- | docs/narr/views.rst | 104 | ||||
| -rw-r--r-- | docs/narr/webob.rst | 6 |
9 files changed, 114 insertions, 91 deletions
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index fe55705bb..a62cf76ff 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -254,7 +254,7 @@ application. This error will contain information about which tags might have conflicted. .. index:: - single: bfg_view + single: view_config single: ZCML view directive single: configuration decoration single: code scanning @@ -277,10 +277,10 @@ referred to by the declaration itself. For example: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config from webob import Response - @bfg_view(name='hello', request_method='GET') + @view_config(name='hello', request_method='GET') def hello(request): return Response('Hello') @@ -290,7 +290,7 @@ the configuration of a :mod:`pyramid` application, a configuration decoration within application code must be found through a process known as a :term:`scan`. -The :class:`pyramid.view.bfg_view` decorator above adds an +The :class:`pyramid.view.view_config` decorator above adds an attribute to the ``hello`` function, making it available for a :term:`scan` to find it later. @@ -306,10 +306,10 @@ and its subpackages. For example: :linenos: from paste.httpserver import serve - from pyramid.view import bfg_view + from pyramid.view import view_config from webob import Response - @bfg_view() + @view_config() def hello(request): return Response('Hello') @@ -334,10 +334,10 @@ directive, the package the ZCML file points to is scanned. # helloworld.py from paste.httpserver import serve - from pyramid.view import bfg_view + from pyramid.view import view_config from webob import Response - @bfg_view() + @view_config() def hello(request): return Response('Hello') @@ -366,7 +366,7 @@ The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects defined within a module. These special attributes are typically attached to code via the use of a :term:`decorator`. For -example, the :class:`pyramid.view.bfg_view` decorator can be +example, the :class:`pyramid.view.view_config` decorator can be attached to a function or instance method. Once scanning is invoked, and :term:`configuration decoration` is @@ -375,7 +375,7 @@ found by the scanner, a set of calls are made to a the intent of the configuration decoration. In the example above, this is best represented as the scanner -translating the arguments to :class:`pyramid.view.bfg_view` into a +translating the arguments to :class:`pyramid.view.view_config` into a call to the :meth:`pyramid.configuration.Configurator.add_view` method, effectively: diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 490d0733f..88b42eabf 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -39,7 +39,7 @@ The fundamental "plug points" of an application developed using :mod:`pyramid` are *routes*, *views*, and *resources*. Routes are declarations made using the ZCML ``<route>`` directive. Views are declarations made using the ZCML ``<view>`` directive (or the -``@bfg_view`` decorator). Resources are files that are accessed by +``@view_config`` decorator). Resources are files that are accessed by :mod:`pyramid` using the :term:`pkg_resources` API such as static files and templates. @@ -89,7 +89,7 @@ Extending an Application Which Possesses Configuration Decorators Or Which Does ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you've inherited a :mod:`pyramid` application which uses -:class:`pyramid.view.bfg_view` decorators or which performs +:class:`pyramid.view.view_config` decorators or which performs configuration imperatively, one of two things may be true: - If you just want to *extend* the application, you can write @@ -101,7 +101,7 @@ configuration imperatively, one of two things may be true: *may* need to change the source code of the original application. If the only source of trouble is the existence of - :class:`pyramid.view.bfg_view` decorators, you can just prevent a + :class:`pyramid.view.view_config` decorators, you can just prevent a :term:`scan` from happening (by omitting the ``<scan>`` declaration from ZCML or omitting any call to the :meth:`pyramid.configuration.Configurator.scan` method). This diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index db933c525..12c1cd0aa 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -556,7 +556,7 @@ subscriber of a :class:`pyramid.interfaces.INewRequest` event). Registering Configuration Decorators ------------------------------------ -Decorators such as :class:`pyramid.view.bfg_view` don't change the +Decorators such as :class:`pyramid.view.view_config` don't change the behavior of the functions or classes they're decorating. Instead, when a :term:`scan` is performed, a modified version of the function or class is registered with :mod:`pyramid`. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 0e18f0924..f88496fcc 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -21,6 +21,9 @@ templates". single: pyramid_zodb paster template single: pyramid_alchemy paster template single: pyramid_routesalchemy paster template + single: pylons_minimal paster template + single: pylons_basic paster template + single: pylons_sqla paster template .. _additional_paster_templates: @@ -52,6 +55,18 @@ The included templates are these: URL mapping via :term:`traversal` and persistence via :term:`SQLAlchemy` +``pylons_minimal`` + URL mapping via :term:`URL dispatch` and Pylons-style view handlers, + minimal setup. + +``pylons_basic`` + URL mapping via :term:`URL dispatch` and Pylons-style view handlers, + and some extra functionality. + +``pylons_sqla`` + URL mapping via :term:`URL dispatch` and Pylons-style view handlers, + some extra functionality, and SQLAlchemy set up. + Each of these project templates uses :term:`ZCML` instead of :term:`imperative configuration`. Each also makes the assumption that you want your code to live in a Python :term:`package`. Even if your diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 5782837aa..63d1cad25 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -181,16 +181,16 @@ For example, the following declaration protects the view named /> The equivalent view registration including the ``add`` permission name -may be performed via the ``@bfg_view`` decorator: +may be performed via the ``@view_config`` decorator: .. ignore-next-block .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config from models import Blog - @bfg_view(context=Blog, name='add_entry.html', permission='add') + @view_config(context=Blog, name='add_entry.html', permission='add') def blog_entry_add_view(request): """ Add blog entry code goes here """ pass diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index e460e2d74..df164e684 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -88,9 +88,6 @@ two extra methods. Extra attributes: -``modified`` - An integer timestamp indicating the last time the session was modified. - ``created`` An integer timestamp indicating the time that this session was created. @@ -130,13 +127,24 @@ Some gotchas: When in doubt, call ``changed()`` after you've changed sessioning data. +.. index:: + single: pyramid_beaker + single: Beaker + Using Alternate Session Factories --------------------------------- -At the time of this writing, alternate session factories don't yet -exist. It is our intent that we will soon provide at least one other -session factory which will be easily installable: one that uses the -`Beaker <http://beaker.groovie.org/>`_ library as a backend. +At the time of this writing, exactly one alternate session factory +implementation exists, named ``pyramid_beaker``. This is a session +factory that uses the `Beaker <http://beaker.groovie.org/>`_ library +as a backend. Beaker has support for file-based sessions, database +based sessions, and encrypted cookie-based sessions. See +`http://github.com/Pylons/pyramid_beaker +<http://github.com/Pylons/pyramid_beaker>`_ for more information about +``pyramid_beaker``. + +.. index:: + single: session factory Creating Your Own Session Factory --------------------------------- diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 0650480af..57d1bc3b9 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -285,16 +285,16 @@ The association of a template as a renderer for a :term:`view configuration` makes it possible to replace code within a :term:`view callable` that handles the rendering of a template. -Here's an example of using a :class:`pyramid.view.bfg_view` +Here's an example of using a :class:`pyramid.view.view_config` decorator to specify a :term:`view configuration` that names a template renderer: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='templates/foo.pt') + @view_config(renderer='templates/foo.pt') def my_view(request): return {'foo':1, 'bar':2} @@ -310,7 +310,7 @@ Similar renderer configuration can be done imperatively and via :term:`ZCML`. See :ref:`views_which_use_a_renderer`. See also :ref:`built_in_renderers`. -The ``renderer`` argument to the ``@bfg_view`` configuration decorator +The ``renderer`` argument to the ``@view_config`` configuration decorator shown above is the template *path*. In the example above, the path ``templates/foo.pt`` is *relative*. Relative to what, you ask? Relative to the directory in which the file which defines the view @@ -347,7 +347,7 @@ of :term:`Jinja2` templates as renderers. See configuration typically return a dictionary, and making assertions about the information is almost always more direct than needing to parse HTML. Specifying a renderer from within :term:`ZCML` (as - opposed to imperatively or via a ``bfg_view`` decorator, or using a + opposed to imperatively or via a ``view_config`` decorator, or using a template directly from within a view callable) also makes it possible for someone to modify the template used to render a view without needing to fork your code to do so. See @@ -401,9 +401,9 @@ the template as a :term:`renderer` like so: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='templates/foo.pt') + @view_config(renderer='templates/foo.pt') def my_view(request): return {'foo':1, 'bar':2} @@ -467,16 +467,16 @@ the macro itself) *into* the rendered template. To make a macro available to the rendered template, you can retrieve a different template using the :func:`pyramid.renderers.get_renderer` API, and pass it in to the template being rendered. For example, using a -:term:`view configuration` via a :class:`pyramid.view.bfg_view` +:term:`view configuration` via a :class:`pyramid.view.view_config` decorator that uses a :term:`renderer`: .. code-block:: python :linenos: from pyramid.renderers import get_renderer - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='templates/mytemplate.pt') + @view_config(renderer='templates/mytemplate.pt') def my_view(request): main = get_renderer('templates/master.pt').implementation() return {'main':main} @@ -534,9 +534,9 @@ which renders this template: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='templates/mytemplate.txt') + @view_config(renderer='templates/mytemplate.txt') def my_view(request): return {'name':'world'} diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 2969487d3..39115a493 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -255,9 +255,9 @@ Response interface, :mod:`pyramid` will attempt to use a :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='json') + @view_config(renderer='json') def hello_world(request): return {'content':'Hello!'} @@ -266,7 +266,7 @@ dictionary does not implement the :term:`WebOb` response interface, so you might believe that this example would fail. However, since a ``renderer`` is associated with the view callable through its :term:`view configuration` (in this case, using a ``renderer`` -argument passed to :func:`pyramid.view.bfg_view`), if the view does +argument passed to :func:`pyramid.view.view_config`), if the view does *not* return a Response object, the renderer will attempt to convert the result of the view to a response on the developer's behalf. Of course, if no renderer is associated with a view's configuration, @@ -411,9 +411,9 @@ representation of the dictionary: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='string') + @view_config(renderer='string') def hello_world(request): return {'content':'Hello!'} @@ -450,9 +450,9 @@ view will render the returned dictionary to a JSON serialization: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='json') + @view_config(renderer='json') def hello_world(request): return {'content':'Hello!'} @@ -610,9 +610,9 @@ attribute to the request before returning a result: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(name='gone', renderer='templates/gone.pt') + @view_config(name='gone', renderer='templates/gone.pt') def myview(request): request.response_status = '404 Not Found' return {'URL':request.URL} @@ -737,9 +737,9 @@ attribute of a :term:`view configuration`: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='amf') + @view_config(renderer='amf') def myview(request): return {'Hello':'world'} @@ -771,9 +771,9 @@ configuration`: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(renderer='templates/mytemplate.jinja2') + @view_config(renderer='templates/mytemplate.jinja2') def myview(request): return {'Hello':'world'} @@ -928,7 +928,7 @@ code raises a ``hellworld.exceptions.ValidationFailure`` exception: from helloworld.exceptions import ValidationFailure - @bfg_view(context=ValidationFailure) + @view_config(context=ValidationFailure) def failed_validation(exc, request): response = Response('Failed validation: %s' % exc.msg) response.status_int = 500 @@ -946,11 +946,11 @@ exception view registration: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config from pyramid.exceptions import NotFound from webob.exc import HTTPNotFound - @bfg_view(context=NotFound, route_name='home') + @view_config(context=NotFound, route_name='home') def notfound_view(request): return HTTPNotFound() @@ -976,7 +976,7 @@ registered as exception views which have a name will be ignored. normal view. The feature can be used with any view registration mechanism -(``@bfg_view`` decorator, ZCML, or imperative ``add_view`` styles). +(``@view_config`` decorator, ZCML, or imperative ``add_view`` styles). .. index:: single: unicode, views, and forms @@ -1120,8 +1120,8 @@ View configuration is performed in one of three ways: :ref:`view_directive`. - by running a :term:`scan` against application source code which has - a :class:`pyramid.view.bfg_view` decorator attached to a Python - object as per :class:`pyramid.view.bfg_view` and + a :class:`pyramid.view.view_config` decorator attached to a Python + object as per :class:`pyramid.view.view_config` and :ref:`mapping_views_using_a_decorator_section`. - by using the :meth:`pyramid.configuration.Configurator.add_view` @@ -1497,15 +1497,15 @@ apply for the class which is named. See :ref:`view_directive` for complete ZCML directive documentation. .. index:: - single: bfg_view decorator + single: view_config decorator .. _mapping_views_using_a_decorator_section: -View Configuration Using the ``@bfg_view`` Decorator +View Configuration Using the ``@view_config`` Decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For better locality of reference, you may use the -:class:`pyramid.view.bfg_view` decorator to associate your view +:class:`pyramid.view.view_config` decorator to associate your view functions with URLs instead of using :term:`ZCML` or imperative configuration for the same purpose. @@ -1520,15 +1520,15 @@ configuration for the same purpose. See :ref:`extending_chapter` for more information about building extensible applications. -Usage of the ``bfg_view`` decorator is a form of :term:`declarative +Usage of the ``view_config`` decorator is a form of :term:`declarative configuration`, like ZCML, but in decorator form. -:class:`pyramid.view.bfg_view` can be used to associate :term:`view +:class:`pyramid.view.view_config` can be used to associate :term:`view configuration` information -- as done via the equivalent ZCML -- with a function that acts as a :mod:`pyramid` view callable. All ZCML :ref:`view_directive` attributes (save for the ``view`` attribute) are available in decorator form and mean precisely the same thing. -An example of the :class:`pyramid.view.bfg_view` decorator might +An example of the :class:`pyramid.view.view_config` decorator might reside in a :mod:`pyramid` application module ``views.py``: .. ignore-next-block @@ -1536,10 +1536,10 @@ reside in a :mod:`pyramid` application module ``views.py``: :linenos: from models import MyModel - from pyramid.view import bfg_view + from pyramid.view import view_config from pyramid.chameleon_zpt import render_template_to_response - @bfg_view(name='my_view', request_method='POST', context=MyModel, + @view_config(name='my_view', request_method='POST', context=MyModel, permission='read', renderer='templates/my.pt') def my_view(request): return {'a':1} @@ -1567,15 +1567,15 @@ Or replaces the need to add this imperative configuration stanza: config.add_view('.views.my_view', name='my_view', request_method='POST', context=MyModel, permission='read') -All arguments to ``bfg_view`` may be omitted. For example: +All arguments to ``view_config`` may be omitted. For example: .. code-block:: python :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view() + @view_config() def my_view(request): """ My view """ return Response() @@ -1586,9 +1586,9 @@ matches any model type, using no permission, registered against requests with any request method / request type / request param / route name / containment. -The mere existence of a ``@bfg_view`` decorator doesn't suffice to +The mere existence of a ``@view_config`` decorator doesn't suffice to perform view configuration. To make :mod:`pyramid` process your -:class:`pyramid.view.bfg_view` declarations, you *must* do one of +:class:`pyramid.view.view_config` declarations, you *must* do one of the following: - If you are using :term:`ZCML`, insert the following boilerplate into @@ -1610,7 +1610,7 @@ the following: Please see :ref:`decorations_and_code_scanning` for detailed information about what happens when code is scanned for configuration declarations resulting from use of decorators like -:class:`pyramid.view.bfg_view`. +:class:`pyramid.view.view_config`. See :ref:`configuration_module` for additional API arguments to the :meth:`pyramid.configuration.Configurator.scan` method. For @@ -1619,10 +1619,10 @@ better control exactly *which* code will be scanned. This is the same value implied by the ``package`` attribute of the ZCML ``<scan>`` directive (see :ref:`scan_directive`). -``@bfg_view`` Placement -+++++++++++++++++++++++ +``@view_config`` Placement +++++++++++++++++++++++++++ -A :class:`pyramid.view.bfg_view` decorator can be placed in various +A :class:`pyramid.view.view_config` decorator can be placed in various points in your application. If your view callable is a function, it may be used as a function @@ -1631,10 +1631,10 @@ decorator: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config from webob import Response - @bfg_view(name='edit') + @view_config(name='edit') def edit(request): return Response('edited!') @@ -1648,9 +1648,9 @@ function. For example: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view() + @view_config() class MyView(object): def __init__(self, request): self.request = request @@ -1658,7 +1658,7 @@ function. For example: def __call__(self): return Response('hello') -You can use the :class:`pyramid.view.bfg_view` decorator as a +You can use the :class:`pyramid.view.view_config` decorator as a simple callable to manually decorate classes in Python 2.5 and below without the decorator syntactic sugar, if you wish: @@ -1666,7 +1666,7 @@ without the decorator syntactic sugar, if you wish: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config class MyView(object): def __init__(self, request): @@ -1675,20 +1675,20 @@ without the decorator syntactic sugar, if you wish: def __call__(self): return Response('hello') - my_view = bfg_view()(MyView) + my_view = view_config()(MyView) -More than one :class:`pyramid.view.bfg_view` decorator can be +More than one :class:`pyramid.view.view_config` decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example: .. code-block:: python :linenos: - from pyramid.view import bfg_view + from pyramid.view import view_config from webob import Response - @bfg_view(name='edit') - @bfg_view(name='change') + @view_config(name='edit') + @view_config(name='change') def edit(request): return Response('edited!') @@ -1700,13 +1700,13 @@ The decorator can also be used against class methods: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config class MyView(object): def __init__(self, request): self.request = request - @bfg_view(name='hello') + @view_config(name='hello') def amethod(self): return Response('hello') @@ -1729,9 +1729,9 @@ equivalently as the below: :linenos: from webob import Response - from pyramid.view import bfg_view + from pyramid.view import view_config - @bfg_view(attr='amethod', name='hello') + @view_config(attr='amethod', name='hello') class MyView(object): def __init__(self, request): self.request = request @@ -1750,7 +1750,7 @@ View Configuration Using the ``add_view`` Method of a Configurator The :meth:`pyramid.configuration.Configurator.add_view` method within :ref:`configuration_module` is used to configure a view imperatively. The arguments to this method are very similar to the -arguments that you provide to the ``@bfg_view`` decorator. For +arguments that you provide to the ``@view_config`` decorator. For example: .. code-block:: python diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 15f8da9cf..b41979a1f 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -112,9 +112,9 @@ Special Attributes Added to the Request by :mod:`pyramid` In addition to the standard :term:`WebOb` attributes, :mod:`pyramid` adds special attributes to every request: ``context``, ``registry``, ``root``, ``subpath``, ``traversed``, ``view_name``, ``virtual_root`` -, ``virtual_root_path``, and ``session``. These attributes are -documented further within the :class:`pyramid.request.Request` API -documentation. +, ``virtual_root_path``, ``session``, and ``tmpl_context``. These +attributes are documented further within the +:class:`pyramid.request.Request` API documentation. .. index:: single: request URLs |