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
-