parsley.runtime package

Submodules

parsley.runtime.commonimports module

Imports everything that is typically used by the end user in a Parsley config file.

parsley.runtime.datastorage module

Implements an abstraction layer for storing arbitrary process data, like sync states or file history information.

class parsley.runtime.datastorage.StorageDepartment

Bases: object

One main hive for data storage.

A main hive has a name and can store data in a tree-like structure (as in filesystems). Different subclasses exist and can be configured in different flavours.

VALUE_FILENAME = '.~parsley+~value.'

Internally used as special file name for value storage.

get_filesystem(*, filesystem, sync=None)

Gets the hive filesystem for more complex custom operations.

Parameters
Return type

parsley.filesystem.abstractfilesystem.Filesystem

get_value_bytes(*, path='/', filesystem, sync=None, throwonnotexists=True, defaultval=b'')

Gets a value as bytes (byte array).

Parameters

  • path (str) – The data path.

  • filesystem (Optional[parsley.filesystem.abstractfilesystem.Filesystem]) – The filesystem to get the data for. Not used in some implementations.

  • sync (Optional[parsley.syncengine.sync.Sync]) – The sync. Typically not needed to specify it.

  • throwonnotexists (bool) – If to throw an exception if there is no data stored for this path.

  • defaultval (Optional[bytes]) – The default value (when no one exists and throwonnotexists=False).

Return type

Optional[bytes]

get_value_string(*, path='/', filesystem=None, sync=None, throwonnotexists=True, defaultval='')

Gets a value as string.

Parameters

  • path (str) – The data path.

  • filesystem (Optional[parsley.filesystem.abstractfilesystem.Filesystem]) – The filesystem to get the data for. Not used in some implementations.

  • sync (Optional[parsley.syncengine.sync.Sync]) – The sync. Typically not needed to specify it.

  • throwonnotexists (bool) – If to throw an exception if there is no data stored for this path.

  • defaultval (Optional[str]) – The default value (when no one exists and throwonnotexists=False).

Return type

Optional[str]

has_value(*, path='/', filesystem, sync=None)

Checks if some value is stored for a path.

Parameters
Return type

bool

list_path(*, path, filesystem, sync=None)

Returns a list of names of all subitems in the given path. Those can either lead to further subitems, or can have a value, or both!

Parameters
Return type

List[str]

remove_value(*, path, filesystem, sync=None, recursive=False, throwonnotexists=True)

Removes a value from storage.

Parameters

  • path (str) – The data path.

  • filesystem (Optional[parsley.filesystem.abstractfilesystem.Filesystem]) – The filesystem to remove data from. Not used in some implementations.

  • sync (Optional[parsley.syncengine.sync.Sync]) – The sync. Typically not needed to specify it.

  • recursive (bool) – If to remove also all subitems.

  • throwonnotexists (bool) – If to throw an exception if there is no data stored for this path.

Return type

None

set_value(value, *, path='/', filesystem, sync=None)

Sets and stores a value.

Parameters
Return type

None

class parsley.runtime.datastorage.StorageLocation

Bases: object

Enumeration of storage locations.

SYNC_VOLUME = 'sync_volume'
SYSTEM = 'system'
class parsley.runtime.datastorage.StorageScope

Bases: object

Enumeration of storage scopes.

PER_SYNC = 'per_sync'
SHARED = 'shared'
class parsley.runtime.datastorage.SyncVolumeStorageDepartment(runtime, name, scope)

Bases: parsley.runtime.datastorage.StorageDepartment

Implementation of StorageDepartment for storage of data inside the sync volume (i.e. potentially on the remote device).

@note Although the data is stored in the sync volume, this data is not part of what gets synchronized

(but resides in a hidden part).

_get_rootpath(sync)
get_filesystem(*, filesystem, sync=None)

Gets the hive filesystem for more complex custom operations.

Parameters

  • filesystem – The filesystem to get the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

get_value_bytes(*, path='/', filesystem, sync=None, throwonnotexists=True, defaultval=b'')

Gets a value as bytes (byte array).

Parameters

  • path – The data path.

  • filesystem – The filesystem to get the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

  • throwonnotexists – If to throw an exception if there is no data stored for this path.

  • defaultval – The default value (when no one exists and throwonnotexists=False).

get_value_path(sync, path='/')
set_value(value, *, path='/', filesystem='', sync=None)

Sets and stores a value.

Parameters

  • value – The value data.

  • path – The data path.

  • filesystem – The filesystem to store the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

class parsley.runtime.datastorage.SystemStorageDepartment(runtime, name, scope)

Bases: parsley.runtime.datastorage.StorageDepartment

Implementation of StorageDepartment for storage of data inside the system, i.e. not on some remote place.

_get_rootpath(sync)
get_filesystem(*, filesystem=None, sync=None)

Gets the hive filesystem for more complex custom operations.

Parameters

  • filesystem – The filesystem to get the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

get_value_bytes(*, path='/', filesystem=None, sync=None, throwonnotexists=True, defaultval=b'')

Gets a value as bytes (byte array).

Parameters

  • path – The data path.

  • filesystem – The filesystem to get the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

  • throwonnotexists – If to throw an exception if there is no data stored for this path.

  • defaultval – The default value (when no one exists and throwonnotexists=False).

get_value_path(sync, path='/')
has_value(**kwa)

Checks if some value is stored for a path.

