mirror of
https://github.com/veekun/pokedex.git
synced 2024-08-20 18:16:34 +00:00
386 lines
No EOL
14 KiB
HTML
386 lines
No EOL
14 KiB
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>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> |