pyramid_beaker ============== .. _overview: Overview -------- A :term:`Beaker` session factory backend for :term:`Pyramid`, also cache configurator. Installation ------------ Install using setuptools, e.g. (within a virtualenv):: $ easy_install pyramid_beaker Setup ----- Once :mod:`pyramid_beaker` is installed, you typically use the ``config.include`` mechanism to include it into your Pyramid project's configuration. In your Pyramid project's ``__init__.py``: .. code-block:: python config = Configurator(.....) config.include('pyramid_beaker') Alternately, instead of using the Configurator's ``include`` method, you can activate :mod:`pyramid_beaker` by changing your application's ``.ini`` file, use the following line: .. code-block:: ini pyramid.includes = pyramid_beaker Usage ----- Session management `````````````````` If you have included pyramid_beaker in your Pyramid project's configuration as shown above then :func:`pyramid_beaker.session_factory_from_settings` is called automatically and you need do nothing else. Otherwise you will need to create a Pyramid :term:`session factory` by adding a call to either the :func:`pyramid_beaker.BeakerSessionFactoryConfig` function or the :func:`pyramid_beaker.session_factory_from_settings` function in the configuration code of your Pyramid project's ``__init__.py`` file and subsequently register that session factory with Pyramid. At that point, accessing ``request.session`` will provide a Pyramid session using Beaker as a backend. :func:`pyramid_beaker.session_factory_from_settings` obtains session settings from the ``**settings`` dictionary passed to the Configurator. It assumes that you've placed session configuration parameters prefixed with ``session.`` in your Pyramid application's ``.ini`` file. For example: .. code-block:: ini [app:myapp] .. other settings .. session.type = file session.data_dir = %(here)s/data/sessions/data session.lock_dir = %(here)s/data/sessions/lock session.key = mykey session.secret = mysecret session.cookie_on_exception = true If your ``.ini`` file has such settings, you can use :func:`pyramid_beaker.session_factory_from_settings` in your application's configuration. For example, let's assume this code is in the ``__init__.py`` of your Pyramid application that uses an ``.ini`` file with the ``session.`` settings above to obtain its ``**settings`` dictionary. .. code-block:: python from pyramid_beaker import session_factory_from_settings from pyramid.config import Configurator def app(global_config, **settings): """ This function returns a WSGI application. It is usually called by the PasteDeploy framework during ``paster serve``. """ session_factory = session_factory_from_settings(settings) config = Configurator(root_factory=get_root, settings=settings) config.set_session_factory(session_factory) # ... other configuration stuff... return config.make_wsgi_app() The ``cookie_on_exception`` option is specific to ``pyramid_beaker`` (as opposed to all other options, which are specific to Beaker itself). It indicates that the session cookie should be set even when a Pyramid exception view is being rendered. The default is ``True``, meaning that session cookies will be sent back in responses generated by exception views. Additionally, the ``constant_csrf_token`` option can be set to override the CSRF token value with some constant value. This is useful for testing but should not be set in production. Beaker cache region support ``````````````````````````` In the configuration portion of your :term:`Pyramid` app, if you are not using the default activation setup, use the :func:`pyramid_beaker.set_cache_regions_from_settings` function to set Beaker's cache regions. At that point, you can use Beaker's `cache_region` functionality to enable caching for Your application. :func:`pyramid_beaker.set_cache_regions_from_settings` obtains region settings from the ``**settings`` dictionary passed to the Configurator. It assumes that you've placed cache configuration parameters prefixed with ``cache.`` in your Pyramid application's ``.ini`` file. For example: .. code-block:: ini [app:myapp] .. other settings .. cache.regions = default_term, second, short_term, long_term cache.type = memory cache.second.expire = 1 cache.short_term.expire = 60 cache.default_term.expire = 300 cache.long_term.expire = 3600 If your ``.ini`` file has such settings, you can use :func:`pyramid_beaker.set_cache_regions_from_settings` in your application's configuration. For example, let's assume this code is in the ``__init__.py`` of your Pyramid application that uses an ``.ini`` file with the ``cache.`` settings above to obtain its ``**settings`` dictionary. .. code-block:: python from pyramid_beaker import set_cache_regions_from_settings from pyramid.configuration import configurator def app(global_config, **settings): """ This function returns a WSGI application. It is usually called by the PasteDeploy framework during ``paster serve``. """ set_cache_regions_from_settings(settings) config = Configurator(root_factory=get_root, settings=settings) # ... other configuration stuff... return config.make_wsgi_app() Inherited region settings ~~~~~~~~~~~~~~~~~~~~~~~~~ The following optional region settings inherit from the main cache configuration or default as specified: ``data_dir`` Inherits if specified. ``enabled`` Inherits or defaults to True. ``expire`` Inherits or defaults to 60 seconds. ``key_length`` Inherits or defaults to 250 characters. ``lock_dir`` Inherits if specified. ``type`` Inherits or defaults to ``memory``. ``url`` Inherits if specified. API --- .. toctree:: :maxdepth: 2 api.rst Indices and tables ------------------ * :ref:`glossary` * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. toctree:: :hidden: glossary