mafw.db.fields

Module provides customised model fields specific for MAFw.

Classes

FileChecksumField([null, index, unique, ...])	A field to be used for file checksum.
FileChecksumFieldAccessor(model, field, name)	Field accessor specialized for file checksum fields.
FileNameField([checksum_field])	Field to be used for filenames.
FileNameFieldAccessor(model, field, name)	A field accessor specialized for filename fields.
FileNameListField([checksum_field])	A field for a list of file names.

class mafw.db.fields.FileChecksumField(null=False, index=False, unique=False, column_name=None, default=None, primary_key=False, constraints=None, sequence=None, collation=None, unindexed=False, choices=None, help_text=None, verbose_name=None, index_type=None, db_column=None, _hidden=False)

Bases: TextField

A field to be used for file checksum.

It is the evolution of the TextField for storing file checksum hexadecimal digest.

If linked to a FileNameField or FileNameListField, then it will be automatically filled when the primary file name (or list of file names) field is set.

If the user decides to set its value manually, then he can provide either the string with the hexadecimal characters as calculated by file_checksum(), or simply the filename (or filename list) and the field will perform the calculation automatically.

accessor_class

The specific field accessor class

alias of FileChecksumFieldAccessor

db_value(value: str | Path | list[str | Path]) → str

Converts the python assigned value to the DB type.

The checksum will be stored in the DB as a string containing only hexadecimal characters (see hexdigest).

The user can provide the checksum directly or the path to the file or a list of path to files. If a Path, or list of Path, is provided, then the checksum will be calculated, if a str (a path converted into a string) is provided, the function will try to see if a file with that path exists. If so, the checksum will be calculated, if not, the original string is assumed to be the checksum.

Parameters:

value (str | Path | list[str | Path]) – The checksum or path to the file, or list of path to files for which the checksum has to be stored.

Returns:

The checksum string for the database storage.

Return type:

str

class mafw.db.fields.FileChecksumFieldAccessor(model, field, name)

Bases: FieldAccessor

Field accessor specialized for file checksum fields.

When the field is directly set, then an initialization flag in the model instance is turned to True to avoid that the linked primary field will overrule this value again.

For each checksum field named my_checksum, the model instance will get an attribute: init_my_checksum to be used as an initialization flag.

Once the field is manually set, to re-establish the automatic mechanism, the user has to manually toggle the initialization flag.

class mafw.db.fields.FileNameField(checksum_field: str | None = None, *args: Any, **kwargs: Any)

Bases: TextField

Field to be used for filenames.

It is just an overload of TextField, that allows to apply filters and python functions specific to filenames.

If the user specifies the name of a file checksum field, then when this field is updated, the checksum one will also be automatically updated.

See also

• FileNameListField for a field able to store a list of filenames.

• remove_widow_db_rows() for a function removing entries from a database table where the corresponding files on disk are missing.

• verify_checksum() for a function comparing the actual checksum with the stored one and in case removing outdated entries from the DB.

Constructor parameter:

Parameters:

checksum_field (str, Optional) – The name of the checksum field linked to this filename. Defaults to None.

accessor_class

The specific accessor class

alias of FileNameFieldAccessor

db_value(value: str | Path) → str

Converts the input python value into a string for the DB.

python_value(value: str) → Path | None

Converts the db value from str to Path

The return value might also be None, if the user set the field value to null.

Parameters:

value (str) – The value of the field as stored in the database.

Returns:

The converted value as a path. It can be None, if value was stored as null.

Return type:

Path | None

class mafw.db.fields.FileNameFieldAccessor(model, field, name)

Bases: FieldAccessor

A field accessor specialized for filename fields.

In the constructor of the FileNameField and subclasses, the user can specify the name of a checksum field linked to this filename. This is very useful because in this way, the user does not have to manually assign any value to this field that will simply be automatically updated when the filename field is updated.

The user can disable this automatic feature either removing the link in the FileNameField or simply assigning a value to the FileChecksumField.

class mafw.db.fields.FileNameListField(checksum_field: str | None = None, *args: Any, **kwargs: Any)

Bases: FileNameField

A field for a list of file names.

The evolution of the FileNameField, this field is able to store a list of filenames as a ‘;’ separated string of full paths.

It is meant to be used when a processor is saving a bunch of correlated files that are to be used all together.

In a similar way as its parent class, it can be link to a checksum field, in this case, the checksum of the whole file list will be calculated.

Constructor parameter:

Parameters:

checksum_field (str, Optional) – The name of the checksum field linked to this filename. Defaults to None.

db_value(value: list[str | Path] | str | Path) → str

Converts the list of paths in a ‘;’ separated string

python_value(value: str) → list[Path]

Converts the ‘;’ separated string in a list of paths