core.bones.file

The FileBone is a subclass of the TreeLeafBone class, which is a relational bone that can reference another entity’s fields. FileBone provides additional file-specific properties and methods, such as managing file derivatives, handling file size and mime type restrictions, and refreshing file metadata.

Module Contents

Classes

FileBone

A FileBone is a custom bone class that inherits from the TreeLeafBone class, and is used to store and manage

Functions

ensureDerived(key, srcKey, deriveMap[, refreshKey])

The function is a deferred function that ensures all pending thumbnails or other derived files
core.bones.file.ensureDerived(key, srcKey, deriveMap, refreshKey=None)

The function is a deferred function that ensures all pending thumbnails or other derived files are built. It takes the following parameters:

Parameters:

  • key (db.key) – The database key of the file-object that needs to have its derivation map updated.

  • srcKey (str) – A prefix for a stable key to prevent rebuilding derived files repeatedly.

  • deriveMap (dict[str,Any]) – A list of DeriveDicts that need to be built or updated.

  • refreshKey (db.Key) – If set, the function fetches and refreshes the skeleton after building new derived files.

The function works by fetching the skeleton of the file-object, checking if it has any derived files, and updating the derivation map accordingly. It iterates through the deriveMap items and calls the appropriate deriver function. If the deriver function returns a result, the function creates a new or updated resultDict and merges it into the file-object’s metadata. Finally, the updated results are written back to the database and the updateRelations function is called to ensure proper relations are maintained.

class core.bones.file.FileBone(*, derive=None, maxFileSize=None, validMimeTypes=None, refKeys=('name', 'mimetype', 'size', 'width', 'height', 'derived'), **kwargs)

Bases: viur.core.bones.treeleaf.TreeLeafBone

A FileBone is a custom bone class that inherits from the TreeLeafBone class, and is used to store and manage file references in a ViUR application.

Parameters:

  • format – Hint for the UI how to display a file entry (defaults to it’s filename)

  • maxFileSize (None | int) – The maximum filesize accepted by this bone in bytes. None means no limit. This will always be checked against the original file uploaded - not any of it’s derivatives.

  • derive (None | dict[str, Any]) –

    A set of functions used to derive other files from the referenced ones. Used fe. to create thumbnails / images for srcmaps from hires uploads. If set, must be a dictionary from string (a key from conf.file_derivations) to the parameters passed to that function. The parameters can be any type (including None) that can be json-serialized.

    # Example
derive = { "thumbnail": [{"width": 111}, {"width": 555, "height": 666}]}

  • validMimeTypes (None | list[str]) –

    A list of Mimetypes that can be selected in this bone (or None for any) Wildcards (“image/*”) are supported.

    # Example
validMimeTypes=["application/pdf", "image/*"]

  • refKeys (Optional[Iterable[str]]) –

Initializes a new Filebone. All properties inherited by RelationalBone are supported.

Parameters:

  • format – Hint for the UI how to display a file entry (defaults to it’s filename)

  • maxFileSize (None | int) – The maximum filesize accepted by this bone in bytes. None means no limit.

  • derive (None | dict[str, Any]) –

  • validMimeTypes (None | list[str]) –

  • refKeys (Optional[Iterable[str]]) –

This will always be checked against the original file uploaded - not any of it’s derivatives. :param derive: A set of functions used to derive other files from the referenced ones. Used to create thumbnails and images for srcmaps from hires uploads. If set, must be a dictionary from string (a key from) conf.file_derivations) to the parameters passed to that function. The parameters can be any type (including None) that can be json-serialized.

# Example
derive = {"thumbnail": [{"width": 111}, {"width": 555, "height": 666}]}
Parameters:

  • validMimeTypes (None | list[str]) –

    A list of Mimetypes that can be selected in this bone (or None for any). Wildcards (‘image*’) are supported.

    #Example
validMimeTypes=["application/pdf", "image/*"]

  • derive (None | dict[str, Any]) –

  • maxFileSize (None | int) –

  • refKeys (Optional[Iterable[str]]) –

kind = 'file'

The kind of this bone is ‘file’

type = 'relational.tree.leaf.file'

The type of this bone is ‘relational.tree.leaf.file’.

isInvalid(value)

Checks if the provided value is invalid for this bone based on its MIME type and file size.

Parameters:

value (dict) – The value to check for validity.

Returns:

None if the value is valid, or an error message if it is invalid.

postSavedHandler(skel, boneName, key)

Handles post-save processing for the FileBone, including ensuring derived files are built.

Parameters:

  • skel (SkeletonInstance) – The skeleton instance this bone belongs to.

  • boneName (str) – The name of the bone.

  • key (db.Key) – The datastore key of the skeleton.

This method first calls the postSavedHandler of its superclass. Then, it checks if the derive attribute is set and if there are any values in the skeleton for the given bone. If so, it handles the creation of derived files based on the provided configuration.

If the values are stored as a dictionary without a “dest” key, it assumes a multi-language setup and iterates over each language to handle the derived files. Otherwise, it handles the derived files directly.

getReferencedBlobs(skel, name)

Retrieves the referenced blobs in the FileBone.

Parameters:

  • skel (SkeletonInstance) – The skeleton instance this bone belongs to.

  • name (str) – The name of the bone.

Returns:

A set of download keys for the referenced blobs.

Return type:

Set[str]

This method iterates over the bone values for the given skeleton and bone name. It skips values that are None. For each non-None value, it adds the download key of the referenced blob to a set. Finally, it returns the set of unique download keys for the referenced blobs.

refresh(skel, boneName)

Refreshes the FileBone by recreating file entries if needed and importing blobs from ViUR 2.

Parameters:

  • skel (SkeletonInstance) – The skeleton instance this bone belongs to.

  • boneName (str) – The name of the bone.

This method defines an inner function, recreateFileEntryIfNeeded(val), which is responsible for recreating the weak file entry referenced by the relation in val if it doesn’t exist (e.g., if it was deleted by ViUR 2). It initializes a new skeleton for the “file” kind and checks if the file object already exists. If not, it recreates the file entry with the appropriate properties and saves it to the database.

The main part of the refresh method calls the superclass’s refresh method and checks if the configuration contains a ViUR 2 import blob source. If it does, it iterates through the file references in the bone value, imports the blobs from ViUR 2, and recreates the file entries if needed using the inner function.

structure()

Describes the bone and its settings as an JSON-serializable dict. This function has to be implemented for subsequent, specialized bone types.

Return type:

dict