From: Raymond Hettinger <python@rcn.com>
Date: Mon, 2 Aug 2010 01:43:41 +0000 (+0000)
Subject: Demonstrate the caching decorators in whatsnew.
X-Git-Tag: v3.2a2~548
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=aed05eb6b84456f8a97382f65a2d38779249b4a2;p=python

Demonstrate the caching decorators in whatsnew.
---

diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index d1ab51ba7c..924d7f5bec 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -66,6 +66,38 @@ Some smaller changes made to the core Python language are:
 New, Improved, and Deprecated Modules
 =====================================
 
+* The functools module now includes two new decorators for caching function
+  calls, :func:`functools.lru_cache` and :func:`functools.lfu_cache`. These can
+  save repeated queries to an external resource whenever the results are
+  expected to be the same.
+
+  For example, adding an LFU decorator to a database query function can save
+  database accesses for the most popular searches::
+
+      @functools.lfu_cache(maxsize=50)
+      def get_phone_number(name):
+          c = conn.cursor()
+          c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,))
+          return c.fetchone()[0]
+
+  The LFU (least-frequently-used) cache gives best results when the distribution
+  of popular queries tends to remain the same over time. In contrast, the LRU
+  (least-recently-used) cache gives best results when the distribution changes
+  over time (for example, the most popular news articles change each day as
+  newer articles are added).
+
+  The two caching decorators can be composed (nested) to handle hybrid cases
+  that have both long-term access patterns and some short-term access trends.
+  For example, music searches can reflect both long-term patterns (popular
+  classics) and short-term trends (new releases)::
+
+      @functools.lfu_cache(maxsize=500)
+      @functools.lru_cache(maxsize=100)
+      def find_music(song):
+          ...
+
+  (Contributed by Raymond Hettinger)
+
 * The previously deprecated :func:`contextlib.nested` function has been
   removed in favor of a plain :keyword:`with` statement which can
   accept multiple context managers.  The latter technique is faster