Split query specification (kind, filter, ancestor, etc.) from query execution (results, cursor, more_results)

[tseaver]

(Continued from #432)

In larger applications, I envision a set of Query objects which are pre-built, something like "prepared statements" in SQL-based apps. Application code would reuse them over and over without needing to re-construct them on the fly.

In the current setup, the application code would have to do that by cloning the queries (even though they weren't going to be modifying the filters). It would be nice if the short-lived / stateful concerns weren't intertwined with the long-lived, stateless ones.

The pattern I'm proposing is something like::

from datastore.query import Query

pending_reports = Query('Expense Report).filter('status', '==', 'pending')

def show_pending_reports(request):
    cursor = pending_reports.fetch()

    for report in cursor:
        show_report(report)

Under the covers, iterating the cursor would cause it to fetch subsequent pages until there were no more (or until the user-supplied limit had been reached). The source Query (pending_reports) would be uninvolved in any of that machinery.

The cursor would have methods for checking whether the back-end reported more results were available, as well as keeping (internal) track for the start_cursor / end_cursor bits for paging. If the user wanted to interact with them directly, she could:

def show_pending_reports(request):
    cursor = pending_reports.fetch()

    for page in cursor.pages():
        for report in page:
            show_report(report)