core.modules.file
¶
Module Contents¶
Classes¶
This bone is used to inject a freshly signed download url into a FileSkel. |
|
Default file leaf skeleton. |
|
Default file node skeleton. |
|
Tree module prototype. |
Functions¶
|
|
|
|
|
External Thumbnailer for images. |
Start searching for blob locks that have been recently freed |
|
|
|
Increase deletion counter on each blob currently not referenced and delete |
|
|
|
Start deletion of pending FileSkels that are older than 7 days. |
Attributes¶
- core.modules.file.VALID_FILENAME_REGEX¶
- core.modules.file.GOOGLE_STORAGE_CLIENT¶
- core.modules.file.GOOGLE_STORAGE_BUCKET¶
- core.modules.file.FilePath¶
- core.modules.file.importBlobFromViur2(dlKey, fileName)¶
- core.modules.file.thumbnailer(fileSkel, existingFiles, params)¶
- core.modules.file.cloudfunction_thumbnailer(fileSkel, existingFiles, params)¶
External Thumbnailer for images.
The corresponding cloudfunction can be found here . https://github.com/viur-framework/viur-cloudfunctions/tree/main/thumbnailer
You can use it like so: main.py:
from viur.core.modules.file import cloudfunction_thumbnailer conf.file_thumbnailer_url = "https://xxxxx.cloudfunctions.net/imagerenderer" conf.file_derivations = {"thumbnail": cloudfunction_thumbnailer} conf.derives_pdf = { "thumbnail": [{"width": 1920,"sites":"1,2"}] }
skeletons/xxx.py: .. code-block:: python
test = FileBone(derive=conf.derives_pdf)
- class core.modules.file.DownloadUrlBone(*, compute=None, defaultValue=None, descr='', getEmptyValueFunc=None, indexed=True, isEmptyFunc=None, languages=None, multiple=False, params=None, readOnly=None, required=False, searchable=False, unique=None, vfunc=None, visible=True)¶
Bases:
viur.core.bones.BaseBone
This bone is used to inject a freshly signed download url into a FileSkel.
Initializes a new Bone.
- Parameters:
compute (Compute) –
defaultValue (Any) –
descr (str) –
getEmptyValueFunc (callable) –
indexed (bool) –
isEmptyFunc (callable) –
languages (None | list[str]) –
multiple (bool | MultipleConstraints) –
params (dict) –
readOnly (bool) –
required (bool | list[str] | tuple[str]) –
searchable (bool) –
unique (None | UniqueValue) –
vfunc (callable) –
visible (bool) –
- unserialize(skel, name)¶
Deserialize bone data from the datastore and populate the bone with the deserialized values.
This function is the inverse of the serialize function. It converts data from the datastore into a format that can be used by the bones in the skeleton.
- Parameters:
skel – A SkeletonInstance object containing the values to be deserialized.
name – The property name of the bone in its Skeleton (not the description).
- Returns:
True if deserialization is successful, False otherwise.
- class core.modules.file.FileLeafSkel(*args, **kwargs)¶
Bases:
viur.core.prototypes.tree.TreeSkel
Default file leaf skeleton.
- kindName = 'file'¶
- size¶
- dlkey¶
- name¶
- mimetype¶
- weak¶
- pending¶
- width¶
- height¶
- downloadUrl¶
- derived¶
- pendingparententry¶
- preProcessBlobLocks(locks)¶
Ensure that our dlkey is locked even if we don’t have a filebone here
- classmethod refresh(skelValues)¶
Refresh the bones current content.
This function causes a refresh of all relational bones and their associated information.
- class core.modules.file.FileNodeSkel(*args, **kwargs)¶
Bases:
viur.core.prototypes.tree.TreeSkel
Default file node skeleton.
- kindName = 'file_rootNode'¶
- name¶
- rootNode¶
- class core.modules.file.File(moduleName, modulePath, *args, **kwargs)¶
Bases:
viur.core.prototypes.tree.Tree
Tree module prototype.
It is used for hierarchical structures, either as a tree with nodes and leafs, or as a hierarchy with nodes only.
- PENDING_POSTFIX = ' (pending)'¶
- DOWNLOAD_URL_PREFIX = '/file/download/'¶
- MAX_FILENAME_LEN = 256¶
- leafSkelCls¶
- nodeSkelCls¶
- handler = 'tree.simple.file'¶
- adminInfo¶
- roles¶
- default_order = 'name'¶
- static is_valid_filename(filename)¶
Verifies a valid filename.
The filename should be valid on Linux, Mac OS and Windows. It should not be longer than MAX_FILENAME_LEN chars.
Rule set: https://stackoverflow.com/a/31976060/3749896 Regex test: https://regex101.com/r/iBYpoC/1
- Parameters:
filename (str) –
- Return type:
bool
- static hmac_sign(data)¶
- Parameters:
data (viur.core.decorators.t.Any) –
- Return type:
str
- static hmac_verify(data, signature)¶
- Parameters:
data (viur.core.decorators.t.Any) –
signature (str) –
- Return type:
bool
- static create_download_url(dlkey, filename, derived=False, expires=datetime.timedelta(hours=1), download_filename=None)¶
Utility function that creates a signed download-url for the given folder/filename combination
- Parameters:
folder – The GCS-Folder (= the download-key) for that file
filename (str) – The name of the file. Either the original filename or the name of a derived file.
derived (bool) – True, if it points to a derived file, False if it points to the original uploaded file
expires (viur.core.decorators.t.Optional[datetime.timedelta | int]) – None if the file is supposed to be public (which causes it to be cached on the google ede caches), otherwise a datetime.timedelta of how long that link should be valid
download_filename (viur.core.decorators.t.Optional[str]) – If set, browser is enforced to download this blob with the given alternate filename
dlkey (str) –
- Returns:
The signed download-url relative to the current domain (eg /download/…)
- Return type:
str
- static parse_download_url(url)¶
Parses a file download URL in the format /file/download/xxxx?sig=yyyy into its FilePath.
If the URL cannot be parsed, the function returns None.
- Parameters:
url – The file download URL to be parsed.
- Returns:
A FilePath on success, None otherwise.
- Return type:
viur.core.decorators.t.Optional[FilePath]
- static create_src_set(file, expires=datetime.timedelta(hours=1), width=None, height=None)¶
Generates a string suitable for use as the srcset tag in html. This functionality provides the browser with a list of images in different sizes and allows it to choose the smallest file that will fill it’s viewport without upscaling.
- Parameters:
file (viur.core.decorators.t.Union[viur.core.skeleton.SkeletonInstance, dict, str]) – The file skeleton (or if multiple=True a single value from it) to generate the srcset.
expires (viur.core.decorators.t.Optional[datetime.timedelta | int]) – None if the file is supposed to be public (which causes it to be cached on the google edecaches), otherwise it’s lifetime in seconds
width (viur.core.decorators.t.Optional[int]) – A list of widths that should be included in the srcset. If a given width is not available, it will be skipped.
height (viur.core.decorators.t.Optional[int]) – A list of heights that should be included in the srcset. If a given height is not available, it will be skipped.
- Returns:
The srctag generated or an empty string if a invalid file object was supplied
- Return type:
str
- write(filename, content, mimetype='text/plain', width=None, height=None)¶
Write a file from any buffer into the file module.
- Parameters:
filename (str) – Filename to be written.
content (viur.core.decorators.t.Any) – The file content to be written, as bytes-like object.
mimetype (str) – The file’s mimetype.
width (int) – Optional width information for the file.
height (int) – Optional height information for the file.
- Returns:
Returns the key of the file object written. This can be associated e.g. with a FileBone.
- Return type:
viur.core.db.Key
- read(key=None, path=None)¶
Read a file from the Cloud Storage.
If a key and a path are provided, the key is preferred. This means that the entry in the db is searched first and if this is not found, the path is used.
- Parameters:
key (viur.core.db.Key | int | str | None) – Key of the LeafSkel that contains the “dlkey” and the “name”.
path (str | None) – The path of the file in the Cloud Storage Bucket.
- Returns:
Returns the file as a io.BytesIO buffer and the content-type
- Return type:
tuple[io.BytesIO, str]
- deleteRecursive(parentKey)¶
Recursively processes a delete request.
This will delete all entries which are children of nodeKey, except key nodeKey.
- Parameters:
parentKey – URL-safe key of the node which children should be deleted.
- getUploadURL(fileName, mimeType, size=None, node=None, authData=None, authSig=None)¶
- Parameters:
fileName (str) –
mimeType (str) –
size (viur.core.decorators.t.Optional[int]) –
node (viur.core.decorators.t.Optional[str | viur.core.db.Key]) –
authData (viur.core.decorators.t.Optional[str]) –
authSig (viur.core.decorators.t.Optional[str]) –
- download(blobKey, fileName='', download=False, sig='', *args, **kwargs)¶
Download a file. :param blobKey: The unique blob key of the file. :param fileName: Optional filename to provide in the header. :param download: Set header to attachment retrival, set explictly to “1” if download is wanted.
- Parameters:
blobKey (str) –
fileName (str) –
download (bool) –
sig (str) –
- add(skelType, node=None, *args, **kwargs)¶
Add a new entry with the given parent node, and render the entry, eventually with error notes on incorrect data. Data is taken by any other arguments in kwargs.
The function performs several access control checks on the requested entity before it is added.
See also
canAdd()
,onAdd()
, ,onAdded()
- Parameters:
skelType (viur.core.prototypes.tree.SkelType) – Defines the type of the new entry and may either be “node” or “leaf”.
node (viur.core.db.Key | int | str | None) – URL-safe key of the parent.
- Returns:
The rendered, added object of the entry, eventually with error hints.
- Raises:
viur.core.errors.NotAcceptable
, when no valid skelType was provided.- Raises:
viur.core.errors.NotFound
, when no valid node was found.- Raises:
viur.core.errors.Unauthorized
, if the current user does not have the required permissions.- Raises:
viur.core.errors.PreconditionFailed
, if the skey could not be verified.
- onEdit(skelType, skel)¶
Hook function that is called before editing an entry.
It can be overridden for a module-specific behavior.
- Parameters:
skelType (viur.core.prototypes.tree.SkelType) – Defines the type of the node that shall be edited.
skel (viur.core.skeleton.SkeletonInstance) – The Skeleton that is going to be edited.
See also
edit()
,onEdited()
- mark_for_deletion(dlkey)¶
Adds a marker to the datastore that the file specified as dlkey can be deleted.
Once the mark has been set, the data store is checked four times (default: every 4 hours) if the file is in use somewhere. If it is still in use, the mark goes away, otherwise the mark and the file are removed from the datastore. These delayed checks are necessary due to database inconsistency.
- Parameters:
dlkey (str) – Unique download-key of the file that shall be marked for deletion.
- Return type:
None
- core.modules.file.startCheckForUnreferencedBlobs()¶
Start searching for blob locks that have been recently freed
- core.modules.file.doCheckForUnreferencedBlobs(cursor=None)¶
- core.modules.file.startCleanupDeletedFiles()¶
Increase deletion counter on each blob currently not referenced and delete it if that counter reaches maxIterCount
- core.modules.file.doCleanupDeletedFiles(cursor=None)¶
- core.modules.file.start_delete_pending_files()¶
Start deletion of pending FileSkels that are older than 7 days.