Add a convenience method to fetch data for a single row

[tseaver]

@jonparrott would prefer:

row = database.read_row(table='Albums', columns=('MarketingBudget',), key=[1, 1]))

[tseaver]

@jonparrott read takes a keyset and returns a sequence of row tuples. If we implement read_rows as a thin wrapper around read, what semantics should we have for a read which returns no rows? Raise a NotFound? Return None?

[theacodes]

I'm leaning towards NotFound (like datastore), but @vkedia should weigh in.

[mcurtiss]

It would be great for query iterators also to have a get_one or one method that returns the single row yielded by the query, else throwing an exception.

Note that SQLAlchemy has a similar one method: http://docs.sqlalchemy.org/en/latest/orm/query.html#sqlalchemy.orm.query.Query.one

[vkedia]

Regarding #3021 (comment) it is definitely valid for the read to not return any row at all. User might just be checking for the existence of row. So None seems better.

Regarding #3021 (comment) I agree it would be useful to have this and some of the other methods like one_or_none, first. Is there no common Python library that exposes these type of methods for an arbitrary iterator. Similar to this in Java.

[lukesneeringer]

Regarding #3021 (comment) it is definitely valid for the read to not return any row at all. User might just be checking for the existence of row. So None seems better.

I would prefer empty list over None, I think.
I would prefer an exception actually, since that is what other Python ORMs do.

Regarding #3021 (comment) I agree it would be useful to have this and some of the other methods like one_or_none, first. Is there no common Python library that exposes these type of methods for an arbitrary iterator. Similar to this in Java.

I am not aware of any such animal (nor have I ever wanted one).

[lukesneeringer]

What semantics would we want for a read that returns more than one row? We could have it send limit=1 to read, but both SQLAlchemy and Django raise exceptions in this case.