mafw.db.db_model

The module provides functionality to MAFw to interface to a DB.

Module Attributes

database_proxy

This is a placeholder for the real database object that will be known only at run time

Classes

MAFwBaseModel(*args, **kwargs)

The base model for the MAFw library.

Exceptions

MAFwBaseModelDoesNotExist

Raised when the base model class is not existing.

exception mafw.db.db_model.MAFwBaseModelDoesNotExist[source]

Bases: MAFwException

Raised when the base model class is not existing.

class mafw.db.db_model.MAFwBaseModel(*args, **kwargs)[source]

Bases: Model

The base model for the MAFw library.

Every model class (table) that the user wants to interface must inherit from this base.

DoesNotExist: alias of MAFwBaseModelDoesNotExist

classmethod create_table(safe: bool = True, **options: Any) → None[source]

Create the table in the underlying DB and all the related trigger as well.

If the creation of a trigger fails, then the whole table dropped, and the original exception is re-raised.

Warning

Trigger creation has been extensively tested with SQLite, but not with the other database implementation. Please report any malfunction.

Parameters:

safe (bool, Optional) – Flag to add an IF NOT EXISTS to the creation statement. Defaults to True.
options – Additional options passed to the super method.

classmethod from_dict(data: dict[str, Any], ignore_unknown: bool = False) → MAFwBaseModel[source]

Create a new model instance from dictionary

Parameters:

data (dict[str, Any]) – The dictionary containing the key/value pairs of the model.
ignore_unknown (bool) – If unknown dictionary keys should be ignored.

Returns:

A new model instance.

Return type:

MAFwBaseModel

classmethod std_upsert(_MAFwBaseModel__data: dict[str, Any] | None = None, **mapping: Any) → ModelInsert[source]

Perform a so-called standard upsert.

An upsert statement is not part of the standard SQL and different databases have different ways to implement it. This method will work for modern versions of sqlite and postgreSQL. Here is a detailed explanation for SQLite.

An upsert is a statement in which we try to insert some data in a table where there are some constraints. If one constraint is failing, then instead of inserting a new row, we will try to update the existing row causing the constraint violation.

A standard upsert, in the naming convention of MAFw, is setting the conflict cause to the primary key with all other fields being updated. In other words, the database will try to insert the data provided in the table, but if the primary key already exists, then all other fields will be updated.

This method is equivalent to the following:

class Sample(MAFwBaseModel):
    sample_id = AutoField(
        primary_key=True,
        help_text='The sample id primary key',
    )
    sample_name = TextField(help_text='The sample name')


(
    Sample.insert(sample_id=1, sample_name='my_sample')
    .on_conflict(
        preserve=[Sample.sample_name]
    )  # use the value we would have inserted
    .execute()
)

Parameters:

__data (dict, Optional) – A dictionary containing the key/value pair for the insert. The key is the column name. Defaults to None
mapping – Keyword arguments representing the value to be inserted.

classmethod std_upsert_many(rows: Iterable[Any], fields: list[str] | None = None) → ModelInsert[source]

Perform a standard upsert with many rows.