maestral.fsevents.polling#

Looking at the source code for watchdog.utils.dirsnapshot.DirectorySnapshotDiff, the event types are categorised as follows:

  • Created event: The inode is unique to the new snapshot. The path may be unique to the new snapshot or exist in both. In the second case, there will be a preceding Deleted event or a Moved event with the path as starting point (the old item was deleted or moved away).

  • Deleted event: The inode is unique to the old snapshot. The path may be unique to the old snapshot or exist in both. In the second case, there will be a subsequent Created event or a Moved event with the path as end point (something else was created at or moved to the location).

  • Moved event: The inode exists in both snapshots but with different paths.

  • Modified event: The inode exists in both snapshots and the mtime or file size are different. DirectorySnapshotDiff will always use the inode’s path from the old snapshot.

From the above classification, there can be at most two created/deleted/moved events that share the same path in one snapshot diff:

  • Deleted(path1) + Created(path1)

  • Moved(path1, path2) + Created(path1)

  • Deleted(path1) + Moved(path0, path1)

Any Modified event will come before a Moved event or stand alone. Modified events will never be combined by themselves with created or deleted events because they require the inode to be present in both snapshots.

From the above, we can achieve correct ordering for unique path by always adding Deleted events to the queue first, Modified events second, Moved events third and Created events last:

Deleted -> Modified -> Moved -> Created

The ordering won’t be correct between unrelated paths and between files and folder. The first does not matter for syncing. We solve the second by assuming that when a directory is deleted, so are its children. And before a child is created, its parent directory must exist.

MovedEvents which are not unique (their paths appear in other events) will be split into Deleted and Created events by Maestral.

Module Contents#

class maestral.fsevents.polling.OrderedPollingEmitter(event_queue, watch, timeout=DEFAULT_EMITTER_TIMEOUT, event_filter=None, stat=os.stat, listdir=os.scandir)[source]#

Bases: watchdog.observers.polling.PollingEmitter

Ordered polling file system event emitter

Platform-independent emitter that polls a directory to detect file system changes. Events are emitted in an order which can be used to produce the new file system state from the old one.

queue_events(timeout)[source]#

Override this method to populate the event queue with events per interval period.

Parameters:

timeout (float) – Timeout (in seconds) between successive attempts at reading events.

Return type:

None

class maestral.fsevents.polling.OrderedPollingObserver(timeout=DEFAULT_OBSERVER_TIMEOUT)[source]#

Bases: watchdog.observers.polling.PollingObserver

Platform-independent observer that polls a directory to detect file system changes.

Parameters:

timeout (float) –