l.s.d.t.DatabaseTransactionPolicy : class documentation

Part of lp.services.database.transaction_policy View In Hierarchy

Context manager for read-only transaction policy.

Use this to define regions of code that explicitly allow or disallow
changes to the database:

    # We want to be sure that inspect_data does not inadvertently
    # make any changes in the database, but we can't run it on the
    # slave store because it doesn't tolerate replication lag.
    with DatabaseTransactionPolicy(read_only=True):
        inspect_data()

The simplest way to use this is as a special transaction:
 * You must commit/abort before entering the policy.
 * Exiting the policy through an exception aborts its changes.
 * Before completing a read-write policy region, you must commit or abort.

You can also have multiple transactions inside one policy, however; the
policy still applies after a commit or abort.

Policies can be nested--a nested policy overrides the one it's nested in.
After the nested policy has exited, the previous policy applies again:

    # This code needs to control the database changes it makes very
    # carefully.  Most of it is just gathering data, with one quick
    # database update at the end.
    with DatabaseTransactionPolicy(read_only=True):
        data = gather_data()
        more_data = figure_stuff_out(data)

        # End the ongoing transaction so we can go into our update.
        transaction.commit()

        # This is the only part where we update the database!
        with DatabaseTransactionPolicy(read_only=False):
            update_model(data, more_data)
            transaction.commit()

        # We've got a bit more work to do here, but it doesn't
        # affect the database.
        write_logs(data)
        notify_user(more_data)
Method __init__ Create a policy.
Method __enter__ Enter this policy.
Method __exit__ Exit this policy.
Method _isInTransaction Is our store currently in a transaction?
Method _checkNoTransaction Verify that no transaction is ongoing.
Method _flushPendingWrites Flush any pending object changes to the database.
Method _getCurrentPolicy Read the database session's default transaction read-only policy.
Method _setPolicy Set the database session's default transaction read-only policy.
def __init__(self, store=None, read_only=False):
Create a policy.

Merely creating a policy has no effect. Use it with "with" to affect writability of database transactions.

ParametersstoreThe store to set policy on. Defaults to the main master store. You don't want to use this on a slave store!
read_onlyIs this policy read-only?
def __enter__(self):
Enter this policy.

Commits the ongoing transaction, and sets the selected default read-only policy on the database.

RaisesTransactionInProgressif a transaction was already ongoing.
def __exit__(self, exc_type, *args):
Exit this policy.

Commits or aborts, depending on mode of exit, and restores the previous default read-only policy.

ReturnsTrue -- any exception will continue to propagate.
RaisesTransactionInProgressif trying to exit normally from a read-write policy without closing its transaction first.
def _isInTransaction(self):
Is our store currently in a transaction?
def _checkNoTransaction(self, error_msg):
Verify that no transaction is ongoing.
Parameterserror_msgThe error message to use if the user got this wrong (i.e. if we're in a transaction).
RaisesTransactionInProgressif we're in a transaction.
def _flushPendingWrites(self):

Flush any pending object changes to the database.

If you see an InternalError exception during this flush, it probably means one of two things:

  1. Code within a read-only policy made model changes.
  2. Code within a policy exited normally despite an error that left the transaction in an unusable state.
def _getCurrentPolicy(self):
Read the database session's default transaction read-only policy.

The information is retrieved from the database, so this will give a sensible answer even when no DatabaseTransactionPolicy is in effect.

ReturnsTrue for read-only policy, False for read-write policy.
def _setPolicy(self, read_only=True):
Set the database session's default transaction read-only policy.
Parametersread_onlyTrue for read-only policy, False for read-write policy.
API Documentation for Launchpad, generated by pydoctor at 2019-11-11 00:00:24.