mirror of
https://github.com/veekun/pokedex.git
synced 2024-08-20 18:16:34 +00:00
275 lines
8.8 KiB
Text
275 lines
8.8 KiB
Text
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:
|
||
|
||
.. testcode::
|
||
|
||
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:
|
||
|
||
.. testoutput::
|
||
|
||
Bulbasaur, the Seed Pokemon
|
||
|
||
Connecting
|
||
----------
|
||
|
||
To get information out of the Pokédex, you will need to create a
|
||
:class:`Session <pokedex.db.multilang.MultilangSession>`. To do that, use
|
||
:func:`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 :func:`~pokedex.db.connect` gives you is actually a
|
||
:class:`SQLAlchemy session <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
|