dhp.doq

DOQ

pronounced Duke allows you to query an list, iterable or generator of objects with a Django ORM like / Fluent interface. This is useful for exploratory programming and also it is just a nice, comfortable inteface to query your data objects. DOQ supports lazy evaluations and nested objects.

Example

Say you had a csv file of employee records and you wanted to list the employees in the IT department. Well you could do the traditional thing or ...

EmployeeRecord = namedtuple('EmployeeRecord', 'emp_id, name, dept, hired')


def csvtuples():
    '''csv named tuple emitter.'''
    reader = csv.reader(TEST_FILE)
    for emp in map(EmployeeRecord._make, reader):
        yield emp

doq = DOQ(data_objects=csvtuples())
for emp in doq.filter(dept='IT'):
    print(emp)

# Now let's list everyone who is not in IT.
for emp in doq.exclude(dept='IT'):
    print(emp)

# ok, now let's sort the not IT employees by name
for emp in doq.exclude(dept='IT').order_by('name'):
    print(emp)

Yes, it is just that easy. You can chain .filter() and .exclude(). There is a .get method that raises DoesNotExist and MultipleObjectsReturned. All that ooohey gooey goodness of an full blown ORM but quick and easy and works without a lot of setup.

Let’s throw some remote json data at the Duke and see what happens.

from dhp.structures import DictDot
from dhp.doq import DOQ
import requests

def json_ds(url):
    # fetch some json data, transform the returned dict to DictDot so
    # we can access attributes with dotted notation and then return
    # a DOQ with that data.
    data_objects = [DictDot(x) for x in requests.get(url).json()]
    return DOQ(data_objects=data_objects)

users = json_ds('http://jsonplaceholder.typicode.com/users')
type(users)         # prints  <class 'dhp.doq.DOQ'>
users.all().count   # prints 10
user = users.all()[0]
type(user)       # prints  <class 'dhp.structures.DictDot'>
user.id          # prints  1
user.address.suite  # prints  u'Apt. 556'
users.filter(address__suite__startswith='Apt.').count     # prints 3

One quick note before we head into the full documenation. DOQ is NOT a full blown Object Relation Manager. It does not create databases, nor know how to access them. If that is what you desire, then SQLAlchemy, Pony, PeeWeeDB or Django’s ORM is probably going to get you what you want.

If you are looking to slap some lipstick on a simple data source, well then, DOQ is your color. dhp.doq package for api specifics.