maestral.daemon

This module defines functions to start and stop the sync daemon and retrieve proxy objects for a running daemon.

class maestral.daemon.Stop(value)[source]

Bases: enum.Enum

Enumeration of daemon exit results

Ok = 0
Killed = 1
NotRunning = 2
Failed = 3
class maestral.daemon.Start(value)[source]

Bases: enum.Enum

Enumeration of daemon start results

Ok = 0
AlreadyRunning = 1
Failed = 2
class maestral.daemon.Lock(path)[source]

Bases: object

A inter-process and inter-thread lock

This internally uses fasteners.InterProcessLock but provides non-blocking acquire. It also guarantees thread-safety when using the singleton() class method to create / retrieve a lock instance.

Parameters

path (str) – Path of the lock file to use / create.

Return type

None

classmethod singleton(path)[source]

Retrieve an existing lock object with a given ‘name’ or create a new one. Use this method for thread-safe locks.

Parameters

path (str) – Path of the lock file to use / create.

Return type

maestral.daemon.Lock

acquire()[source]

Attempts to acquire the given lock.

Returns

Whether or not the acquisition succeeded.

Return type

bool

release()[source]

Release the previously acquired lock.

Return type

None

locked()[source]

Checks if the lock is currently held by any thread or process.

Returns

Whether the lock is acquired.

Return type

bool

locking_pid()[source]

Returns the PID of the process which currently holds the lock or None. This should work on macOS, OpenBSD and Linux but may fail on some platforms. Always use locked() to check if the lock is held by any process.

Returns

The PID of the process which currently holds the lock or None.

Return type

Optional[int]

maestral.daemon.maestral_lock(config_name)[source]

Returns an inter-process and inter-thread lock for Maestral. This is a wrapper around Lock which fills out the appropriate lockfile path for he given config name.

Parameters

config_name (str) – The name of the Maestral configuration.

Returns

Lock instance for the config name

Return type

maestral.daemon.Lock

maestral.daemon.get_maestral_pid(config_name)[source]

Returns the PID of the daemon if it is running, None otherwise.

Parameters

config_name (str) – The name of the Maestral configuration.

Returns

The daemon’s PID.

Return type

Optional[int]

maestral.daemon.sockpath_for_config(config_name)[source]

Returns the unix socket location to be used for the config. This should default to the apps runtime directory + ‘CONFIG_NAME.sock’.

Parameters

config_name (str) – The name of the Maestral configuration.

Returns

Socket path.

Return type

str

maestral.daemon.lockpath_for_config(config_name)[source]

Returns the lock file location to be used for the config. This will be the apps runtime directory + ‘CONFIG_NAME.lock’.

Parameters

config_name (str) – The name of the Maestral configuration.

Returns

Path of lock file to use.

Return type

str

maestral.daemon.wait_for_startup(config_name, timeout=20)[source]

Waits until we can communicate with the maestral daemon for config_name.

Parameters
  • config_name (str) – Configuration to connect to.

  • timeout (float) – Timeout it seconds until we raise an error.

Raises

CommunicationError – if we cannot communicate with the daemon within the given timeout.

Return type

None

maestral.daemon.is_running(config_name)[source]

Checks if a daemon is currently running.

Parameters

config_name (str) – The name of the Maestral configuration.

Returns

Whether the daemon is running.

Return type

bool

maestral.daemon.freeze_support()[source]

Call this as early as possible in the main entry point of a frozen executable. This call will start the sync daemon if a matching command line arguments are detected and do nothing otherwise.

Return type

None

maestral.daemon.start_maestral_daemon(config_name='maestral', log_to_stderr=False)[source]

Starts the Maestral daemon with event loop in the current thread.

Startup is race free: there will never be more than one daemon running with the same config name. The daemon is a maestral.main.Maestral instance which is exposed as Pyro daemon object and listens for requests on a unix domain socket. This call starts an asyncio event loop to process client requests and blocks until the event loop shuts down. On macOS, the event loop is integrated with Cocoa’s CFRunLoop. This allows processing Cocoa events and callbacks, for instance for desktop notifications.

Parameters
  • config_name (str) – The name of the Maestral configuration to use.

  • log_to_stderr (bool) – If True, write logs to stderr.

Raises

RuntimeError – if a daemon for the given config_name is already running.

Return type

None

maestral.daemon.start_maestral_daemon_process(config_name='maestral', timeout=20)[source]

Starts the Maestral daemon in a new process by calling start_maestral_daemon().

Startup is race free: there will never be more than one daemon running for the same config name. This function will use sys.executable as a Python executable to start the daemon.

Environment variables from the current process will be preserved and updated with the environment variables defined in constants.ENV.

Parameters
  • config_name (str) – The name of the Maestral configuration to use.

  • timeout (float) – Time in sec to wait for daemon to start.

Returns

Start.Ok if successful, Start.AlreadyRunning if the daemon was already running or Start.Failed if startup failed. It is possible that Start.Ok may be returned instead of Start.AlreadyRunning in case of a race but the daemon is nevertheless started only once.

Return type

maestral.daemon.Start

maestral.daemon.stop_maestral_daemon_process(config_name='maestral', timeout=20)[source]

Stops a maestral daemon process by finding its PID and shutting it down.

This function first tries to shut down Maestral gracefully. If this fails and we know its PID, it will send SIGTERM. If that fails as well, it will send SIGKILL to the process.

Parameters
  • config_name (str) – The name of the Maestral configuration to use.

  • timeout (float) – Number of sec to wait for daemon to shut down before killing it.

Returns

Stop.Ok if successful, Stop.Killed if killed, Stop.NotRunning if the daemon was not running and Stop.Failed if killing the process failed because we could not retrieve its PID.

Return type

maestral.daemon.Stop

class maestral.daemon.MaestralProxy(config_name='maestral', fallback=False)[source]

Bases: object

A Proxy to the Maestral daemon

All methods and properties of Maestral’s public API are accessible and calls / access will be forwarded to the corresponding Maestral instance. This class can be used as a context manager to close the connection to the daemon on exit.

Example

Use MaestralProxy as a context manager:

>>> with MaestralProxy() as m:
...     print(m.status)

Use MaestralProxy directly:

>>> m = MaestralProxy()
>>> print(m.status)
>>> m._disconnect()
Variables

_is_fallback – Whether we are using an actual Maestral instance as fallback instead of a Proxy.

Parameters
  • config_name (str) – The name of the Maestral configuration to use.

  • fallback (bool) – If True, a new instance of Maestral will created in the current process when the daemon is not running.

Raises

CommunicationError – if the daemon is running but cannot be reached or if the daemon is not running and fallback is False.

Return type

None

exception maestral.daemon.CommunicationError[source]

Bases: Pyro5.errors.PyroError

Base class for the errors related to network communication problems.