maestral.models

This module contains the definitions of our database tables which store the index, sync history and cache of content hashes. Each table is defined by a subclass of maestral.database.orm.Model with properties representing database columns. Class instances then represent table rows.

Module Contents

class maestral.models.SyncDirection[source]

Bases: enum.Enum

Enumeration of sync directions

Up = up[source]
Down = down[source]
class maestral.models.SyncStatus[source]

Bases: enum.Enum

Enumeration of sync status

Queued = queued[source]
Syncing = syncing[source]
Done = done[source]
Failed = failed[source]
Skipped = skipped[source]
Aborted = aborted[source]
class maestral.models.ItemType[source]

Bases: enum.Enum

Enumeration of SyncEvent types

File = file[source]
Folder = folder[source]
Unknown = unknown[source]
class maestral.models.ChangeType[source]

Bases: enum.Enum

Enumeration of SyncEvent change types

Added = added[source]
Removed = removed[source]
Moved = moved[source]
Modified = modified[source]
class maestral.models.SyncEvent(**kwargs)[source]

Bases: maestral.database.orm.Model

Represents a file or folder change in the sync queue

This class is used to represent both local and remote file system changes and track their sync progress. Some instance attributes will depend on the state of the sync session, e.g., local_path will depend on the current path of the local Dropbox folder. They may therefore become invalid between sync sessions.

The class methods from_dbx_metadata() and from_file_system_event() should be used to properly construct a SyncEvent from a dropbox.files.Metadata instance or a watchdog.events.FileSystemEvent instance, respectively.

id :maestral.database.orm.Column[int][source]

A unique identifier of the SyncEvent.

direction :maestral.database.orm.Column[SyncDirection][source]

The SyncDirection.

item_type :maestral.database.orm.Column[ItemType][source]

The ItemType. May be undetermined for remote deletions.

sync_time :maestral.database.orm.Column[float][source]

The time the SyncEvent was registered.

dbx_id :maestral.database.orm.Column[str | None][source]

A unique dropbox ID for the file or folder. Will only be set for download events which are not deletions.

dbx_path :maestral.database.orm.Column[str][source]

Correctly cased Dropbox path of the item to sync. If the sync represents a move operation, this will be the destination path. Follows the casing from the path_display attribute of Dropbox metadata.

dbx_path_lower :maestral.database.orm.Column[str][source]

Dropbox path of the item to sync. If the sync represents a move operation, this will be the destination path. This is normalised as the path_lower attribute of Dropbox metadata.

local_path :maestral.database.orm.Column[str][source]

Local path of the item to sync. If the sync represents a move operation, this will be the destination path. This will be correctly cased.

dbx_path_from :maestral.database.orm.Column[str | None][source]

Dropbox path that this item was moved from. Will only be set if change_type is ChangeType.Moved. Follows the casing from the path_display attribute of Dropbox metadata.

dbx_path_from_lower :maestral.database.orm.Column[str | None][source]

Dropbox path that this item was moved from. Will only be set if change_type is ChangeType.Moved. This is normalised as the path_lower attribute of Dropbox metadata.

local_path_from :maestral.database.orm.Column[str | None][source]

Local path that this item was moved from. Will only be set if change_type is ChangeType.Moved. This will be correctly cased.

rev :maestral.database.orm.Column[str | None][source]

The file revision. Will only be set for remote changes. Will be 'folder' for folders and None for deletions.

content_hash :maestral.database.orm.Column[str | None][source]

A hash representing the file content. Will be 'folder' for folders and None for deletions. Set for both local and remote changes.

If the file is a symlink, its target path. This should only be set for files.

change_type :maestral.database.orm.Column[ChangeType][source]

The ChangeType. Remote SyncEvents currently do not generate moved events but are reported as deleted and added at the new location.

change_time :maestral.database.orm.Column[float | None][source]

Local ctime or remote client_modified time for files. None for folders or for remote deletions. Note that client_modified may not be reliable as it is set by other clients and not verified.

change_dbid :maestral.database.orm.Column[str | None][source]

The Dropbox ID of the account which performed the changes. This may not be set for added folders or deletions on the server.

change_user_name :maestral.database.orm.Column[str | None][source]

