File: //usr/share/doc/python-sqlalchemy-0.9.8/doc/_modules/examples/dogpile_caching/caching_query.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
examples.dogpile_caching.caching_query
—
SQLAlchemy 0.9 Documentation
</title>
<!-- begin iterate through SQLA + sphinx environment css_files -->
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/sphinx_paramlinks.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/changelog.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '0.9.8',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../../../_static/detectmobile.js"></script>
<script type="text/javascript" src="../../../_static/init.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="copyright" title="Copyright" href="../../../copyright.html" />
<link rel="top" title="SQLAlchemy 0.9 Documentation" href="../../../index.html" />
<link rel="up" title="Module code" href="../../index.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
</div>
<h1>SQLAlchemy 0.9 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="">
<div id="index-nav">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p>
<a href="../../../index.html">Contents</a> |
<a href="../../../genindex.html">Index</a>
</p>
</div>
</div>
<div id="docs-body" class="" >
<h1>Source code for examples.dogpile_caching.caching_query</h1><div class="highlight"><pre>
<span class="sd">"""caching_query.py</span>
<span class="sd">Represent functions and classes</span>
<span class="sd">which allow the usage of Dogpile caching with SQLAlchemy.</span>
<span class="sd">Introduces a query option called FromCache.</span>
<span class="sd">The three new concepts introduced here are:</span>
<span class="sd"> * CachingQuery - a Query subclass that caches and</span>
<span class="sd"> retrieves results in/from dogpile.cache.</span>
<span class="sd"> * FromCache - a query option that establishes caching</span>
<span class="sd"> parameters on a Query</span>
<span class="sd"> * RelationshipCache - a variant of FromCache which is specific</span>
<span class="sd"> to a query invoked during a lazy load.</span>
<span class="sd"> * _params_from_query - extracts value parameters from</span>
<span class="sd"> a Query.</span>
<span class="sd">The rest of what's here are standard SQLAlchemy and</span>
<span class="sd">dogpile.cache constructs.</span>
<span class="sd">"""</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.interfaces</span> <span class="kn">import</span> <span class="n">MapperOption</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.query</span> <span class="kn">import</span> <span class="n">Query</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">visitors</span>
<span class="kn">from</span> <span class="nn">dogpile.cache.api</span> <span class="kn">import</span> <span class="n">NO_VALUE</span>
<span class="k">class</span> <span class="nc">CachingQuery</span><span class="p">(</span><span class="n">Query</span><span class="p">):</span>
<span class="sd">"""A Query subclass which optionally loads full results from a dogpile</span>
<span class="sd"> cache region.</span>
<span class="sd"> The CachingQuery optionally stores additional state that allows it to consult</span>
<span class="sd"> a dogpile.cache cache before accessing the database, in the form</span>
<span class="sd"> of a FromCache or RelationshipCache object. Each of these objects</span>
<span class="sd"> refer to the name of a :class:`dogpile.cache.Region` that's been configured</span>
<span class="sd"> and stored in a lookup dictionary. When such an object has associated</span>
<span class="sd"> itself with the CachingQuery, the corresponding :class:`dogpile.cache.Region`</span>
<span class="sd"> is used to locate a cached result. If none is present, then the</span>
<span class="sd"> Query is invoked normally, the results being cached.</span>
<span class="sd"> The FromCache and RelationshipCache mapper options below represent</span>
<span class="sd"> the "public" method of configuring this state upon the CachingQuery.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">regions</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cache_regions</span> <span class="o">=</span> <span class="n">regions</span>
<span class="n">Query</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""override __iter__ to pull results from dogpile</span>
<span class="sd"> if particular attributes have been configured.</span>
<span class="sd"> Note that this approach does *not* detach the loaded objects from</span>
<span class="sd"> the current session. If the cache backend is an in-process cache</span>
<span class="sd"> (like "memory") and lives beyond the scope of the current session's</span>
<span class="sd"> transaction, those objects may be expired. The method here can be</span>
<span class="sd"> modified to first expunge() each loaded item from the current</span>
<span class="sd"> session before returning the list of items, so that the items</span>
<span class="sd"> in the cache are not the same ones in the current Session.</span>
<span class="sd"> """</span>
<span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s">'_cache_region'</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_value</span><span class="p">(</span><span class="n">createfunc</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span> <span class="nb">list</span><span class="p">(</span><span class="n">Query</span><span class="o">.</span><span class="n">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">)))</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="n">Query</span><span class="o">.</span><span class="n">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">_get_cache_plus_key</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Return a cache region plus key."""</span>
<span class="n">dogpile_region</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cache_regions</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_cache_region</span><span class="o">.</span><span class="n">region</span><span class="p">]</span>
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache_region</span><span class="o">.</span><span class="n">cache_key</span><span class="p">:</span>
<span class="n">key</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache_region</span><span class="o">.</span><span class="n">cache_key</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">key</span> <span class="o">=</span> <span class="n">_key_from_query</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="k">return</span> <span class="n">dogpile_region</span><span class="p">,</span> <span class="n">key</span>
<span class="k">def</span> <span class="nf">invalidate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Invalidate the cache value represented by this Query."""</span>
<span class="n">dogpile_region</span><span class="p">,</span> <span class="n">cache_key</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_cache_plus_key</span><span class="p">()</span>
<span class="n">dogpile_region</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">cache_key</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">get_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">merge</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">createfunc</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">expiration_time</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">ignore_expiration</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
<span class="sd">"""Return the value from the cache for this query.</span>
<span class="sd"> Raise KeyError if no value present and no</span>
<span class="sd"> createfunc specified.</span>
<span class="sd"> """</span>
<span class="n">dogpile_region</span><span class="p">,</span> <span class="n">cache_key</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_cache_plus_key</span><span class="p">()</span>
<span class="c"># ignore_expiration means, if the value is in the cache</span>
<span class="c"># but is expired, return it anyway. This doesn't make sense</span>
<span class="c"># with createfunc, which says, if the value is expired, generate</span>
<span class="c"># a new value.</span>
<span class="k">assert</span> <span class="ow">not</span> <span class="n">ignore_expiration</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">createfunc</span><span class="p">,</span> \
<span class="s">"Can't ignore expiration and also provide createfunc"</span>
<span class="k">if</span> <span class="n">ignore_expiration</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">createfunc</span><span class="p">:</span>
<span class="n">cached_value</span> <span class="o">=</span> <span class="n">dogpile_region</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">cache_key</span><span class="p">,</span>
<span class="n">expiration_time</span><span class="o">=</span><span class="n">expiration_time</span><span class="p">,</span>
<span class="n">ignore_expiration</span><span class="o">=</span><span class="n">ignore_expiration</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">cached_value</span> <span class="o">=</span> <span class="n">dogpile_region</span><span class="o">.</span><span class="n">get_or_create</span><span class="p">(</span>
<span class="n">cache_key</span><span class="p">,</span>
<span class="n">createfunc</span><span class="p">,</span>
<span class="n">expiration_time</span><span class="o">=</span><span class="n">expiration_time</span>
<span class="p">)</span>
<span class="k">if</span> <span class="n">cached_value</span> <span class="ow">is</span> <span class="n">NO_VALUE</span><span class="p">:</span>
<span class="k">raise</span> <span class="ne">KeyError</span><span class="p">(</span><span class="n">cache_key</span><span class="p">)</span>
<span class="k">if</span> <span class="n">merge</span><span class="p">:</span>
<span class="n">cached_value</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">merge_result</span><span class="p">(</span><span class="n">cached_value</span><span class="p">,</span> <span class="n">load</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="k">return</span> <span class="n">cached_value</span>
<span class="k">def</span> <span class="nf">set_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="sd">"""Set the value in the cache for this query."""</span>
<span class="n">dogpile_region</span><span class="p">,</span> <span class="n">cache_key</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_cache_plus_key</span><span class="p">()</span>
<span class="n">dogpile_region</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">cache_key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">query_callable</span><span class="p">(</span><span class="n">regions</span><span class="p">,</span> <span class="n">query_cls</span><span class="o">=</span><span class="n">CachingQuery</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">query</span><span class="p">(</span><span class="o">*</span><span class="n">arg</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="k">return</span> <span class="n">query_cls</span><span class="p">(</span><span class="n">regions</span><span class="p">,</span> <span class="o">*</span><span class="n">arg</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
<span class="k">return</span> <span class="n">query</span>
<span class="k">def</span> <span class="nf">_key_from_query</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="n">qualifier</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Given a Query, create a cache key.</span>
<span class="sd"> There are many approaches to this; here we use the simplest,</span>
<span class="sd"> which is to create an md5 hash of the text of the SQL statement,</span>
<span class="sd"> combined with stringified versions of all the bound parameters</span>
<span class="sd"> within it. There's a bit of a performance hit with</span>
<span class="sd"> compiling out "query.statement" here; other approaches include</span>
<span class="sd"> setting up an explicit cache key with a particular Query,</span>
<span class="sd"> then combining that with the bound parameter values.</span>
<span class="sd"> """</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">with_labels</span><span class="p">()</span><span class="o">.</span><span class="n">statement</span>
<span class="n">compiled</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span>
<span class="n">params</span> <span class="o">=</span> <span class="n">compiled</span><span class="o">.</span><span class="n">params</span>
<span class="c"># here we return the key as a long string. our "key mangler"</span>
<span class="c"># set up with the region will boil it down to an md5.</span>
<span class="k">return</span> <span class="s">" "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
<span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">compiled</span><span class="p">)]</span> <span class="o">+</span>
<span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">params</span><span class="p">[</span><span class="n">k</span><span class="p">])</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">params</span><span class="p">)])</span>
<span class="k">class</span> <span class="nc">FromCache</span><span class="p">(</span><span class="n">MapperOption</span><span class="p">):</span>
<span class="sd">"""Specifies that a Query should load results from a cache."""</span>
<span class="n">propagate_to_loaders</span> <span class="o">=</span> <span class="bp">False</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">region</span><span class="o">=</span><span class="s">"default"</span><span class="p">,</span> <span class="n">cache_key</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Construct a new FromCache.</span>
<span class="sd"> :param region: the cache region. Should be a</span>
<span class="sd"> region configured in the dictionary of dogpile</span>
<span class="sd"> regions.</span>
<span class="sd"> :param cache_key: optional. A string cache key</span>
<span class="sd"> that will serve as the key to the query. Use this</span>
<span class="sd"> if your query has a huge amount of parameters (such</span>
<span class="sd"> as when using in_()) which correspond more simply to</span>
<span class="sd"> some other identifier.</span>
<span class="sd"> """</span>
<span class="bp">self</span><span class="o">.</span><span class="n">region</span> <span class="o">=</span> <span class="n">region</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cache_key</span> <span class="o">=</span> <span class="n">cache_key</span>
<span class="k">def</span> <span class="nf">process_query</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">):</span>
<span class="sd">"""Process a Query during normal loading operation."""</span>
<span class="n">query</span><span class="o">.</span><span class="n">_cache_region</span> <span class="o">=</span> <span class="bp">self</span>
<span class="k">class</span> <span class="nc">RelationshipCache</span><span class="p">(</span><span class="n">MapperOption</span><span class="p">):</span>
<span class="sd">"""Specifies that a Query as called within a "lazy load"</span>
<span class="sd"> should load results from a cache."""</span>
<span class="n">propagate_to_loaders</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">attribute</span><span class="p">,</span> <span class="n">region</span><span class="o">=</span><span class="s">"default"</span><span class="p">,</span> <span class="n">cache_key</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Construct a new RelationshipCache.</span>
<span class="sd"> :param attribute: A Class.attribute which</span>
<span class="sd"> indicates a particular class relationship() whose</span>
<span class="sd"> lazy loader should be pulled from the cache.</span>
<span class="sd"> :param region: name of the cache region.</span>
<span class="sd"> :param cache_key: optional. A string cache key</span>
<span class="sd"> that will serve as the key to the query, bypassing</span>
<span class="sd"> the usual means of forming a key from the Query itself.</span>
<span class="sd"> """</span>
<span class="bp">self</span><span class="o">.</span><span class="n">region</span> <span class="o">=</span> <span class="n">region</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cache_key</span> <span class="o">=</span> <span class="n">cache_key</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_relationship_options</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">(</span><span class="n">attribute</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">class_</span><span class="p">,</span> <span class="n">attribute</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">key</span><span class="p">):</span> <span class="bp">self</span>
<span class="p">}</span>
<span class="k">def</span> <span class="nf">process_query_conditionally</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">):</span>
<span class="sd">"""Process a Query that is used within a lazy loader.</span>
<span class="sd"> (the process_query_conditionally() method is a SQLAlchemy</span>
<span class="sd"> hook invoked only within lazyload.)</span>
<span class="sd"> """</span>
<span class="k">if</span> <span class="n">query</span><span class="o">.</span><span class="n">_current_path</span><span class="p">:</span>
<span class="n">mapper</span><span class="p">,</span> <span class="n">prop</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">_current_path</span><span class="p">[</span><span class="o">-</span><span class="mi">2</span><span class="p">:]</span>
<span class="n">key</span> <span class="o">=</span> <span class="n">prop</span><span class="o">.</span><span class="n">key</span>
<span class="k">for</span> <span class="n">cls</span> <span class="ow">in</span> <span class="n">mapper</span><span class="o">.</span><span class="n">class_</span><span class="o">.</span><span class="n">__mro__</span><span class="p">:</span>
<span class="k">if</span> <span class="p">(</span><span class="n">cls</span><span class="p">,</span> <span class="n">key</span><span class="p">)</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_relationship_options</span><span class="p">:</span>
<span class="n">relationship_option</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_relationship_options</span><span class="p">[(</span><span class="n">cls</span><span class="p">,</span> <span class="n">key</span><span class="p">)]</span>
<span class="n">query</span><span class="o">.</span><span class="n">_cache_region</span> <span class="o">=</span> <span class="n">relationship_option</span>
<span class="k">break</span>
<span class="k">def</span> <span class="nf">and_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">option</span><span class="p">):</span>
<span class="sd">"""Chain another RelationshipCache option to this one.</span>
<span class="sd"> While many RelationshipCache objects can be specified on a single</span>
<span class="sd"> Query separately, chaining them together allows for a more efficient</span>
<span class="sd"> lookup during load.</span>
<span class="sd"> """</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_relationship_options</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">option</span><span class="o">.</span><span class="n">_relationship_options</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">self</span></pre></div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
<div id="docs-copyright">
© <a href="../../../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>