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.
LogicalFileReferenceField([checksum_field])	Store a mafw.storage.LogicalFileReference as portable text.
LogicalFileReferenceListField([checksum_field])	Store an ordered list of logical references as semicolon-separated text.
StorageField([checksum_field])	Store a physical path or logical reference in one self-describing text field.
StorageFieldAccessor(model, field, name)	Maintain physical-only checksum propagation for storage-aware fields.
StorageListField([checksum_field])	Store an ordered, self-describing list of physical and logical values.

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, FileNameListField, StorageField, or StorageListField, then it is automatically filled when the associated field is set. Storage-aware fields propagate only all-physical values; logical or mixed values require an explicit resolved path or digest.

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] | None) → str | None

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 | None) → str | None

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 | None) → str | None

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

python_value(value: str) → list[Path]

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

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

Bases: _LogicalFileReferenceFieldBase

Store a mafw.storage.LogicalFileReference as portable text.

checksum_field records the linked checksum field name for later storage integration. Assignment does not populate that field: logical references are unresolved identifiers, not filesystem paths or checksum digests.

Parameters:

checksum_field – Optional name of the associated checksum field.

Added in version 2.4.

Initialize the field and retain optional checksum association metadata.

db_value(value: LogicalFileReference | str | None) → str | None

Convert a reference or serialized reference to database text.

python_value(value: str | None) → LogicalFileReference | None

Parse database text into a logical reference, preserving SQL NULL.

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

Bases: _LogicalFileReferenceFieldBase

Store an ordered list of logical references as semicolon-separated text.

Empty or null values map to an empty list. A single reference or serialized reference string is accepted as a one-element list. Empty elements in a non-empty serialized list are rejected.

Parameters:

checksum_field – Optional name of the associated checksum field.

Added in version 2.4.

Initialize the field and retain optional checksum association metadata.

db_value(value: Any) → str

Serialize an iterable of references, or one reference, to text.

python_value(value: str | None) → list[LogicalFileReference]

Parse the stored list, preserving its order and duplicate entries.

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

Bases: TextField

Store a physical path or logical reference in one self-describing text field.

Ordinary physical paths retain their legacy untagged representation. Paths beginning with the reserved mafw: prefix are written with a mafw:path: envelope. Logical references use mafw:logical:<volume>:<relative/path>. Incomplete or malformed reserved-looking values remain legacy physical paths; a complete unknown codec identifier raises ValueError.

A string assigned in Python is always treated as a physical path. Assign a LogicalFileReference object for logical data. The codec never resolves paths or accesses a storage service.

Automatic checksum propagation occurs only for physical values. For a logical value, provide a resolved physical path or an already computed checksum explicitly.

Parameters:

checksum_field – Optional name of the associated checksum field.

Added in version 2.4.

Initialize a text field with an optional physical checksum association.

accessor_class

alias of StorageFieldAccessor

db_value(value: str | Path | LogicalFileReference | None) → str | None

Serialize one physical or logical storage value.

python_value(value: str | None) → Path | LogicalFileReference | None

Decode storage text into a physical path or logical reference.

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

Bases: FieldAccessor

Maintain physical-only checksum propagation for storage-aware fields.

Added in version 2.4.

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

Bases: StorageField

Store an ordered, self-describing list of physical and logical values.

Values use the existing semicolon-separated text format. A physical list member containing ; is rejected because it cannot be represented unambiguously. Existing text is decoded using the historical split rule. SQL NULL and empty text both produce an empty list.

Parameters:

checksum_field – Optional name of the associated checksum field.

Added in version 2.4.

Initialize a text field with an optional physical checksum association.

db_value(value: Iterable[str | Path | LogicalFileReference] | str | Path | LogicalFileReference | None) → str | None

Serialize list members in order without escaping legacy delimiters.

python_value(value: str | None) → list[Path | LogicalFileReference]

Decode a semicolon-separated list, preserving order and duplicates.

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

Bases: TextField

Share checksum association metadata between logical-reference fields.

Initialize the field and retain optional checksum association metadata.

mafw.db.fields._decode_storage_value(value: str) → Path | LogicalFileReference

Decode a complete known envelope; otherwise retain legacy path text.

mafw.db.fields._encode_storage_value(value: str | Path | LogicalFileReference, *, list_member: bool = False) → str

Encode one physical path or logical reference without resolving it.

mafw.db.fields._storage_checksum_value(field: StorageField, value: Any) → Any

Return an all-physical assignment eligible for automatic hashing.

mafw.db.fields._STORAGE_LOGICAL_PREFIX = 'mafw:logical:'

Envelope marker for logical file references.

mafw.db.fields._STORAGE_PATH_PREFIX = 'mafw:path:'

Envelope marker for physical paths that need an explicit storage type.

mafw.db.fields._STORAGE_PREFIX = 'mafw:'

Reserved prefix for future self-describing storage codecs.