<!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>Using pokedex — pokedex 0.1 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<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>
<link rel="top" title="pokedex 0.1 documentation" href="index.html" />
<link rel="next" title="The database schema" href="schema.html" />
<link rel="prev" title="Installing the pokedex library" href="installing.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="schema.html" title="The database schema"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="installing.html" title="Installing the pokedex library"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pokedex 0.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="using-pokedex">
<h1>Using pokedex<a class="headerlink" href="#using-pokedex" title="Permalink to this headline">¶</a></h1>
<p>The pokédex is, first and foremost, a Python library. To get the most of it,
you’ll need to learn <a class="reference external" href="http://www.python.org">Python</a> and <a class="reference external" href="http://www.sqlalchemy.org">SQLAlchemy</a>.</p>
<p>Here is a small example of using pokedex:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pokedex.db</span> <span class="kn">import</span> <span class="n">connect</span><span class="p">,</span> <span class="n">tables</span><span class="p">,</span> <span class="n">util</span>
<span class="n">session</span> <span class="o">=</span> <span class="n">connect</span><span class="p">()</span>
<span class="n">pokemon</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">,</span> <span class="s">u'bulbasaur'</span><span class="p">)</span>
<span class="k">print</span> <span class="s">u'{0.name}, the {0.genus} Pokemon'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">pokemon</span><span class="p">)</span>
</pre></div>
</div>
<p>Running this will give you some Bulbasaur info:</p>
<div class="highlight-none"><div class="highlight"><pre>Bulbasaur, the Seed Pokemon
</pre></div>
</div>
<div class="section" id="connecting">
<h2>Connecting<a class="headerlink" href="#connecting" title="Permalink to this headline">¶</a></h2>
<p>To get information out of the Pokédex, you will need to create a
<code class="xref py py-class docutils literal"><span class="pre">Session</span></code>. To do that, use
<a class="reference internal" href="#pokedex.db.connect" title="pokedex.db.connect"><code class="xref py py-func docutils literal"><span class="pre">pokedex.db.connect()</span></code></a>. For simple uses, you don’t need to give it any
arguments: it uses the database that <code class="docutils literal"><span class="pre">pokedex</span> <span class="pre">load</span></code> fills up by default. If
you need to select another database, give its URI as the first argument.</p>
<p>The object <a class="reference internal" href="#pokedex.db.connect" title="pokedex.db.connect"><code class="xref py py-func docutils literal"><span class="pre">connect()</span></code></a> gives you is actually a
<a class="reference external" href="http://www.sqlalchemy.org/docs/orm/session_api.html#sqlalchemy.orm.session.Session" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal"><span class="pre">SQLAlchemy</span> <span class="pre">session</span></code></a>, giving you the
full power of SQLAlchemy for working with the data. We’ll cover some basics
here, but if you intend to do some serious work, do read SQLAlchemy’s docs.</p>
</div>
<div class="section" id="pokedex-tables">
<h2>Pokédex tables<a class="headerlink" href="#pokedex-tables" title="Permalink to this headline">¶</a></h2>
<p>Data in the pokédex is organized in tables, defined in
<a class="reference internal" href="main-tables.html#module-pokedex.db.tables" title="pokedex.db.tables"><code class="xref py py-mod docutils literal"><span class="pre">pokedex.db.tables</span></code></a>.
There is quite a few or them. To get you started, here are a few common ones:</p>
<ul class="simple">
<li><a class="reference internal" href="main-tables.html#pokedex.db.tables.PokemonSpecies" title="pokedex.db.tables.PokemonSpecies"><code class="xref py py-class docutils literal"><span class="pre">PokemonSpecies</span></code></a></li>
<li><a class="reference internal" href="main-tables.html#pokedex.db.tables.Move" title="pokedex.db.tables.Move"><code class="xref py py-class docutils literal"><span class="pre">Move</span></code></a></li>
<li><a class="reference internal" href="main-tables.html#pokedex.db.tables.Item" title="pokedex.db.tables.Item"><code class="xref py py-class docutils literal"><span class="pre">Item</span></code></a></li>
<li><a class="reference internal" href="main-tables.html#pokedex.db.tables.Type" title="pokedex.db.tables.Type"><code class="xref py py-class docutils literal"><span class="pre">Type</span></code></a></li>
</ul>
</div>
<div class="section" id="getting-things">
<h2>Getting things<a class="headerlink" href="#getting-things" title="Permalink to this headline">¶</a></h2>
<p>If you know what you want from the pokédex, you can use the
<a class="reference internal" href="#pokedex.db.util.get" title="pokedex.db.util.get"><code class="xref py py-func docutils literal"><span class="pre">pokedex.db.util.get()</span></code></a> function. It looks up a thing in a table, based on
its identifier, name, or ID, and returns it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">print_pokemon</span><span class="p">(</span><span class="n">pokemon</span><span class="p">):</span>
<span class="k">print</span> <span class="s">u'{0.name}, the {0.genus} Pokemon'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">pokemon</span><span class="p">)</span>
<span class="n">print_pokemon</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">,</span> <span class="n">identifier</span><span class="o">=</span><span class="s">u'eevee'</span><span class="p">))</span>
<span class="n">print_pokemon</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">u'Ho-Oh'</span><span class="p">))</span>
<span class="n">print_pokemon</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="mi">50</span><span class="p">))</span>
<span class="k">def</span> <span class="nf">print_item</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="k">print</span> <span class="s">u'{0.name}: ${0.cost}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
<span class="n">print_item</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">Item</span><span class="p">,</span> <span class="n">identifier</span><span class="o">=</span><span class="s">u'great-ball'</span><span class="p">))</span>
<span class="n">print_item</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">Item</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">u'Potion'</span><span class="p">))</span>
<span class="n">print_item</span><span class="p">(</span><span class="n">util</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">tables</span><span class="o">.</span><span class="n">Item</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="mi">30</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-none"><div class="highlight"><pre>Eevee, the Evolution Pokemon
Ho-Oh, the Rainbow Pokemon
Diglett, the Mole Pokemon
Great Ball: $600
Potion: $300
Fresh Water: $200
</pre></div>
</div>
</div>
<div class="section" id="querying">
<h2>Querying<a class="headerlink" href="#querying" title="Permalink to this headline">¶</a></h2>
<p>So, how do you get data from the session? You use the session’s
<a class="reference external" href="http://www.sqlalchemy.org/docs/orm/session_api.html#sqlalchemy.orm.session.Session.query" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal"><span class="pre">query()</span></code></a> method, and give it a pokédex
Table as an argument. This will give you a <a class="reference external" href="http://www.sqlalchemy.org/docs/orm/query.html#sqlalchemy.orm.query.Query" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal"><span class="pre">SQLAlchemy</span> <span class="pre">query</span></code></a>.</p>
<div class="section" id="ordering">
<h3>Ordering<a class="headerlink" href="#ordering" title="Permalink to this headline">¶</a></h3>
<p>As always with SQL, you should not rely on query results being in some
particular order – unless you have ordered the query first. This means that
you’ll want to sort just about every query you will make.</p>
<p>For example, you can get a list of all pokémon species, sorted by their
<code class="xref py py-attr docutils literal"><span class="pre">id</span></code>, like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">pokemon</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">)</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="o">.</span><span class="n">id</span><span class="p">):</span>
<span class="k">print</span> <span class="n">pokemon</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<div class="highlight-none"><div class="highlight"><pre>Bulbasaur
Ivysaur
Venusaur
Charmander
Charmeleon
...
Xerneas
Yveltal
Zygarde
</pre></div>
</div>
<p>Or to order by <code class="xref py py-attr docutils literal"><span class="pre">name</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">pokemon</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="p">)</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">PokemonSpecies</span><span class="o">.</span><span class="n">name</span><span class="p">):</span>
<span class="k">print</span> <span class="n">pokemon</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<div class="highlight-none"><div class="highlight"><pre>Abomasnow
...
Zygarde
</pre></div>
</div>
</div>
<div class="section" id="filtering">
<h3>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline">¶</a></h3>
<p>Another major operation on queries is filtering, using the query’s
<a class="reference external" href="http://www.sqlalchemy.org/docs/orm/query.html#sqlalchemy.orm.query.Query.filter" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal"><span class="pre">filter()</span></code></a> or
<a class="reference external" href="http://www.sqlalchemy.org/docs/orm/query.html#sqlalchemy.orm.query.Query.filter_by" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal"><span class="pre">filter_by()</span></code></a> methods:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">move</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="o">.</span><span class="n">power</span> <span class="o">></span> <span class="mi">200</span><span class="p">):</span>
<span class="k">print</span> <span class="n">move</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<div class="highlight-none"><div class="highlight"><pre>Explosion
</pre></div>
</div>
</div>
<div class="section" id="joining">
<h3>Joining<a class="headerlink" href="#joining" title="Permalink to this headline">¶</a></h3>
<p>The final operation we’ll cover here is joining other tables to the query,
using the query’s <a class="reference external" href="http://www.sqlalchemy.org/docs/orm/query.html#sqlalchemy.orm.query.Query.join" title="(in SQLAlchemy v1.0)"><code class="xref py py-meth docutils literal"><span class="pre">join()</span></code></a>.
You will usually want to join on a relationship, such as in the following
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="p">)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="o">.</span><span class="n">type</span><span class="p">)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Type</span><span class="o">.</span><span class="n">identifier</span> <span class="o">==</span> <span class="s">u'grass'</span><span class="p">)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="o">.</span><span class="n">power</span> <span class="o">>=</span> <span class="mi">100</span><span class="p">)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="o">.</span><span class="n">power</span><span class="p">)</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">tables</span><span class="o">.</span><span class="n">Move</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'The most powerful Grass-type moves:'</span>
<span class="k">for</span> <span class="n">move</span> <span class="ow">in</span> <span class="n">query</span><span class="p">:</span>
<span class="k">print</span> <span class="s">u'{0.name} ({0.power})'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">move</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-none"><div class="highlight"><pre>The most powerful Grass-type moves:
Petal Dance (120)
Power Whip (120)
Seed Flare (120)
Solar Beam (120)
Wood Hammer (120)
Leaf Storm (130)
Frenzy Plant (150)
</pre></div>
</div>
<p>That concludes our brief tutorial.
If you need to do more, consult the <a class="reference external" href="http://www.sqlalchemy.org/docs/orm/tutorial.html">SQLAlchemy documentation</a>.</p>
</div>
</div>
<div class="section" id="api-documentation">
<h2>API documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="pokedex.db.connect">
<code class="descclassname">pokedex.db.</code><code class="descname">connect</code><span class="sig-paren">(</span><em>uri=None</em>, <em>session_args={}</em>, <em>engine_args={}</em>, <em>engine_prefix=''</em><span class="sig-paren">)</span><a class="headerlink" href="#pokedex.db.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Connects to the requested URI. Returns a session object.</p>
<p>With the URI omitted, attempts to connect to a default SQLite database
contained within the package directory.</p>
<p>Calling this function also binds the metadata object to the created engine.</p>
<p>See <a class="reference external" href="http://www.sqlalchemy.org/docs/orm/session_api.html#sqlalchemy.orm.session.Session" title="(in SQLAlchemy v1.0)"><code class="xref py py-class docutils literal"><span class="pre">sqlalchemy.orm.session.Session</span></code></a> for more documentation on the
returned object.</p>
</dd></dl>
<dl class="function">
<dt id="pokedex.db.util.get">
<code class="descclassname">pokedex.db.util.</code><code class="descname">get</code><span class="sig-paren">(</span><em>session</em>, <em>table</em>, <em>identifier=None</em>, <em>name=None</em>, <em>id=None</em>, <em>language=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pokedex.db.util.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Get one object from the database.</p>
<p>session: The session to use (from pokedex.db.connect())
table: The table to select from (such as pokedex.db.tables.Move)</p>
<p>identifier: Identifier of the object
name: The name of the object
id: The ID number of the object</p>
<p>language: A Language to use for name and form_name</p>
<p>All conditions must match, so it’s not a good idea to specify more than one
of identifier/name/id at once.</p>
<p>If zero or more than one objects matching the criteria are found, the
appropriate SQLAlchemy exception is raised.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using pokedex</a><ul>
<li><a class="reference internal" href="#connecting">Connecting</a></li>
<li><a class="reference internal" href="#pokedex-tables">Pokédex tables</a></li>
<li><a class="reference internal" href="#getting-things">Getting things</a></li>
<li><a class="reference internal" href="#querying">Querying</a><ul>
<li><a class="reference internal" href="#ordering">Ordering</a></li>
<li><a class="reference internal" href="#filtering">Filtering</a></li>
<li><a class="reference internal" href="#joining">Joining</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-documentation">API documentation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="installing.html"
title="previous chapter">Installing the pokedex library</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="schema.html"
title="next chapter">The database schema</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="schema.html" title="The database schema"
>next</a> |</li>
<li class="right" >
<a href="installing.html" title="Installing the pokedex library"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pokedex 0.1 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
</div>
</body>
</html>