ox.apps.files

This application provides file management, including: upload, thumbnailing, access rights.

Models

class ox.apps.files.models.file.File(*args, **kwargs)

This class represent a file.

Files are looked up for a matching FileProcessor (reading mime-type). A processors handles different tasks such as creating preview (thumbnails) or getting metadata. In order to do so, it uses registry that provides helpers to read mime types and register file processors.

A file can be nested under a parent folder. If None is provided, then it will be at the root of the filesystem.

Each file is also attached to an owner that specifies who has access to the object (using django-caps permission system).

At deletion, related files and previews can be deleted based on .conf.ox_files_settings (CLEAR_FILES_ON_DELETE=True option).

Access

alias of FileAccess

exception DoesNotExist

exception MultipleObjectsReturned

clear_files()

Delete files from storage.

This method is used to clear storage when the model instance is deleted. It updates fields without saving model instance.

delete(*args, clear_files=None, **kwargs)

Ensure file deletion if OX_FILES['CLEAR_FILES_ON_DELETE'] or clear_files is True.

Parameters:

• *args –

  forward to super’s delete()

• clear_files (bool | None) – if True or False, overrides default settings.

• **kwargs –

  forward to super’s delete()

get_processor(save=True, registry=<ox.apps.files.processors.registry.Registry object>)

Return processor to use for this file type.

Read mime-type from file if not already set.

Parameters:

• save – save model if mime type is updated (default is True)

• registry – use this processors instead of processors.processors

on_save(fields=None)

Ensure mime type and file validation.

parent_attr = 'folder'

Field name used for parenting.

read_mime_type(save=True)

Read mime-type from file and update corresponding field. :rtype: str

Parameters:

save (bool) – save object instance

:return the mime type

validate_node()

Ensure file name is unique within folder.

Yield ValidationError:

if file name is already present in folder (file or folder).

class ox.apps.files.models.file.FileQuerySet(model=None, query=None, using=None, hints=None)

clear_files(update=True)

Delete files from filesystem and optionally update fields.

Parameters:

update (bool) – if True (default), update queryset fields.

delete(clear_files=None)

Delete the records in the current QuerySet.

ox.apps.files.models.file.file_upload_to(instance, filename)

Return target upload file depending on whether the folder is synchronized or not.

Return type:

str

ox.apps.files.models.file.get_obfuscated_path(ext)

Return an obfuscated file path with provided extension.

There is no base dir prefix such as conf.Settings.UPLOAD_DIR, only sub-dir and path.

Return type:

str

class ox.apps.files.models.folder.Folder(*args, **kwargs)

Represent a folder in which files are stored.

There are two kind of folders:

• virtual folder (default): the folder structure is only stored in the database, while file names and storage are obfuscated.

  The files are saved under conf.Settings.UPLOAD_DIR directory.

• synchronized folder: the directory structure and file name are synchronized on the file system (to be used by external tools, not for direct user’s decision).

  The folders and files are saved and synchronized under conf.Settings.SYNC_DIR.

Once a folder is a assigned a type, all its children and files will be impacted. To avoid filesystem synchronisation issues this value can not be changed afterward.

Important Notes

Updating parent, name and path should not be done manually. Instead use rename() and move_to() methods to ensure that these values are correctly set.

When thoses values raise a ValidationError, user should assume that new values of the model are invalid.

Access

alias of FolderAccess

exception DoesNotExist

exception MultipleObjectsReturned

get_sync_path(path)

Return synchronization directory for the provided folder path.

Return type:

Path

is_sync

This attribute allows to synchronize files and folder on the file system instead of being obfuscated.

Once set, this attribute should never be changed in order to avoid desynchronization.

The folders will be put under directory following this convention: {ox_files_settings}/{owner__uuid}/{path}.

move_to(parent=None, name=None, save=True)

Move folder into provided parent folder or root.

Parameters:

• parent (Folder | None) – parent folder

• name (str | None) – if provided rename folder

• save (bool) – save node

on_save(fields=None)

Ensure tree id, level and path are set.

It also validate_node() and update children’s values.

rename(name, save=True)

Rename folder.

root_grants = {'ox_files.add_file': 1, 'ox_files.add_folder': 1, 'ox_files.change_file': 1, 'ox_files.change_folder': 1, 'ox_files.delete_file': 1, 'ox_files.delete_folder': 1, 'ox_files.view_file': 3, 'ox_files.view_folder': 3}

This class attribute provide the default value for grant object. It should follows the structure of grants field, such as:

root_grants = {
    "auth.view_user": 1,
    "app.change_mymodel": 2
}

sync(initial_path=None)

Synchronize folder with filesystem :rtype: Path

Parameters:

initial_path (str | None) – original path before it has been moved (as path value).

:return the path on file system :yield ValueError: when folder is not synchronized (is_sync).

validate_node()

Validate node for name collision (folder & file) and owner.

Yield PermissionDenied:

owner is not the same as parent’s.

Yield ValidationError:

