Class Transaction (2.0.1)

Transaction(client, read_only=False)

An abstraction representing datastore Transactions.

Transactions can be used to build up a bulk mutation and ensure all or none succeed (transactionally).

For example, the following snippet of code will put the two save operations (either insert or upsert) into the same mutation, and execute those within a transaction:

.. testsetup:: txn-put-multi, txn-api

import os
import uuid

from google.cloud import datastore
from tests.system.test_system import Config  # system tests

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))
key1 = client.key('_Doctest')
entity1 = datastore.Entity(key=key1)
entity1['foo'] = 1337

key2 = client.key('_Doctest', 'abcd1234')
entity2 = datastore.Entity(key=key2)
entity2['foo'] = 42

Config.TO_DELETE.extend([entity1, entity2])

.. doctest:: txn-put-multi

>>> with client.transaction():
...     client.put_multi([entity1, entity2])

Because it derives from xref_Batch, Transaction also provides put and delete methods:

.. doctest:: txn-api

with client.transaction() as xact: ... xact.put(entity1) ... xact.delete(entity2.key)

By default, the transaction is rolled back if the transaction block exits with an error:

.. testsetup:: txn-error

import os
import uuid

from google.cloud import datastore

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))

def do_some_work():
    return

class SomeException(Exception):
    pass

.. doctest:: txn-error

>>> with client.transaction():
...     do_some_work()
...     raise SomeException  # rolls back
Traceback (most recent call last):
  ...
SomeException

If the transaction block exits without an exception, it will commit by default.

with client.transaction(): ... entity = Entity(key=client.key('Thing')) ... client.put(entity)

Once you exit the transaction (or call commit), the automatically generated ID will be assigned to the entity:

.. doctest:: txn-entity-key-after

  >>> with client.transaction():
  ...     entity = Entity(key=client.key('Thing'))
  ...     client.put(entity)
  ...     print(entity.key.is_partial)  # There is no ID on this key.
  ...
  True
  >>> print(entity.key.is_partial)  # There *is* an ID.
  False

If you don't want to use the context manager you can initialize a transaction manually:

.. doctest:: txn-manual

transaction = client.transaction() transaction.begin()

entity = Entity(key=client.key('Thing')) transaction.put(entity)

transaction.commit()

Parameters
Name	Description
`client`	`Client` the client used to connect to datastore.
`read_only`	`bool` indicates the transaction is read only.

Properties

id

Getter for the transaction ID.

Returns
Type	Description
`str`	The ID of the current transaction.

mutations

Getter for the changes accumulated by this batch.

Every batch is committed with a single commit request containing all the work to be done as mutations. Inside a batch, calling put with an entity, or delete with a key, builds up the request by adding a new mutation. This getter returns the protobuf that has been built-up so far.

Returns
Type	Description
`iterable`	The list of `.datastore_pb2.Mutation` protobufs to be sent in the commit request.

namespace

Getter for namespace in which the batch will run.

Returns
Type	Description
`str`	The namespace in which the batch will run.

project

Getter for project in which the batch will run.

Returns
Type	Description
`str`	The project in which the batch will run.

Methods

begin

begin(retry=None, timeout=None)

Begins a transaction.

This method is called automatically when entering a with statement, however it can be called explicitly if you don't want to use a context manager.

Parameters
Name	Description
`retry`	`google.api_core.retry.Retry` A retry object used to retry requests. If `None` is specified, requests will be retried using a default configuration.
`timeout`	`float` Time, in seconds, to wait for the request to complete. Note that if `retry` is specified, the timeout applies to each individual attempt.

Exceptions
Type	Description
`exceptions.ValueError	if the transaction has already begun.

commit

commit(retry=None, timeout=None)

Commits the transaction.

This is called automatically upon exiting a with statement, however it can be called explicitly if you don't want to use a context manager.

This method has necessary side-effects:

Sets the current transaction's ID to None.

Parameters
Name	Description
`retry`	`google.api_core.retry.Retry` A retry object used to retry requests. If `None` is specified, requests will be retried using a default configuration.
`timeout`	`float` Time, in seconds, to wait for the request to complete. Note that if `retry` is specified, the timeout applies to each individual attempt.

current

current()

Return the topmost transaction.

Returns
Type	Description
`Transaction or None`	The current transaction (if any are active).

delete

delete(key)

Remember a key to be deleted during commit.

Parameter
Name	Description
`key`	`Key` the key to be deleted.

Exceptions
Type	Description
`exceptions.ValueError	if the batch is not in progress, if key is not complete, or if the key's `project` does not match ours.

put

put(entity)

Adds an entity to be committed.

Ensures the transaction is not marked readonly. Please see documentation at xref_put

Parameter
Name	Description
`entity`	`Entity` the entity to be saved.

Exceptions
Type	Description
`RuntimeError	if the transaction is marked ReadOnly

rollback

rollback(retry=None, timeout=None)

Rolls back the current transaction.