feat: add new_transaction support

[daniel-sanche]

This PR modifies the Transaction class to add a new begin_later argument.

When True, the transaction will not initialize itself at the start of the context manager __enter__ block. Instead, it will only begin at the first rpc. If the first rpc is a read call, this allows us to create the transaction at the same time as the call, saving a network call.

This new behaviour is enabled by default, and is aligned with changes in other languages

---

For reviewers

In Python, a transaction is created in a context manager, and typically interacted with through the client (which passes through to the Transaction object when needed):

with client.transaction(begin_later=True):
  client.query(query)
  client.get(entity)
  client.put(entity)
  client.delete(entity)

if beginlater is False, it will call begin automatically when entering that context manager block (using __enter_\ method), retrieving a transaction_id from the server. Otherwise, begin is deferred until a get/query/commit call forces the transaction to talk to the backend

States

The state machine looks like this. Green lines denote transitions that are only valid when begin_later=True orange lines denote transitions that are valid when begin_later=False

• Starts out in INITIAL state
  • if begin_later is true, it allows you to immediately start collecting put and get mutations. Otherwise any rpcs in the INITIAL state will throw an exception
• When begin is called and the transaction receives and ID from the server, it moves into IN_PROGRESS state
  • if begin_later is false, it will immediately call begin when enter is called (called by the with statement)
  • if begin_later is true, it will call begin when it encounters the first get or query call
  • user can also always call begin manually
• a rollback from either state (or a commit with no content from INITIAL) will result in the terminal ABORTED state
• a commit from IN_PROGRESS results in the terminal FINISHED state
• any invalid attempted transitions will raise an exception

[cindy-peng]

This PR modifies the Transaction class to add a new begin_later argument.

When True, the transaction will not initialize itself at the start of the context manager __enter__ block. Instead, it will only begin at the first rpc. If the first rpc is a read call, this allows us to create the transaction at the same time as the call, saving a network call.

This new behaviour is enabled by default, and is aligned with changes in other languages

Hi Daniel, it looks like begin_later is by default set to False so by default disabled? Do we want this behavior to be enabled by default?

[daniel-sanche]

Yes, I believe it's intended to be off by default. Having it on or off may be more efficient depending on the circumstances, so we opted to keep it off by default (correct me if I'm misremembering @danieljbruce @bhshkh)