veekun_pokedex/_sources/usage.txt

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