mafw.db.std_tables

Module provides standard tables that are included in all database created by MAFw processor.

Standard tables are automatically created and initialized by a Processor or a ProcessorList when opening a database connection.

This means that if a processor receives a valid database object, then it will suppose that the connection was already opened somewhere else (either from a ProcessorList or a third party) and thus it is not creating the standard tables.

If a processor is constructed using a database configuration dictionary, then it will first try to open a connection to the DB, then creating all standard tables and finally executing their StandardTable.init method. The same apply for the Processor list.

In other words, object responsible to open the database connection is taking care also of creating the standard tables and of initializing them. If the user opens the connection and passes it to a Processor or ProcessorList, then the user is responsible to create the standard tables and to initialize them.

All standard tables must derive from the StandardTable to have the same interface for the initialization.

Classes

`OrphanFile`(args, *kwargs)	A Model for the files to be removed from disc
`PlotterOutput`(args, *kwargs)	A model for the output of the plotter processors.
`StandardTable`(args, *kwargs)	A base class for tables that are generated automatically by the MAFw processor.
`StorageVolume`(args, *kwargs)	Persist logical storage-volume identity independently of its physical root.
`TriggerDisabler`(trigger_type_id)	A helper tool to disable a specific type of triggers.
`TriggerStatus`(args, *kwargs)	A Model for the trigger status

Exceptions

`OrphanFileDoesNotExist`	An exception raised when trying to access a not existing table.
`PlotterOutputDoesNotExist`	An exception raised when trying to access a not existing table.
`StandardTableDoesNotExist`	An exception raised when trying to access a not existing table.
`StorageVolumeDoesNotExist`	Raised when a requested storage-volume record does not exist.
`TriggerStatusDoesNotExist`	An exception raised when trying to access a not existing table.

exception mafw.db.std_tables.OrphanFileDoesNotExist[source]

Bases: DoesNotExist

An exception raised when trying to access a not existing table.

exception mafw.db.std_tables.PlotterOutputDoesNotExist[source]

Bases: DoesNotExist

An exception raised when trying to access a not existing table.

exception mafw.db.std_tables.StandardTableDoesNotExist[source]

Bases: Exception

An exception raised when trying to access a not existing table.

exception mafw.db.std_tables.StorageVolumeDoesNotExist[source]

Bases: DoesNotExist

Raised when a requested storage-volume record does not exist.

Added in version 2.4.

exception mafw.db.std_tables.TriggerStatusDoesNotExist[source]

Bases: Exception

An exception raised when trying to access a not existing table.

class mafw.db.std_tables.OrphanFile(*args, **kwargs)[source]

Bases: StandardTable

A Model for the files to be removed from disc

Changed in version v2.0.0: The checksum field is set to allow null values. The class is set not to automatically generate triggers for file removal

DoesNotExist: alias of OrphanFileDoesNotExist

class mafw.db.std_tables.PlotterOutput(*args, **kwargs)[source]

Bases: StandardTable

A model for the output of the plotter processors.

filename_list stores physical paths or logical references using the self-describing storage codec. Existing physical-only rows keep their original representation and schema. checksum stores the digest computed from resolved output files.

Changed in version 2.4: filename_list now also stores logical output references without adding a database column.

DoesNotExist: alias of PlotterOutputDoesNotExist

class mafw.db.std_tables.StandardTable(*args, **kwargs)[source]

Bases: MAFwBaseModel

A base class for tables that are generated automatically by the MAFw processor.

DoesNotExist: alias of StandardTableDoesNotExist

classmethod init() → None[source]: The user must overload this method, if he wants some specific operations to be performed on the model everytime the database is connected.

class mafw.db.std_tables.StorageVolume(*args, **kwargs)[source]

Bases: StandardTable

Persist logical storage-volume identity independently of its physical root.

created_at and last_seen default to the current UTC timestamp stored without timezone metadata, matching the database representation used by MAFw migration history. Later storage-service initialization updates last_seen after validating the volume. Standard-table initialization is deliberately a no-op so existing volume identities are preserved.

The table contains no storage root. Its UUID identifies the volume, not any individual file.

Added in version 2.4.

DoesNotExist: alias of StorageVolumeDoesNotExist

class mafw.db.std_tables.TriggerDisabler(trigger_type_id: int)[source]

Bases: object

A helper tool to disable a specific type of triggers.

Not all SQL dialects allow to temporarily disable trigger execution.

In order overcome this limitation, MAFw has introduced a practical workaround. All types of triggers are active by default but they can be temporarily disabled, by changing their status in the TriggerStatus table.

In order to disable the trigger execution, the user has to set the status of the corresponding status to 0 and also add a when condition to the trigger definition.

Here is an example code:

class MyTable(MAFwBaseModel):
    id_ = AutoField(primary_key=True)
    integer = IntegerField()
    float_num = FloatField()

    @classmethod
    def triggers(cls):
        return [
            Trigger(
                'mytable_after_insert',
                (TriggerWhen.After, TriggerAction.Insert),
                cls,
                safe=True,
            )
            .add_sql(
                'INSERT INTO target_table (id__id, half_float_num) VALUES (NEW.id_, NEW.float_num / 2)'
            )
            .add_when(
                '1 == (SELECT status FROM trigger_status WHERE trigger_type_id == 1)'
            )
        ]

When you want to perform a database action with the trigger disabled, you can either use this class as context manager or call the disable() and enable() methods.

# as a context manager
with TriggerDisabler(trigger_type_id = 1):
    # do something without triggering any trigger of type 1.

# with the explicit methods
disabler = TriggerDisabler(1)
disabler.disable()
# do something without triggering any trigger of type 1.
disabler.enable()

When using the two explicit methods, the responsibility to assure that the triggers are re-enabled in on the user.

Context-manager nesting is tracked within the current execution context. This preserves nested use by one thread or asynchronous task, but does not coordinate independent database connections or processes that modify the same database.

For example, if trigger 4 is initially enabled, it remains disabled until the outer context exits:

# Before entering: trigger 4 is enabled.
with TriggerDisabler(4):
    # Trigger 4 is disabled.
    with TriggerDisabler(4):
        # Trigger 4 remains disabled.
        pass
    # Trigger 4 is still disabled after the inner context exits.
# Trigger 4 is enabled again after the outer context exits.

Constructor parameters:

Parameters:: trigger_type_id (int) – the id of the trigger to be temporary disabled.

disable() → None[source]: Disable the trigger

enable() → None[source]: Enable the trigger

class mafw.db.std_tables.TriggerStatus(*args, **kwargs)[source]

Bases: StandardTable

A Model for the trigger status

DoesNotExist: alias of TriggerStatusDoesNotExist

classmethod init() → None[source]: Resets all triggers to enable when the database connection is opened.

mafw.db.std_tables._utc_now_naive() → datetime[source]: Return current UTC time without tzinfo for portable Peewee DateTimeField storage.

mafw.db.std_tables._trigger_contexts: ContextVar = <ContextVar name='trigger_contexts' default={}>: Track trigger contexts within the current execution context, keyed by database and trigger ID.