Parameters

  • path – The data path.

  • filesystem – The filesystem to check. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

set_value(value, *, path='/', filesystem=None, sync=None)

Sets and stores a value.

Parameters

  • value – The value data.

  • path – The data path.

  • filesystem – The filesystem to store the data for. Not used in some implementations.

  • sync – The sync. Typically not needed to specify it.

parsley.runtime.datastorage.get_storage_department(ctx, name, *, location='sync_volume', scope='per_sync')

Creates a StorageDepartment for storage of process data.

Parameters

  • ctx (parsley.runtime.runtime.RuntimeData) – The current runtime context.

  • name (str) – The name of this storage department name.

  • location (str) – The storage location. One of StorageLocation.

  • scope (str) – The storage scope. One of StorageScope.

Return type

Union[parsley.runtime.datastorage.SyncVolumeStorageDepartment, parsley.runtime.datastorage.SystemStorageDepartment]

parsley.runtime.projectinformations module

parsley.runtime.returnvalue module

Parsley engine return values.

class parsley.runtime.returnvalue.ReturnValue

Bases: object

Flags that roughly describe the success of a synchronization run. The return value you get on command line is composed from this flags.

DIRTY = 32

Something remained dirty and needs a new synchronization run soon.

ERROR = 1

An error occurred.

ERROR_EXECUTION = 9

An error occurred while executing the synchronization itself (excluding preparations, …).

ERROR_INITIALIZATION = 3

An error occurred in the initialization of the synchronization itself.

ERROR_PREPARATION = 5

An error occurred while enabling one of the specified parsley.preparation.abstractpreparation.Preparation before execution.

ERROR_UNPREPARATION = 17

An error occurred while disabling one of the specified parsley.preparation.abstractpreparation.Preparation after execution.

SUCCESS = 0

Everything went perfectly okay.

parsley.runtime.runtime module

The implementation for some Parsley core features.

class parsley.runtime.runtime.RuntimeData(datadir, loggers, syncs)

Bases: object

Runtime data for synchronization runs used by the parsley engine and some higher layers. Used by the synchronization implementations for logging, for communicating success values and for retrieving/setting some environment values. There is one instance for each parsley engine run (which can do multiple synchronizations).

Parameters
clone(merge_also_from=None, merge_also=None)

Clones this object.

This is used for providing objects for repeating sub-processes, so they always get a fresh but pre-populated RuntimeData object. This method returns a shallow copy, which is used for writing stuff to the original from a clone in some ways.

Parameters

  • merge_also_from (Optional[Any]) – Take all members from this object into the new clone as well.

  • merge_also (Optional[Dict[str, Optional[Any]]]) – Take all entries from this dictionary as members into the new clone as well.

Return type

parsley.runtime.runtime.RuntimeData

get_retval()

Gets the return value as combination of parsley.runtime.returnvalue.ReturnValue.

Return type

int

log(*, subject='', verb='', comment='', severity=3, symbol='')

This is the log method that is actually used by clients.

Parameters

  • subject (str) – The name of the subject, e.g. a file name (arbitrary string).

  • verb (str) – A description what happened with the subject, e.g. ‘deleted’ or ‘created’ (arbitrary string).

  • comment (str) – A description following after the verb (arbitrary string).

  • severity (int) – A parsley.logger.severity.Severity describes how important this message is. This value decides if the message will be really logged.

  • symbol (str) – One character that describes the kind of log message (arbitrary string).

Return type

None

mark_dirty()

Marks the current sync run as dirty, which leads to a faster re-execution (e.g. since one or more file was skipped).

Return type

None

set_retval(flag)

Sets a flag from parsley.runtime.returnvalue.ReturnValue to the return value.

Parameters

flag (int) –

Return type

None

parsley.runtime.successtracker module

Tracks the success of sync runs, invokes warning messages after some time of sync problems, …

class parsley.runtime.successtracker.SuccessTracker(runtime)

Bases: object

Tracks the success of sync runs.

Used internally for logging warnings when a synchronization did not run successfully since a certain timespan. It stores timestamps on the filesystem for this functionality.

Parameters

runtime (parsley.runtime.runtime.RuntimeData) –

begincall(sync)

Called by the infrastructure when a sync run begins, for bookkeeping.

Parameters

sync (parsley.syncengine.sync.Sync) –

Return type

None

end()

Signals that a task execution was scheduled for now and the process is over. This happens for successful and for failed executions and triggers a warning notification in certain situations.

Return type

None

forceexecution(sync)

Marks a sync task so it gets executed next time regardless of the sync interval.

Parameters

sync (parsley.syncengine.sync.Sync) –

Return type

None

getlastsuccessfulcall(sync)

Gets a tuple of the time of last successful execution and the forced flag of a task.

Parameters

sync (parsley.syncengine.sync.Sync) –

Return type

Tuple[Optional[datetime.datetime], bool]

setscope(syncs)

Sets the list of sync tasks for processing.

Parameters

syncs (List[parsley.syncengine.sync.Sync]) –

Return type

None

shall_skip(sync)

Determines if a sync task should be skipped now.

Parameters

sync (parsley.syncengine.sync.Sync) –

Return type

bool

successfulcall(sync)

Marks a sync task as successfully executed.

Parameters

sync (parsley.syncengine.sync.Sync) –

Return type

None

Module contents

Parsley core parts.