ox.apps.files

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

Models

class ox.apps.files.models.file.File(*args, **kwargs)[source]

Bases: Described, Timestamped, ChildOwned

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 are deleted based on .conf.ox_files_settings (CLEAR_FILES_ON_DELETE=True option).

Access: alias of FileAccess

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

delete(*args, clear_files=None, **kwargs)[source]

Ensure file deletion.

Parameters:

*args –
forward to super’s delete()
clear_files (bool | None) – if True or False, overrides default settings.
**kwargs –
forward to super’s delete()

property file_url[source]: Return file url.

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

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

move_or_copy(path, copy=False)[source]

Move file by path.

Parameters:: path (str) – path related to upload directory

on_save(fields=None)[source]: Ensure mime type and file validation.

parent_attr = 'folder': Field name used for parenting.

property preview_url[source]: Return file preview url.

read_mime_type(save=True)[source]

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

Parameters:: save (bool) – save object instance

:return the mime type

validate_node()[source]

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)[source]

Bases: ChildOwnedQuerySet

clear_files(update=True)[source]

Delete files from filesystem and optionally update fields.

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

delete(clear_files=None)[source]: Delete the records in the current QuerySet.

ox.apps.files.models.file.file_upload_to(instance, filename)[source]

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

Return type:: str

class ox.apps.files.models.folder.Folder(*args, **kwargs)[source]

Bases: Described, Timestamped, OwnedTreeNode

Represent a folder in which files are stored.

Important

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: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

abs_path()[source]

File system path of the folder.

Return type:: Path

move_to(parent=None, name=None, save=True)[source]

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)[source]

Ensure tree id, level and path are set.

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

rename(name, save=True)[source]: 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_node(source_path=None, target_path=None)[source]: Synchronize folder with filesystem (move or create it).

validate_node()[source]

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.FolderComment(*args, **kwargs)[source]

Bases: Message

Message to a file

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

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

Bases: OwnedTreeNodeQuerySet

find_clone(node, **lookups)[source]

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)[source]: 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[source]: Bases: Processor

class ox.apps.files.processors.LibreOfficeProcessor[source]: Bases: Processor

class ox.apps.files.processors.PDFProcessor[source]: Bases: Processor

class ox.apps.files.processors.Processor[source]

Bases: object

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

create_preview(path, out, size=(600, 800), force=False, **kwargs)[source]

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)[source]

Return file metadata.

Parameters:: path (Path) – file path
Return type:: dict[str, str]

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

Bases: object

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)[source]

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'])[source]: 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)[source]

Return mime type for the provided file or stream.

Return type:: str

register(processor)[source]: 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)[source]

Bases: AppConfig

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()[source]: 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 "instance.settings">)[source]

Bases: Settings

FILE_SIZE_LIMIT = 15728640: Set maximum file size.

MAGIC_BUFFER: int = 2048: Buffer size used by Python-Magic to read mime types.

PREVIEW_DIR = 'ox_files/previews': Directory in protected media which to save previews.

PROCESSORS: list[str] = ['ox.apps.files.processors.ImageProcessor', 'ox.apps.files.processors.PDFProcessor', 'ox.apps.files.processors.LibreOfficeProcessor']: List of file processors.

THUMBNAIL_SIZE: tuple[int, int] = (600, 800): Size for thumbnails

UPLOAD_DIR = 'ox_files/uploads': Subdirectory in protected media where to upload files.

WEBDAV_HOST: str = '127.0.0.1': Host for the WebDAV server. Defaults to the first ALLOWED_HOSTS.

WEBDAV_PORT: int = 8042: Port of the WebDAV server.

property preview_dir: Path: Return full path to preview dir.

resolve(path, owner=None, relative=False)[source]

Resolve path under file upload directory.

Parameters:

path (str) – path to resolve.
owner (UUID | None) – if provided resolve under this owner’s path.
relative (bool) – if True, return path relative to MEDIA_ROOT.

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.conf.resolve(path, owner=None, relative=False): Shortcut to ox_files_settings ‘s Settings.resolve().

ox.apps.files.exceptions

exception ox.apps.files.exceptions.FileTypeError[source]

Bases: ValueError

Invalid file format.

ox.apps.files.filters

ox.apps.files.serializers

class ox.apps.files.serializers.BaseFileCommentSerializer(*args, **kwargs)[source]: Bases: MessageSerializer, ModelSerializer

class ox.apps.files.serializers.BaseFolderCommentSerializer(*args, **kwargs)[source]: Bases: MessageSerializer, ModelSerializer

class ox.apps.files.serializers.FileCommentSerializer(*args, **kwargs)[source]: Bases: BaseFileCommentSerializer

class ox.apps.files.serializers.FileSerializer(*args, **kwargs)[source]

Bases: OwnedSerializer

file_data: File data upload

validate_file(value)[source]: Check file size limitation

class ox.apps.files.serializers.FolderCommentSerializer(*args, **kwargs)[source]: Bases: BaseFolderCommentSerializer

class ox.apps.files.serializers.FolderSerializer(*args, **kwargs)[source]: Bases: OwnedSerializer

ox.apps.files.tasks

ox.apps.files.views

class ox.apps.files.views.FileAccessViewSet(**kwargs)[source]: Bases: AccessViewSet

class ox.apps.files.views.FileViewSet(**kwargs)[source]

Bases: OwnedViewSet

serializer_class: alias of FileSerializer

class ox.apps.files.views.FolderAccessViewSet(**kwargs)[source]: Bases: AccessViewSet

class ox.apps.files.views.FolderViewSet(**kwargs)[source]

Bases: OwnedViewSet

serializer_class: alias of FolderSerializer