a file or folder already exists with this name in parent.

class ox.apps.files.models.folder.FolderQuerySet(model=None, query=None, using=None, hints=None)

find_clone(node, **lookups)

Search for a node that would be the same as this one. This is used in order to search for colliding paths.

Parameters:

• node – node to look.

• **lookup –

  extra filters to add.

Return type:

FolderQuerySet

ox.apps.files.models.folder.validate_name(value)

Validate folder or file name.

File processors

Processors are used to handle file manipulation such as generating thumbnails. They are registered using the ox.apps.files.processors.registry Registry instance.

class ox.apps.files.processors.ImageProcessor

class ox.apps.files.processors.LibreOfficeProcessor

class ox.apps.files.processors.PDFProcessor

class ox.apps.files.processors.Processor

A Processor handles reading file metadata, providing preview among other things.

create_preview(path, out, size=(600, 800), force=False, **kwargs)

Create a preview for the file at provided path.

Parameters:

• path (Path) – path of the file to create a preview of

• out (Path) – output path to save preview

• size (thumbnail) – defaults to configured settings.

• force (bool) – create file even if it exists

Return type:

bool

:return boolean indicating wether file has been created

get_metadata(path)

Return file metadata.

Parameters:

path (Path) – file path

Return type:

dict[str, str]

class ox.apps.files.processors.Registry(default_processor, processors=[])

Registry of all file processor classes.

This is used to determine file type and provide a processor based on it.

default_processor = None

Default processor to use when file type is not supported by any other processor.

get(mime_type)

Return processor for the provided mime type.

Return type:

Processor | None

mime_types: dict[str, Processor] = None

Processors by mime type

populate(paths=['ox.apps.files.processors.ImageProcessor', 'ox.apps.files.processors.PDFProcessor', 'ox.apps.files.processors.LibreOfficeProcessor'])

Fullfill registry using provided list of processors class path. :type paths: list[str] :param paths: class paths (defaults to PROCESSORS)

processors: list[Processor] = None

List of processors

read_mime_type(file_or_stream)

Return mime type for the provided file or stream.

Return type:

str

register(processor)

Register a new processor

ox.apps.files.processors.registry = <ox.apps.files.processors.registry.Registry object>

Default registry of file processors.

ox.apps.files.apps

class ox.apps.files.apps.AppConfig(*args, **kwargs)

icon: str = 'mdi-document-multiple-outline'

Material design icon class.

npm_package: str | None = '@oxylus/files'

Name of the corresponding NPM package to look up for.

Defaults to app label.

ready()

Override this method in subclasses to run code when Django starts.

root_url: str = 'ox/files'

Provide an alternative to app label when we target application in paths.

For example Oxylus will nest template directories as ox/core/ instead of ox_core. The same happens for urls.

ox.apps.files.conf

class ox.apps.files.conf.Settings(key, source=<LazySettings "ox.settings.dev">)

CLEAR_FILES_ON_DELETE = True

When a File is deleted from database, remove it from storage.

FILE_SIZE_LIMIT = 15728640

Set maximum file size.

MAGIC_BUFFER = 2048

Buffer size used by Python-Magic to read mime types.

PREVIEW_DIR = 'ox_files/previews'

Directory in which to save previews.

PROCESSORS = ['ox.apps.files.processors.ImageProcessor', 'ox.apps.files.processors.PDFProcessor', 'ox.apps.files.processors.LibreOfficeProcessor']

List of file processors.

SYNC_DIR = 'ox_files/store'

Base directory in which unobfuscated files and folder are synchronized.

By default uploaded files names and directories are obfuscated on file system. There might however be some cases with wan’t them to be synchronized with it.

This settings defines the root directory for thoses folders and files, in order to synchronize with external tools (eg. FTP).

THUMBNAIL_SIZE = (600, 800)

Size for thumbnails

UPLOAD_DIR = 'odir/uploads'

Subdirectory in media where to upload files.

property preview_dir: Path

Return full path to preview dir.

property sync_dir: Path

Return full path to sync dir.

property upload_dir: Path

Return full path to upload dir.

ox.apps.files.conf.ox_files_settings: Settings = <ox.apps.files.conf.Settings object>

Settings used by ox_files application, using key OX_FILES.

ox.apps.files.exceptions

exception ox.apps.files.exceptions.FileTypeError

Invalid file format.

ox.apps.files.filters

ox.apps.files.serializers

class ox.apps.files.serializers.FileSerializer(*args, **kwargs)

validate_file(value)

Check file size limitation

class ox.apps.files.serializers.FolderSerializer(*args, **kwargs)

ox.apps.files.tasks

ox.apps.files.views

class ox.apps.files.views.FileAccessViewSet(**kwargs)

class ox.apps.files.views.FileViewSet(**kwargs)

serializer_class

alias of FileSerializer

class ox.apps.files.views.FolderAccessViewSet(**kwargs)

class ox.apps.files.views.FolderViewSet(**kwargs)

serializer_class

alias of FolderSerializer