cloudsync.CloudSync

The main sync class, instance this to initiate a sync.

class cloudsync.CloudSync(providers: Tuple[cloudsync.provider.Provider, cloudsync.provider.Provider], roots: Optional[Tuple[str, str]] = None, storage: Optional[cloudsync.sync.state.Storage] = None, sleep: Optional[Tuple[float, float]] = None, root_oids: Optional[Tuple[str, str]] = None, state_class: Type = <class 'cloudsync.sync.state.SyncState'>, smgr_class: Type = <class 'cloudsync.sync.manager.SyncManager'>, emgr_class: Type = <class 'cloudsync.event.EventManager'>)

The main synchronization class used.

property aging

float: The number of seconds to wait before syncing a file.

Reduces storage provider traffic at the expense of increased conflict risk.

Default is based on the max(provider.default_sleep) value

authenticate(side: int)

Override this method to change (re)authentication

Default is to call provider[side].authenticate()

Args:

side: either 0 (LOCAL) or 1 (REMOTE)

static backoff()

Raises an exception, interrupting the durrent do() call, and sleeping for backoff seconds.

property busy

True if there are any changes or events to be processed

property change_count

Number of relevant changes to be processed.

do()

One loop of sync, used for tests only.

This randomly chooses to process local events, remote events or local syncs.

done()

Called at shutdown, override if you need some shutdown code.

forget()

Forget and discard state information, and drop any events in the queue. This will trigger a walk.

handle_notification(notification: dataclasses.dataclass)

Override to receive notifications during sync processing.

Args:

notification: Information about errors, or other sync events.

in_backoff = 0.0

interruptable_sleep(secs)

Call this instead of sleep, so the service can be interrupted

max_backoff = 1.0

min_backoff = 0.01

mult_backoff = 2.0

nothing_happened()

Sets a “nothing happened” flag. This will cause backoff to remain the same, even on success.

prioritize(side: int, path: str)

Override this method to change the sync priority

Default priority is 0 Negative values happen first Positive values happen later

Args:

side: either 0 (LOCAL) or 1 (REMOTE) path: a path value in the (side) provider

resolve_conflict(f1: IO, f2: IO) → Tuple[Any, bool]

Override this method to handle conflict resolution of files

Note:

• f1 and f2 are file-likes that will block on read, and can possibly pull data from the network, internet, etc

• f1 and f2 also support the .path property to get a relative path to the file

• f1 and f2 also support the .side property

Returns:

A tuple of (result, keep) or None, meaning there is no good resolution result is one of: - A “merged” file-like which should be used as the data to replace both f1/f2 with - One of f1 or f2, which is selected as the correct version keep is true if we want to keep the old version of the file around as a .conflicted file, else False

run(*, timeout=None, until=None, sleep=0.001)

Calls do in a loop.

Args:

timeout: stop calling do after secs until: lambda returns bool sleep: seconds

If an unhandled exception occurs, backoff sleep will occur.

service_name = None

set_need_walk(side, need_walk=True)

start(*, daemon=True, **kwargs)

Starts the cloudsync service.

property started

True if the service has been started and has not finished stopping

stop(forever=True, wait=True)

Stops the cloudsync service.

Args:

forever: If false is passed, then handles are left open for a future start. Generally used for tests only. wait: If false, manager threads are signaled to stop, but are NOT joined

static stop_all(runnables: List[Runnable], forever: bool = True, wait: bool = True)

Convenience function for stopping multiple Runnables efficiently.

property stopped

Set when you call stop(), causes the services to drop out.

storage_label()

Returns:

str: a unique label representing this paired, translated sync

Override this if if you are re-using storage and are using a rootless translate.

translate(side: int, path: str)

Override this method to translate between local and remote paths

By default uses self.roots to strip the path provided, and join the result to the root of the other side.

If self.roots is None, this function must be overridden.

Example:

translate(REMOTE, “/home/full/local/path.txt”) -> “/cloud/path.txt”

Args:

side: either 0 (LOCAL) or 1 (REMOTE) path: a path valid in the (1-side) provider

Returns:

The path, valid for the provider[side], or None to mean “don’t sync”

wait(timeout=None)

Wait for all threads.

Will wait forever, unless stop() is called or timeout is specified.

wake()

Wake up, if do was sleeping, and do things right away.

walk(side=None, root=None, recursive=True)

Manually run a walk on a provider, causing a single-direction sync.