Add a short explanation of Batches vs Transactions ?

[jgeewax]

I think it'd be pretty useful to explain what the difference is between these two... doesn't need to be long, but something explaining when to use each, with links off to the datastore API documentation explaining in more detail.

[dhermes]

Batches can safely be used never by a user. Transaction maps to a concept outside of our library. I think a simpler solution could be just to put the Batches section below the fold somehow. WDYT?

A Batch powers get() / put() / delete() under the covers and it turns out most of the features needed to do this are needed for a Transaction (essentially everything except making the begin_transaction request and sending the transaction ID in the request),

[jgeewax]

OK so you're saying we don't ever have a good reason to use a Batch by itself? If so, should we remove it's page from the docs?

[tseaver]

@jgeewax the point of Batch is to allow the developer to control the number of API requests, without the overhead / semantics of a transaction. E.g., this generates only one request, without a transaction being created / finished:

with datastore.Batch(connection) as batch:
    batch.put([entity1, entity2]
    batch.delete([key3, key4]

This might be a "power user" feature, but it should be documented.

[dhermes]

I think we can close this out. @jgeewax Feel free to re-open if you still think its an issue. Otherwise our practice of "autodoc" the things will be the standard.

Aside: We put connection module autodocs in the same file as client modules since users don't likely need to know about connection stuff. We could put Batch with Transaction if it were really an issue.