<!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 v0.1 documentation</title>
<link rel="stylesheet" href="_static/default.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 v0.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>
<div class="related">
<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><a href="index.html">pokedex v0.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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 href="#id1"><span class="problematic" id="id2">`Python`_</span></a> and <a href="#id3"><span class="problematic" id="id4">`SQLAlchemy`_</span></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">'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
<tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt>. To do that, use
<tt class="xref py py-func docutils literal"><span class="pre">pokedex.db.connect()</span></tt>. For simple uses, you don’t need to give it any
arguments: it the database that <tt class="docutils literal"><span class="pre">pokedex</span> <span class="pre">load</span></tt> fills up by default. If you
need to select another database, give its URI as the first argument.</p>
<p>The object <tt class="xref py py-func docutils literal"><span class="pre">connect()</span></tt> gives you is actually a
<a class="reference external" href="http://www.sqlalchemy.org/docs/orm/session.html#sqlalchemy.orm.session.Session" title="(in SQLAlchemy v0.7)"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.session.Session</span></tt></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>
<p>XXX: write the rest of this</p>
<p>..:</p>
<div class="highlight-python"><pre>Pokédex tables
--------------
Data in the pokédex is organized in tables, defined in
:mod:`pokedex.db.tables`.
There is quite a few or them. To get you started, here are a few common ones:
* :class:`~pokedex.db.tables.Pokemon` (includes some alternate forms)
* :class:`~pokedex.db.tables.Move`
* :class:`~pokedex.db.tables.Item`
* :class:`~pokedex.db.tables.Type`
Getting things
--------------
If you know what you want from the pokédex, you can use the
:func:`pokedex.db.util.get` function. It looks up a thing in a table, based on
its identifier, name, or ID, and returns it.
.. testcode::
def print_pokemon(pokemon):
print u'{0.name}, the {0.genus} Pokemon'.format(pokemon)
print_pokemon(util.get(session, tables.PokemonSpecies, identifier='eevee'))
print_pokemon(util.get(session, tables.PokemonSpecies, name=u'Ho-Oh'))
print_pokemon(util.get(session, tables.PokemonSpecies, id=50))
def print_item(item):
print u'{0.name}: ${0.cost}'.format(item)
print_item(util.get(session, tables.Item, identifier='great-ball'))
print_item(util.get(session, tables.Item, name='Potion'))
print_item(util.get(session, tables.Item, id=30))
.. testoutput::
Eevee, the Evolution Pokemon
Ho-Oh, the Rainbow Pokemon
Diglett, the Mole Pokemon
Great Ball: $600
Potion: $300
Fresh Water: $200
.. :
Simple lists
------------
.. note::
These functions are only included for convenience in experiments and simple
scripts.
If you want to do something specific, please query the pokédex as explained
in the following sections.
If you want to get a simple list of pokémon without needing to worry about
things like the different forms and sorting the list, you can use the
:func:`pokedex.util.simple.pokemon` function.
.. testcode::
from pokedex.util import simple
for pokemon in simple.pokemon(session):
print u'{0.name}, the {0.species} Pokemon'.format(pokemon)
.. testoutput::
Bulbasaur, the Seed Pokemon
Ivysaur, the Seed Pokemon
...
Meloetta, the Melody Pokemon
Genesect, the Paleozoic Pokemon
Similar functions exist for :func:`~pokedex.util.simple.moves`,
:func:`~pokedex.util.simple.items` and :func:`~pokedex.util.simple.types`.
All of these give you quick simple lists, basically something a pokédex would
show you. They filter out things you probably won't need (such as Shadow moves
or duplicate Pokémon moves), and sort the results in some sane way, but they
can't guess your needs exactly, and their guesses might change in future
versions.
If you want to do some serious work with the pokédex, read on.
Querying
--------
So, how do you get data from the session? You use the session's
:meth:`~sqlalchemy.orm.session.Session.query` method, and give it a pokédex
Table as an argument. This will give you a :class:`SQLAlchemy query
<sqlalchemy.orm.query.Query>`.
To get you started, we'll cover some common query operations below. If you
need to do more, consult the `SQLAlchemy documentation`_.
Ordering
^^^^^^^^
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 likely want to sort every query you will make.
For example, you can get a list of all pokémon, sorted by their
:attr:`~pokedex.db.tables.Pokemon.order`, like so:
.. testcode::
for pokemon in session.query(tables.Pokemon).order_by(tables.Pokemon.order):
print pokemon.name
.. testoutput::
Bulbasaur
Ivysaur
Venusaur
Charmander
Charmeleon
...
Pichu
Pikachu
Raichu
...
Keldeo
Aria Meloetta
Pirouette Meloetta
Genesect
Ordering by name
****************
Since the pokédex can be used in other languages than English, working with
texts such as names is sometimes tricky.
The “name” attribute is actually a relation that uses the connection's
default language to select an appropriate translation. It usually works the
same way as a normal attribute, but ordering is an exception to this:
.. testcode::
for pokemon in session.query(tables.Pokemon).order_by(tables.Pokemon.name):
print pokemon.name
.. testoutput::
Traceback (most recent call last):
...
ArgumentError: SQL expression object or string expected.
This means that to order by name, you either have to explicitly join the
translation table and sort by that, or use
:func:`pokedex.db.util.order_by_name`:
.. testcode::
from pokedex.db import util
for pokemon in util.order_by_name(session.query(tables.Pokemon), tables.Pokemon):
print pokemon.name
.. testoutput::
Abomasnow
...
Zweilous
Filtering
^^^^^^^^^
Another major operation on queries is filtering, using the query's
:meth:`~sqlalchemy.orm.query.Query.filter` or
:meth:`~sqlalchemy.orm.query.Query.filter_by` methods:
.. testcode::
for move in session.query(tables.Move).filter(tables.Move.power > 200):
print move.name
.. testoutput::
Explosion
Joining
^^^^^^^
The final operation we'll cover here is joining other tables to the query,
using the query's :meth:`~sqlalchemy.orm.query.Query.join`.
You will usually want to join on a relationship, such as in the following
example:
.. testcode::
query = session.query(tables.Move)
query = query.join(tables.Move.type)
query = query.filter(tables.Type.identifier == 'grass')
query = query.filter(tables.Move.power >= 100)
query = query.order_by(tables.Move.power)
query = util.order_by_name(query, tables.Move)
print 'The most powerful Grass moves:'
for move in query:
print u'{0.name} ({0.power})'.format(move)
.. testoutput::
The most powerful Grass moves:
Petal Dance (120)
Power Whip (120)
Seed Flare (120)
SolarBeam (120)
Wood Hammer (120)
Leaf Storm (140)
Frenzy Plant (150)
API documentation
-----------------
.. autofunction:: pokedex.db.connect
See :class:`sqlalchemy.orm.session.Session` for more documentation on the
returned object.
.. autofunction:: pokedex.db.util.get
.. autofunction:: pokedex.db.util.order_by_name
Simple lists
^^^^^^^^^^^^
.. autofunction:: pokedex.util.simple.pokemon
.. autofunction:: pokedex.util.simple.moves
.. autofunction:: pokedex.util.simple.items
.. autofunction:: pokedex.util.simple.types
.. _Python: http://www.python.org
.. _SQLAlchemy: http://www.sqlalchemy.org
.. _`SQLAlchemy documentation`: http://www.sqlalchemy.org/docs/orm/tutorial.html</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<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>
</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>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<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">
<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><a href="index.html">pokedex v0.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
</div>
</body>
</html>