/docs/index.rst
https://bitbucket.org/jmoiron/johnny-cache/ · ReStructuredText · 148 lines · 109 code · 39 blank · 0 comment · 0 complexity · c710579a160b661a2f87014fbf0e254e MD5 · raw file
- .. Johnny Cache documentation master file, created by
- sphinx-quickstart on Thu Feb 18 22:05:30 2010.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
- Johnny Cache
- ============
- Johnny Cache is a caching framework for django_ applications. It works with
- the django caching abstraction, but was developed specifically with the use of
- memcached_ in mind. Its main feature is a patch on Django's ORM that
- automatically caches all reads in a consistent manner. It works with Django
- 1.1 thru 1.4 and python 2.4 thru 2.7.
- .. highlight:: sh
- You can install johnny with pip::
- pip install johnny-cache
- You can fork johnny-cache `from its git repository`_::
- git clone https://github.com/jmoiron/johnny-cache.git
- or, if you prefer, from its `hg mirror`_::
- hg clone http://bitbucket.org/jmoiron/johnny-cache
- Please use `github's issue tracker`_ to report bugs. Contact the authors at
- `@jmoiron`_ and `@finder83`_.
- .. _django: http://djangoproject.com
- .. _memcached: http://memcached.org
- .. _@jmoiron: http://twitter.com/jmoiron
- .. _@finder83: http://twitter.com/finder83
- .. _github's issue tracker: https://github.com/jmoiron/johnny-cache/issues
- .. _from its git repository: https://github.com/jmoiron/johnny-cache
- .. _hg mirror: http://bitbucket.org/jmoiron/johnny-cache
- Usage
- =====
- .. highlight:: python
- A typical ``settings.py`` file for Django 1.3 or 1.4 configured for
- ``johnny-cache``::
-
- # add johnny's middleware
- MIDDLEWARE_CLASSES = (
- 'johnny.middleware.LocalStoreClearMiddleware',
- 'johnny.middleware.QueryCacheMiddleware',
- # ...
- )
- # some johnny settings
- CACHES = {
- 'default' : dict(
- BACKEND = 'johnny.backends.memcached.MemcachedCache',
- LOCATION = ['127.0.0.1:11211'],
- JOHNNY_CACHE = True,
- )
- }
- JOHNNY_MIDDLEWARE_KEY_PREFIX='jc_myproj'
- For a full inspection of options for earlier versions of Django please see
- the `queryset cache <queryset_cache.html>`_ docs.
- The ``MIDDLEWARE_CLASSES`` setting enables two middlewares: the outer one
- clears a thread-local dict-like cache located at ``johnny.cache.local`` at
- the end of every request, and should really be the outer most middleware in
- your stack. The second one enables the main feature of Johnny: the
- `queryset cache <queryset_cache.html>`_.
- The ``CACHES`` configuration includes a `custom backend <backends.html>`_,
- which allows cache times of "0" to be interpreted as "forever", and marks
- the ``default`` cache backend as the one Johnny will use.
- Finally, the project's name is worked into the Johnny key prefix so that if
- other projects are run using the same cache pool, Johnny won't confuse the
- cache for one project with the cache for another.
- With these settings, all of your ORM queries are now cached. You should
- read the `queryset cache documentation <queryset_cache.html>`_ closely to
- see if you are doing anything that might require manual invalidation.
- Johnny does not define any views, urls, or models, so we can skip adding it
- to ``INSTALLED_APPS``.
- *Note*: Since Johnny is enabled by the inclusion of middleware, it will not
- be enabled by default in scripts, management commands, asynchronous workers,
- or the django shell. See `the queryset cache documentation
- <queryset_cache.html#using-with-scripts-management-commands-asynchronous-workers-and-the-shell>`_
- for instructions on how to enable it in these cases.
- New in this version
- ~~~~~~~~~~~~~~~~~~~
- * Django 1.4 support
- * Redis backend
- * Master/Slave support
- * Cache whitelist
- * New celery task utilities
- Version Numbering
- ~~~~~~~~~~~~~~~~~
- Because Johnny tracks Django's release schedule with its own releases, and is
- itself a mature project, the version number has been bumped from 0.3 to 1.4 to
- coincide with the highest version of Django with support. In the future,
- Johnny's version will track the major and minor version numbers of Django, but
- will have independent dot releases for bugfixes, maintenance, and backwards
- compatible feature enhancements.
- Deprecation Policy
- ~~~~~~~~~~~~~~~~~~
- As of the release of Django 1.4, Django 1.1 and 1.2 are now officially
- unsupported projects. In addition, in an effort to clean up code in preparation
- for eventual Python 3.3 support, Django 1.4 drops support for Python 2.4 and
- Django 1.5 will drop support for Python 2.5.
- Johnny 1.4 will maintain support for Django 1.1+ and Python 2.4-2.7, as
- previous releases have had no official deprecation policies. Future versions
- will:
- * Adopt Django's Python version support & deprecation policy (including its
- py3k adoption timeline)
- * Support the 3 most recent versions of Django
- If Django development goals are met, this means that Johnny 1.5 will support
- Django 1.3-1.5 and Python 2.6+, with experimental Python 3.3 support.
- In Depth Documentation
- ~~~~~~~~~~~~~~~~~~~~~~
- .. toctree::
- :maxdepth: 1
- queryset_cache
- localstore_cache
- backends
- .. * :ref:`modindex`
- .. * :ref:`genindex`
- .. * :ref:`search`