maestral.models =============== .. py:module:: maestral.models .. autoapi-nested-parse:: 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 :class:`maestral.database.orm.Model` with properties representing database columns. Class instances then represent table rows. Module Contents --------------- .. py:class:: SyncDirection Bases: :py:obj:`enum.Enum` Enumeration of sync directions .. py:attribute:: Up :value: 'up' .. py:attribute:: Down :value: 'down' .. py:class:: SyncStatus Bases: :py:obj:`enum.Enum` Enumeration of sync status .. py:attribute:: Queued :value: 'queued' .. py:attribute:: Syncing :value: 'syncing' .. py:attribute:: Done :value: 'done' .. py:attribute:: Failed :value: 'failed' .. py:attribute:: Skipped :value: 'skipped' .. py:attribute:: Aborted :value: 'aborted' .. py:attribute:: Conflict :value: 'conflict' .. py:class:: ItemType Bases: :py:obj:`enum.Enum` Enumeration of SyncEvent types .. py:attribute:: File :value: 'file' .. py:attribute:: Folder :value: 'folder' .. py:attribute:: Unknown :value: 'unknown' .. py:class:: ChangeType Bases: :py:obj:`enum.Enum` Enumeration of SyncEvent change types .. py:attribute:: Added :value: 'added' .. py:attribute:: Removed :value: 'removed' .. py:attribute:: Moved :value: 'moved' .. py:attribute:: Modified :value: 'modified' .. py:class:: SyncEvent(**kwargs) Bases: :py:obj:`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., :attr:`local_path` will depend on the current path of the local Dropbox folder. They may therefore become invalid between sync sessions. The class methods :meth:`from_dbx_metadata` and :meth:`from_file_system_event` should be used to properly construct a :class:`SyncEvent` from a :class:`dropbox.files.Metadata` instance or a :class:`watchdog.events.FileSystemEvent` instance, respectively. .. py:attribute:: id A unique identifier of the SyncEvent. .. py:attribute:: direction The :class:`SyncDirection`. .. py:attribute:: item_type The :class:`ItemType`. May be undetermined for remote deletions. .. py:attribute:: sync_time Timestamp in Unix epoch seconds the SyncEvent was registered. .. py:attribute:: dbx_id A unique dropbox ID for the file or folder. Will only be set for download events which are not deletions. .. py:attribute:: dbx_path 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. .. py:attribute:: dbx_path_lower 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. .. py:attribute:: local_path 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. .. py:attribute:: dbx_path_from Dropbox path that this item was moved from. Will only be set if :attr:`change_type` is :attr:`ChangeType.Moved`. Follows the casing from the path_display attribute of Dropbox metadata. .. py:attribute:: dbx_path_from_lower Dropbox path that this item was moved from. Will only be set if :attr:`change_type` is :attr:`ChangeType.Moved`. This is normalised as the path_lower attribute of Dropbox metadata. .. py:attribute:: local_path_from Local path that this item was moved from. Will only be set if :attr:`change_type` is :attr:`ChangeType.Moved`. This will be correctly cased. .. py:attribute:: rev The file revision. Will only be set for remote changes. Will be ``'folder'`` for folders and ``None`` for deletions. .. py:attribute:: content_hash A hash representing the file content. Will be ``'folder'`` for folders and ``None`` for deletions. Set for both local and remote changes. .. py:attribute:: symlink_target If the file is a symlink, its target path. This should only be set for files. .. py:attribute:: change_type The :class:`ChangeType`. Remote SyncEvents currently do not generate moved events but are reported as deleted and added at the new location. .. py:attribute:: change_time Timestamp in Unix epoch seconds when the file was last modified. 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. .. py:attribute:: change_dbid The Dropbox ID of the account which performed the changes. This may not be set for added folders or deletions on the server. .. py:attribute:: change_user_name The user name corresponding to :attr:`change_dbid`, if the account still exists. This field may not be set for performance reasons. .. py:attribute:: status The :class:`SyncStatus`. .. py:attribute:: size Size of the item in bytes. Always zero for folders. .. py:attribute:: completed File size in bytes which has already been uploaded or downloaded. Always zero for folders. .. py:property:: change_time_or_sync_time :type: float Change time when available, otherwise sync time. This can be used for sorting or user information purposes. .. py:property:: is_file :type: bool Returns True for file changes .. py:property:: is_directory :type: bool Returns True for folder changes .. py:property:: is_added :type: bool Returns True for added items .. py:property:: is_moved :type: bool Returns True for moved items .. py:property:: is_changed :type: bool Returns True for changed file contents .. py:property:: is_deleted :type: bool Returns True for deleted items .. py:property:: is_upload :type: bool Returns True for changes to upload .. py:property:: is_download :type: bool Returns True for changes to download .. py:method:: from_metadata(md, sync_engine) :classmethod: Initializes a SyncEvent from the given Dropbox metadata. :param md: Dropbox Metadata. :param sync_engine: SyncEngine instance. :returns: An instance of this class with attributes populated from the given Dropbox Metadata. .. py:method:: from_file_system_event(event, sync_engine) :classmethod: Initializes a SyncEvent from the given local file system event. :param event: Local file system event. :param sync_engine: SyncEngine instance. :returns: An instance of this class with attributes populated from the given SyncEvent. .. py:class:: IndexEntry(**kwargs) Bases: :py:obj:`maestral.database.orm.Model` Represents an entry in our local sync index .. py:attribute:: dbx_path_lower 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. .. py:attribute:: dbx_path_cased Dropbox path of the item, correctly cased. Corresponds to the path_display field of Dropbox metadata. .. py:attribute:: dbx_id The unique dropbox ID for the item. .. py:attribute:: item_type The :class:`ItemType`. .. py:attribute:: last_sync The last time a local change was uploaded. Should be the ctime of the local item. .. py:attribute:: rev The file revision. Will be ``'folder'`` for folders. .. py:attribute:: content_hash A hash representing the file content. Will be ``'folder'`` for folders. May be ``None`` if not yet calculated. .. py:attribute:: symlink_target If the file is a symlink, its target path. This should only be set for files. .. py:property:: is_file :type: bool Returns True for files .. py:property:: is_directory :type: bool Returns True for folders .. py:property:: is_symlink :type: bool Returns True for symlinks .. py:class:: HashCacheEntry(**kwargs) Bases: :py:obj:`maestral.database.orm.Model` Represents an entry in our cache of content hashes .. py:attribute:: inode The inode of the item. .. py:attribute:: local_path The local path of the item. .. py:attribute:: hash_str The content hash of the item. .. py:attribute:: mtime The mtime of the item just before the hash was computed. When the current mtime is newer, the hash will need to be recalculated. .. py:class:: SyncErrorEntry(**kwargs) Bases: :py:obj:`maestral.database.orm.Model` Table of sync errors .. py:attribute:: dbx_path .. py:attribute:: dbx_path_lower .. py:attribute:: dbx_path_from .. py:attribute:: dbx_path_from_lower .. py:attribute:: local_path .. py:attribute:: local_path_from .. py:attribute:: direction .. py:attribute:: title .. py:attribute:: message .. py:attribute:: type