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 `. 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 `, 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 `. 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