pyramid_dogpile_cache2 1.2.0
Integrates dogpile.cache for Pyramid
License: BSD-3-Clause
Requires Python: >=3.7
Keywords: dogpile.cache, pyramid

======================
pyramid_dogpile_cache2
======================

Small `dogpile.cache`_ configuration and access package. It is inspired by
`pyramid_dogpile_cache`_, which we found unusable since it insists on
configuring the cache regions in its ``get_region()`` API -- but if you want to
use the ``@cache_on_arguments`` decorator, that is at **import time**, where no
configuration exists yet. Our package wants to perform the configuration during
the WSGI application setup instead.

This package is compatible with Python version >=3.6.

.. _`dogpile.cache`: https://python.org/project/dogpile-cache/
.. _`pyramid_dogpile_cache`: https://pypi.org/project/pyramid-dogpile-cache/


Usage
=====

The package offers only one API function; it returns a dogpile.cache
``CacheRegion``::

    from pyramid_dogpile_cache import get_region
    region = get_region('foo')

As said above, this is safe to call at import time, so you can go on like this::

    @region.cache_on_arguments()
    def expensive_function(one, two, three):
        # compute stuff


Setup / Pyramid
===============

Include the package, either in code::

    config = Configurator(...)
    config.include('pyramid_dogpile_cache2')

or in the ini file::

    pyramid.includes = pyramid_dogpile_cache2


Setup / Paste
=============

For non-Pyramid WSGI applications that use a paste.ini file, you need to call::

    def my_paste_app_factory(global_conf, **local_conf):
        pyramid_dogpile_cache2.configure_dogpile_cache(local_conf)
        return my_wsgi_callable


Settings
========

The settings support of pyramid_dogpile_cache unfortunately is quite incomplete
(e.g. it does not even convert ``expiration_time`` to ``int``). The support of
this packages is a little better, but still very much incomplete: we support
the in-memory and memcached backends (pylibmc to be precise), and only the same
backend and configuration for all cache regions.

The following settings are supported:

``dogpile_cache.regions``

    A list of region names that should be configured (separated by either
    spaces or commas).

``dogpile_cache.backend``

    The default backend for cache regions (e.g. ``'dogpile.cache.memory'``,
    ``dogpile.cache.pylibmc``, etc.).

``dogpile_cache.REGION.backend``

   Backend for the given region.

``dogpile_cache.expiration_time``

    The default expiration time. Can be overridden for individual regions (in
    seconds). Omit to set no expiration.

``dogpile_cache.REGION.expiration_time``

    The expiration time for the given cache region (in seconds).
    If omitted, uses the global expiration_time setting.

``dogpile_cache.arguments.*``

    Defaults for backend arguments. Can be overridden for individual regions.

``dogpile_cache.REGION.arguments.*``

    Backend arguments for the given cache region.

Backend arguments work only for strings, thus we support some custom treatment:

``dogpile_cache.pylibmc_url``

    A list of memcached servers, separated by ``;``.

``dogpile_cache.pylibmc_behavior.*``

    Set `pylibmc behaviours`_, see `pylibmc convert`_ for which
    subkeys are supported.


.. _`pylibmc behaviours`: http://sendapatch.se/projects/pylibmc/behaviors.html
.. _`pylibmc convert`: https://github.com/ZeitOnline/pyramid_dogpile_cache2/blob/main/src/pyramid_dogpile_cache2/pylibmc.py

Note: As opposed to pyramid_dogpile_cache we don't support overriding the
key_generator or key_mangler functions yet; we preconfigure them with enhanced
versions of dogpile.cache that support non-ascii function arguments and
generating cache keys for methods that include the class name.


=====================================
Developing pyramid_dogpile_cache2
=====================================

:Author:
    `Die ZEIT Engineering Online <zon-backend@zeit.de>`_

:PyPI page:
    https://pypi.org/project/pyramid-dogpile-cache2/

:Issues:
    `report by e-mail <zon-backend@zeit.de>`_

:Source code:
    https://github.com/zeitonline/pyramid_dogpile_cache2

:Current change log:
    https://github.com/zeitonline/pyramid_dogpile_cache2/blob/main/CHANGES.txt


=====================================
Change log for pyramid_dogpile_cache2
=====================================

.. towncrier release notes start

1.2.0 (2025-08-29)
==================




- Vendor pylibmc parsing code after beaker removed it in 1.14 (beaker)


1.1.2 (2022-07-15)
==================

- Clear internal `_actual_backend` during configure,
  to improve test isolation


1.1.1 (2020-09-11)
==================

- Ignore empty `pylibmc_url` setting


1.1.0 (2020-07-28)
==================

- Drop Python-2 compatibility, update to dogpile.cache>=1.0


1.0.6 (2019-11-08)
==================

- Allow configuring no expiration time at all


1.0.5 (2018-12-14)
==================

- Clarify Python-3 compatiblity (it's >=3.4, not _just_ 3.4)


1.0.4 (2018-11-21)
==================

- Support caching functions with type annotations on Python 3
  (see PR #5).


1.0.3 (2017-02-14)
==================

- Fix packaging issue (see PR #2).


1.0.2 (2016-08-01)
==================

- Update API compatibility to dogpile.cache-0.6.0.


1.0.1 (2016-01-20)
==================

- Actually include the class name in the cache key for methods.


1.0.0 (2016-01-19)
==================

- Initial release.