OS-specifics¶
Note that satella’s posix submodule is a deprecated alias for os
Note that in blatant disregard of this name’s module some of these routines will work on Windows. So, a routine is available on Windows unless stated otherwise.
whereis¶
- satella.os.whereis(name)¶
Looking in PATH return a sequence of executable files having provided name.
Additionally, on Windows, it will use PATHEXT.
Note
on Windows name is supposed to be without extension!
- Parameters:
name (str) – name of the executable to search for
- Returns:
an iterator of absolute paths to given executable
- Return type:
Iterator[str]
suicide¶
Kill your process (and your process group). Does not work on Windows (NotImplementedError). See issue #37 on GitHub.
- satella.os.suicide(kill_entire_pg=True)¶
Kill self.
- Parameters:
kill_entire_pg (bool) – whether to kill entire PG if a session leader. Won’t work on Windows.
- Return type:
None
daemonize¶
Become a daemonized process. Does not work on Windows (OSError).
- satella.os.daemonize(exit_via=<built-in function exit>, redirect_std_to_devnull=True, uid=None, gid=None)¶
Make this process into a daemon.
This entails:
umask 0
forks twice
be the child of init
becomes session leader
changes root directory to /
closes stdin, stdout, stderr
(option) redirects stdin, stdout, stderr to /dev/null
Refer - “Advanced Programming in the UNIX Environment” 13.3
- Parameters:
exit_via (Callable) – callable used to terminate process
redirect_std_to_devnull (bool) – whether to redirect stdin, stdout and stderr to /dev/null
uid (Optional[int]) – User to set (via seteuid). Default - this won’t be done. You can pass either user name as string or UID.
gid (Optional[int]) – Same as UID, but for groups. These will be resolved too.
- Raises:
KeyError – uid/gid was passed as string, but getpwnam() failed
OSError – platform is Windows
hang_until_sig¶
Sleep until a signal is received.
- satella.os.hang_until_sig(extra_signals=None, sleep_interval=2)¶
Will hang until this process receives SIGTERM or SIGINT. If you pass extra signal IDs (signal.SIG*) with extra_signals, then also on those signals this call will release.
Periodic sleeping with polling was chosen as the approach of choice, as pause() seemed to work a bit shakily multi-platform.
- Parameters:
extra_signals (Optional[Sequence[int]]) – a list of extra signals to listen to
sleep_interval (float) – amount of time to sleep between checking for termination condition.
- Return type:
None
is_running_as_root¶
Return if running as root. Routine unavailable on Windows (OSError).
- satella.os.is_running_as_root()¶
Is this process running as root?
Checks whether effective UID is 0
- Returns:
bool
- Raises:
OSError – called on Windows!
- Return type:
bool
PIDFileLock¶
This is meant to acquire a lock on a file.
- class satella.os.PIDFileLock(pid_file, base_dir='/var/run')¶
Acquire a PID lock file.
Usage:
>>> with PIDFileLock('my_service.pid'): >>> ... rest of code ..
Any alternatively
>>> pid_lock = PIDFileLock('my_service.pid') >>> pid_lock.acquire() >>> ... >>> pid_lock.release()
The constructor doesn’t throw, __enter__ or acquire() does, one of:
- ResourceLocked - lock is already held. This has two attributes - pid (int), the PID of holder,
and is_alive (bool) - whether the holder is an alive process
Initialize a PID lock file object
- Parameters:
pid_file – rest of path
base_dir – base lock directory
- acquire()¶
Acquire the PID lock
- Raises:
ResourceLocked – if lock if held
- Return type:
None
- release()¶
Free the lock :raises RuntimeError: lock not acquired
- Return type:
None