The pokédex is, first and foremost, a Python library. To get the most of it, you’ll need to learn `Python`_ and `SQLAlchemy`_.
Here is a small example of using pokedex:
from pokedex.db import connect, tables, util
session = connect()
pokemon = util.get(session, tables.PokemonSpecies, 'bulbasaur')
print u'{0.name}, the {0.genus} Pokemon'.format(pokemon)
Running this will give you some Bulbasaur info:
Bulbasaur, the Seed Pokemon
To get information out of the Pokédex, you will need to create a Session. To do that, use pokedex.db.connect(). For simple uses, you don’t need to give it any arguments: it the database that pokedex load fills up by default. If you need to select another database, give its URI as the first argument.
The object connect() gives you is actually a sqlalchemy.orm.session.Session, 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.
XXX: write the rest of this
..:
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