/docs/index.rst

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

  1.. Johnny Cache documentation master file, created by
  2   sphinx-quickstart on Thu Feb 18 22:05:30 2010.
  3   You can adapt this file completely to your liking, but it should at least
  4   contain the root `toctree` directive.
  5
  6Johnny Cache
  7============
  8
  9Johnny Cache is a caching framework for django_ applications.  It works with
 10the django caching abstraction, but was developed specifically with the use of
 11memcached_ in mind.  Its main feature is a patch on Django's ORM that
 12automatically caches all reads in a consistent manner.  It works with Django 
 131.1 thru 1.4 and python 2.4 thru 2.7.
 14
 15.. highlight:: sh
 16
 17You can install johnny with pip::
 18
 19    pip install johnny-cache
 20
 21You can fork johnny-cache `from its git repository`_::
 22
 23    git clone https://github.com/jmoiron/johnny-cache.git
 24
 25or, if you prefer, from its `hg mirror`_::
 26
 27    hg clone http://bitbucket.org/jmoiron/johnny-cache
 28
 29Please use `github's issue tracker`_ to report bugs.  Contact the authors at
 30`@jmoiron`_ and `@finder83`_.
 31
 32.. _django: http://djangoproject.com
 33.. _memcached: http://memcached.org
 34.. _@jmoiron: http://twitter.com/jmoiron
 35.. _@finder83: http://twitter.com/finder83
 36.. _github's issue tracker: https://github.com/jmoiron/johnny-cache/issues
 37.. _from its git repository: https://github.com/jmoiron/johnny-cache
 38.. _hg mirror: http://bitbucket.org/jmoiron/johnny-cache
 39
 40
 41Usage
 42=====
 43
 44.. highlight:: python
 45
 46A typical ``settings.py`` file for Django 1.3 or 1.4 configured for
 47``johnny-cache``::
 48    
 49    # add johnny's middleware
 50    MIDDLEWARE_CLASSES = (
 51        'johnny.middleware.LocalStoreClearMiddleware',
 52        'johnny.middleware.QueryCacheMiddleware',
 53        # ... 
 54    )
 55    # some johnny settings
 56    CACHES = {
 57        'default' : dict(
 58            BACKEND = 'johnny.backends.memcached.MemcachedCache',
 59            LOCATION = ['127.0.0.1:11211'],
 60            JOHNNY_CACHE = True,
 61        )
 62    }
 63    JOHNNY_MIDDLEWARE_KEY_PREFIX='jc_myproj'
 64
 65For a full inspection of options for earlier versions of Django please see 
 66the `queryset cache <queryset_cache.html>`_ docs.
 67
 68The ``MIDDLEWARE_CLASSES`` setting enables two middlewares:  the outer one
 69clears a thread-local dict-like cache located at ``johnny.cache.local`` at
 70the end of every request, and should really be the outer most middleware in
 71your stack.  The second one enables the main feature of Johnny:  the 
 72`queryset cache <queryset_cache.html>`_.
 73
 74The ``CACHES`` configuration includes a `custom backend <backends.html>`_,
 75which allows cache times of "0" to be interpreted as "forever", and marks
 76the ``default`` cache backend as the one Johnny will use.
 77
 78Finally, the project's name is worked into the Johnny key prefix so that if
 79other projects are run using the same cache pool, Johnny won't confuse the
 80cache for one project with the cache for another.
 81
 82With these settings, all of your ORM queries are now cached.  You should
 83read the `queryset cache documentation <queryset_cache.html>`_ closely to
 84see if you are doing anything that might require manual invalidation.
 85
 86Johnny does not define any views, urls, or models, so we can skip adding it
 87to ``INSTALLED_APPS``.
 88
 89*Note*: Since Johnny is enabled by the inclusion of middleware, it will not
 90be enabled by default in scripts, management commands, asynchronous workers,
 91or the django shell.  See `the queryset cache documentation
 92<queryset_cache.html#using-with-scripts-management-commands-asynchronous-workers-and-the-shell>`_
 93for instructions on how to enable it in these cases.
 94
 95
 96New in this version
 97~~~~~~~~~~~~~~~~~~~
 98
 99* Django 1.4 support
100* Redis backend
101* Master/Slave support
102* Cache whitelist
103* New celery task utilities
104
105Version Numbering
106~~~~~~~~~~~~~~~~~
107
108Because Johnny tracks Django's release schedule with its own releases, and is
109itself a mature project, the version number has been bumped from 0.3 to 1.4 to
110coincide with the highest version of Django with support.  In the future,
111Johnny's version will track the major and minor version numbers of Django, but
112will have independent dot releases for bugfixes, maintenance, and backwards
113compatible feature enhancements.
114
115Deprecation Policy
116~~~~~~~~~~~~~~~~~~
117
118As of the release of Django 1.4, Django 1.1 and 1.2 are now officially
119unsupported projects.  In addition, in an effort to clean up code in preparation
120for eventual Python 3.3 support, Django 1.4 drops support for Python 2.4 and 
121Django 1.5 will drop support for Python 2.5.
122
123Johnny 1.4 will maintain support for Django 1.1+ and Python 2.4-2.7, as
124previous releases have had no official deprecation policies.  Future versions
125will:
126
127 * Adopt Django's Python version support & deprecation policy (including its
128   py3k adoption timeline)
129 * Support the 3 most recent versions of Django
130
131If Django development goals are met, this means that Johnny 1.5 will support
132Django 1.3-1.5 and Python 2.6+, with experimental Python 3.3 support.
133
134
135In Depth Documentation
136~~~~~~~~~~~~~~~~~~~~~~
137
138.. toctree::
139   :maxdepth: 1
140
141   queryset_cache
142   localstore_cache
143   backends
144
145.. * :ref:`modindex`
146.. * :ref:`genindex`
147.. * :ref:`search`
148