Using pokedex

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, u'bulbasaur')
print u'{0.name}, the {0.genus} Pokemon'.format(pokemon)

Running this will give you some Bulbasaur info:

Bulbasaur, the Seed Pokemon

Connecting

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 uses 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 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.

Pokédex tables

Data in the pokédex is organized in tables, defined in pokedex.db.tables. There is quite a few or them. To get you started, here are a few common ones:

• PokemonSpecies
• Move
• Item
• Type

Getting things

If you know what you want from the pokédex, you can use the pokedex.db.util.get() function. It looks up a thing in a table, based on its identifier, name, or ID, and returns it.

def print_pokemon(pokemon):
    print u'{0.name}, the {0.genus} Pokemon'.format(pokemon)

print_pokemon(util.get(session, tables.PokemonSpecies, identifier=u'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=u'great-ball'))
print_item(util.get(session, tables.Item, name=u'Potion'))
print_item(util.get(session, tables.Item, id=30))

Eevee, the Evolution Pokemon
Ho-Oh, the Rainbow Pokemon
Diglett, the Mole Pokemon
Great Ball: $600
Potion: $300
Fresh Water: $200

Querying

So, how do you get data from the session? You use the session’s query() method, and give it a pokédex Table as an argument. This will give you a SQLAlchemy query.

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 want to sort just about every query you will make.

For example, you can get a list of all pokémon species, sorted by their id, like so:

for pokemon in session.query(tables.PokemonSpecies).order_by(tables.PokemonSpecies.id):
    print pokemon.name

Bulbasaur
Ivysaur
Venusaur
Charmander
Charmeleon
...
Keldeo
Meloetta
Genesect

Or to order by name:

for pokemon in session.query(tables.PokemonSpecies).order_by(tables.PokemonSpecies.name):
    print pokemon.name

Abomasnow
...
Zweilous

Filtering

Another major operation on queries is filtering, using the query’s filter() or filter_by() methods:

for move in session.query(tables.Move).filter(tables.Move.power > 200):
    print move.name

Explosion

Joining

The final operation we’ll cover here is joining other tables to the query, using the query’s join(). You will usually want to join on a relationship, such as in the following example:

query = session.query(tables.Move)
query = query.join(tables.Move.type)
query = query.filter(tables.Type.identifier == u'grass')
query = query.filter(tables.Move.power >= 100)
query = query.order_by(tables.Move.power)
query = query.order_by(tables.Move.name)

print 'The most powerful Grass-type moves:'
for move in query:
    print u'{0.name} ({0.power})'.format(move)

The most powerful Grass-type moves:
Petal Dance (120)
Power Whip (120)
Seed Flare (120)
SolarBeam (120)
Wood Hammer (120)
Leaf Storm (140)
Frenzy Plant (150)

That concludes our brief tutorial. If you need to do more, consult the SQLAlchemy documentation.

API documentation

pokedex.db.connect(uri=None, session_args={}, engine_args={}, engine_prefix='')

Connects to the requested URI. Returns a session object.

With the URI omitted, attempts to connect to a default SQLite database contained within the package directory.

Calling this function also binds the metadata object to the created engine.

See sqlalchemy.orm.session.Session for more documentation on the returned object.

pokedex.db.util.get(session, table, identifier=None, name=None, id=None, language=None)

Get one object from the database.

session: The session to use (from pokedex.db.connect()) table: The table to select from (such as pokedex.db.tables.Move)

identifier: Identifier of the object name: The name of the object id: The ID number of the object

language: A Language to use for name and form_name

All conditions must match, so it’s not a good idea to specify more than one of identifier/name/id at once.

If zero or more than one objects matching the criteria are found, the appropriate SQLAlchemy exception is raised.