/docs/index.rst

https://bitbucket.org/jmoiron/johnny-cache/ · ReStructuredText · 148 lines · 109 code · 39 blank · 0 comment · 0 complexity · c710579a160b661a2f87014fbf0e254e MD5 · raw file

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