The user name corresponding to change_dbid, if the account still exists. This field may not be set for performance reasons.

status :maestral.database.orm.Column[SyncStatus][source]

The SyncStatus.

size :maestral.database.orm.Column[int][source]

Size of the item in bytes. Always zero for folders.

completed :maestral.database.orm.Column[int][source]

File size in bytes which has already been uploaded or downloaded. Always zero for folders.

property change_time_or_sync_time(self)[source]

Change time when available, otherwise sync time. This can be used for sorting or user information purposes.

Return type

float

property is_file(self)[source]

Returns True for file changes

Return type

bool

property is_directory(self)[source]

Returns True for folder changes

Return type

bool

property is_added(self)[source]

Returns True for added items

Return type

bool

property is_moved(self)[source]

Returns True for moved items

Return type

bool

property is_changed(self)[source]

Returns True for changed file contents

Return type

bool

property is_deleted(self)[source]

Returns True for deleted items

Return type

bool

property is_upload(self)[source]

Returns True for changes to upload

Return type

bool

property is_download(self)[source]

Returns True for changes to download

Return type

bool

classmethod from_metadata(cls, md, sync_engine)[source]

Initializes a SyncEvent from the given Dropbox metadata.

Parameters
Returns

An instance of this class with attributes populated from the given Dropbox Metadata.

Return type

SyncEvent

classmethod from_file_system_event(cls, event, sync_engine)[source]

Initializes a SyncEvent from the given local file system event.

Parameters
Returns

An instance of this class with attributes populated from the given SyncEvent.

Return type

SyncEvent

class maestral.models.IndexEntry(**kwargs)[source]

Bases: maestral.database.orm.Model

Represents an entry in our local sync index

dbx_path_lower :maestral.database.orm.Column[str][source]

Dropbox path of the item in lower case. This acts as a primary key for the SQLites database since there can only be one entry per case-insensitive Dropbox path. Corresponds to the path_lower field of Dropbox metadata.

dbx_path_cased :maestral.database.orm.Column[str][source]

Dropbox path of the item, correctly cased. Corresponds to the path_display field of Dropbox metadata.

dbx_id :maestral.database.orm.Column[str][source]

The unique dropbox ID for the item.

item_type :maestral.database.orm.Column[ItemType][source]

The ItemType.

last_sync :maestral.database.orm.Column[float | None][source]

The last time a local change was uploaded. Should be the ctime of the local item.

rev :maestral.database.orm.Column[str][source]

The file revision. Will be 'folder' for folders.

content_hash :maestral.database.orm.Column[str | None][source]

A hash representing the file content. Will be 'folder' for folders. May be None if not yet calculated.

If the file is a symlink, its target path. This should only be set for files.

property is_file(self)[source]

Returns True for files

Return type

bool

property is_directory(self)[source]

Returns True for folders

Return type

bool

Returns True for symlinks

Return type

bool

class maestral.models.HashCacheEntry(**kwargs)[source]

Bases: maestral.database.orm.Model

Represents an entry in our cache of content hashes

inode :maestral.database.orm.Column[int][source]

The inode of the item.

local_path :maestral.database.orm.Column[str][source]

The local path of the item.

hash_str :maestral.database.orm.Column[str | None][source]

The content hash of the item.

mtime :maestral.database.orm.Column[float | None][source]

The mtime of the item just before the hash was computed. When the current mtime is newer, the hash will need to be recalculated.

class maestral.models.SyncErrorEntry(**kwargs)[source]

Bases: maestral.database.orm.Model

Table of sync errors

dbx_path :maestral.database.orm.Column[str][source]
dbx_path_lower :maestral.database.orm.Column[str][source]
dbx_path_from :maestral.database.orm.Column[str | None][source]
dbx_path_from_lower :maestral.database.orm.Column[str | None][source]
local_path :maestral.database.orm.Column[str | None][source]
local_path_from :maestral.database.orm.Column[str | None][source]
direction :maestral.database.orm.Column[SyncDirection][source]
title :maestral.database.orm.Column[str | None][source]
message :maestral.database.orm.Column[str | None][source]
type :maestral.database.orm.Column[str | None][source]