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
`mafw_model_register`	This is the instance of the ModelRegister

Functions

make_prefixed_suffixed_name(model_class)

Generate a table name with optional prefix and suffix for a given model class.

Classes

`MAFwBaseModel`(args, *kwargs)	The base model for the MAFw library.
`RegisteredMeta`(name, bases, attrs, **kwargs)	Metaclass for registering models with the MAFw model registry.

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.

This class extends peewee’s Model with several additional features:

Automatic model registration: Models are automatically registered with the MAFw model registry during class definition, enabling dynamic discovery and management of database models.
Trigger support: The class supports defining database triggers through the triggers() method, which are automatically created when the table is created. File removal triggers can also be automatically generated using the file_trigger_auto_create boolean flag in the meta class. See also file_removal_triggers().
Standard upsert operations: Provides std_upsert() and std_upsert_many() methods for performing upsert operations that work with SQLite and PostgreSQL.
Dictionary conversion utilities: Includes to_dict(), from_dict(), and update_from_dict() methods for easy serialization and deserialization of model instances.
Customizable table naming: Supports table name prefixes and suffixes through the Meta class with prefix and suffix attributes. See make_prefixed_suffixed_name().
Automatic table creation control: The automatic_creation Meta attribute controls whether tables are automatically created when the application starts.

Note

The automatic model registration can be disabled for one single model class using the keyword argument do_not_register passed to the RegisteredMeta meta-class. For example:

class AutoRegisterModel(MAFwBaseModel):
    pass


class NoRegisterModel(MAFwBaseModel, do_not_register=True):
    pass

the first class will be automatically registered, while the second one will not. This is particularly useful if the user wants to define a base model class for the whole project without having it in the register where only concrete Model implementations are stored.

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 file_removal_triggers() → list[Trigger][source]

Generate a list of triggers for automatic file removal when records are deleted.

This method creates database triggers that automatically handle file cleanup when records containing FileNameField fields are removed from the database table. The triggers insert the filenames and checksums into the OrphanFile table for later processing.

The triggers are only created if the model has at least one field of type FileNameField. If no such fields exist, an empty list is returned.

FileNameListField is a subclass of FileNameField and is treated in the same way.

Added in version v2.0.0.

Note

This functionality requires the file_trigger_auto_create attribute in the model’s Meta class to be set to True for automatic trigger creation.

Returns:: A list containing the trigger object for file removal, or an empty list if no FileNameField fields are found.
Return type:: list[Trigger]

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 get_fields_by_type(field_type: type[Field]) → dict[str, Field][source]

Return a dict {field_name: field_object} for all fields of the given type.

Added in version v2.0.0.

Parameters:: field_type (peewee.Field) – Field type
Returns:: A dict {field_name: field_object} for all fields of the given type.
Return type:: dict[str, peewee.Field]

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.