maestral.daemon
#
This module defines functions to start and stop the sync daemon and retrieve proxy objects for a running daemon.
Module Contents#
- 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
- class maestral.daemon.Lock(path)[source]#
An inter-process and inter-thread lock
This internally uses
fasteners.InterProcessLock
but provides non-blocking acquire. It also guarantees thread-safety when using thesingleton()
class method to create / retrieve a lock instance.- Parameters:
path (str) – Path of the lock file to use / create.
- 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.
- acquire()[source]#
Attempts to acquire the given lock.
- Returns:
Whether the acquisition succeeded.
- Return type:
- locked()[source]#
Checks if the lock is currently held by any thread or process.
- Returns:
Whether the lock is acquired.
- Return type:
- 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 uselocked()
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:
int | None
- 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 the given config name.
- 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’.
- 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’.
- maestral.daemon.get_maestral_pid(config_name)[source]#
Returns the PID of the daemon if it is running,
None
otherwise.
- maestral.daemon.wait_for_startup(config_name, timeout=30)[source]#
Waits until we can communicate with the maestral daemon for
config_name
.
- 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:
- 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=30)[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:
- Returns:
Start.Ok
if successful,Start.AlreadyRunning
if the daemon was already running orStart.Failed
if startup failed. It is possible thatStart.Ok
may be returned instead ofStart.AlreadyRunning
in case of a race but the daemon is nevertheless started only once.- Return type:
- maestral.daemon.stop_maestral_daemon_process(config_name='maestral', timeout=10)[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:
- Returns:
Stop.Ok
if successful,Stop.Killed
if killed,Stop.NotRunning
if the daemon was not running andStop.Failed
if killing the process failed because we could not retrieve its PID.- Return type:
- class maestral.daemon.MaestralProxy(config_name='maestral', fallback=False)[source]#
Bases:
ContextManager
[MaestralProxy
]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:
>>> import src.maestral.cli.cli_info >>> with MaestralProxy() as m: ... print(src.maestral.cli.cli_info.status)
Use MaestralProxy directly:
>>> import src.maestral.cli.cli_info >>> m = MaestralProxy() >>> print(src.maestral.cli.cli_info.status) >>> m._disconnect()
- Variables:
_is_fallback – Whether we are using an actual Maestral instance as fallback instead of a Proxy.
- Parameters:
- Raises:
CommunicationError – if the daemon is running but cannot be reached or if the daemon is not running and
fallback
isFalse
.