Break "simple" query functions out of pokedex.util.get

pokedex/tests/test_util.py

@@ -3,7 +3,7 @@ from nose.tools import *
 import unittest
 
 from pokedex.db import connect, tables
-from pokedex.util import get
+from pokedex.util import get, simple
 
 session = connect()
 
@@ -46,30 +46,30 @@ def test_get_pokemon_other_form_identifier():
         if poke.form.unique_pokemon_id:
             assert poke.form.identifier == form_identifier
 
-def test_pokemon():
-    pokemon = get.pokemon(session)
-    assert pokemon[0].identifier == 'bulbasaur'
-    assert pokemon[-1].identifier == 'genesect'
-
-def test_pokemon_by_name():
-    pokemon = get.pokemon(session, order=tables.Pokemon.name)
-    assert pokemon[0].identifier == 'abomasnow'
-    assert pokemon[-1].identifier == 'zweilous'
-
 def test_types_french_order():
     french = get.get(session, tables.Language, 'fr')
-    types = get.types(session, order=None)
+    types = session.query(tables.Type).filter(tables.Type.id < 10000)
     types = list(get.order_by_name(types, tables.Type, language=french))
     assert types[0].name_map[french] == 'Acier', types[0].name_map[french]
     assert types[-1].name_map[french] == 'Vol', types[-1].name_map[french]
 
-def test_moves():
-    moves = get.moves(session)
+def test_simple_pokemon():
+    pokemon = simple.pokemon(session)
+    assert pokemon[0].identifier == 'bulbasaur'
+    assert pokemon[-1].identifier == 'genesect'
+
+def test_simple_types():
+    types = simple.types(session)
+    assert types[0].identifier == 'bug'
+    assert types[-1].identifier == 'water'
+
+def test_simple_moves():
+    moves = simple.moves(session)
     assert moves[0].identifier == 'absorb'
     assert moves[-1].identifier == 'zen-headbutt'
 
-def test_items():
-    items = get.items(session)
+def test_simple_items():
+    items = simple.items(session)
     assert items[0].identifier == 'ability-urge'
     assert items[-1].identifier == 'zoom-lens'
 

pokedex/util/get.py

@@ -1,15 +1,14 @@
-"""Provides simple functions for common queries
+"""Helpers for common ways to work with pokedex queries
 
 These include identifier- and name-based lookup, filtering out base forms
-of pokemon, ordering by name, and getting canonical "pokedex" lists (i.e.
-ordered and without cruft like alternate pokemon forms or Shadow moves)
+of pokemon, and filtering/ordering by name.
 """
 
 from sqlalchemy.orm import aliased
 
 from pokedex.db import tables
 
-### Getters
+### Getter
 
 def get(session, table, identifier=None, name=None, id=None,
         form_identifier=None, form_name=None, language=None, is_pokemon=None):
@@ -122,54 +121,3 @@ def order_by_name(query, table, language=None, *extra_languages):
         query = query.order_by(names_table.name)
     query = query.order_by(table.identifier)
     return query
-
-_name = object()
-def get_all(session, table, order=_name):
-    """Shortcut to get an ordered query from table.
-
-    session: The session to use
-    table: The table to select from
-    order: A clause to order by, or None for no ordering.
-        The default is to order by name; this can also be specified explicitly
-        with the table's name property (e.g. tables.Pokemon.name). Be aware
-        that the query's order_by will not order by name this way.
-    """
-    query = session.query(table)
-    if order is table.name or order is _name:
-        query = order_by_name(query, table)
-    elif order is not None:
-        query = query.order_by(order)
-    return query
-
-### Shortcuts
-
-def pokemon(session, order=tables.Pokemon.id):
-    """Return a query for all base form pokemon, ordered by id by default
-
-    See get_all for the session and order arguments (but note the default for
-    pokemon is to order by id).
-    """
-    query = get_all(session, tables.Pokemon, order=order)
-    query = query.filter(tables.Pokemon.forms.any())
-    return query
-
-def moves(session, order=_name):
-    """Return a query for moves in the mainline games (i.e. no Shadow moves)
-
-    See get_all for the session and order arguments.
-    """
-    return get_all(session, tables.Move, order=order).filter(tables.Move.id < 10000)
-
-def types(session, order=_name):
-    """Return a query for sane types (i.e. not ???, Shadow)
-
-    See get_all for the session and order arguments.
-    """
-    return get_all(session, tables.Type, order=order).filter(tables.Type.id < 10000)
-
-def items(session, order=_name):
-    """Return a query for items
-
-    See get_all for the session and order arguments.
-    """
-    return get_all(session, tables.Item, order=order)

pokedex/util/simple.py

@@ -0,0 +1,66 @@
+"""Simple lists of things for simple scripts
+
+If you want to get a pokemon list, and you don't want it to include three
+Wormadams and a whole bunch of Rotoms because of how the database is
+structured, this module is for you.
+
+The returned queries basically contain what a pokedex would show you.
+You should make no other assumptions about them.
+
+If you need to make assumptions, feel free to use these functions as examples
+of what to watch out for.
+"""
+
+from pokedex.db import tables
+from pokedex.util.get import filter_base_forms, order_by_name
+
+def pokemon(session):
+    """Get a "sane" list of pokemon
+
+    WARNING: The result of this function is not very well defined.
+    If you want something specific, build that specific query yourself.
+
+    Currently, all base forms are returned, in evolution-preserving order
+    """
+    query = session.query(tables.Pokemon)
+    query = query.order_by(tables.Pokemon.order)
+    query = filter_base_forms(query)
+    return query
+
+def moves(session):
+    """Get a "sane" list of moves
+
+    WARNING: The result of this function is not very well defined.
+    If you want something specific, build that specific query yourself.
+
+    Currently, moves from mainline games are returned, sored by name
+    """
+    query = session.query(tables.Move)
+    query = order_by_name(query, tables.Move)
+    query = query.filter(tables.Move.id < 10000)
+    return query
+
+def types(session):
+    """Get a "sane" list of types
+
+    WARNING: The result of this function is not very well defined.
+    If you want something specific, build that specific query yourself.
+
+    Currently, generation V types are returned, sored by name
+    """
+    query = session.query(tables.Type)
+    query = order_by_name(query, tables.Type)
+    query = query.filter(tables.Type.id < 10000)
+    return query
+
+def items(session):
+    """Get a "sane" list of items
+
+    WARNING: The result of this function is not very well defined.
+    If you want something specific, build that specific query yourself.
+
+    Currently, items are sored by name
+    """
+    query = session.query(tables.Item)
+    query = order_by_name(query, tables.Item)
+    return query