platforms

Platforms.

Utilities dealing with platform specifics: signals, daemonization, users, groups, and so on.

Module Contents

Classes

LockFailed() Raised if a PID lock can’t be acquired.
Pidfile(self,path) Pidfile.
DaemonContext(self,pidfile=None,workdir=None,umask=None,fake=False,after_chdir=None,after_forkers=True,**kwargs) Context manager daemonizing the process.
Signals() Convenience interface to signals.

Functions

isatty(fh) Return true if the process has a controlling terminal.
pyimplementation() Return string identifying the current Python implementation.
create_pidlock(pidfile) Create and verify pidfile.
_create_pidlock(pidfile)
fd_by_path(paths) Return a list of file descriptors.
detached(logfile=None,pidfile=None,uid=None,gid=None,umask=0,workdir=None,fake=False,**opts) Detach the current process in the background (daemonize).
parse_uid(uid) Parse user id.
parse_gid(gid) Parse group id.
_setgroups_hack(groups)
setgroups(groups) Set active groups from a list of group ids.
initgroups(uid,gid) Init process group permissions.
setgid(gid) Version of os.setgid() supporting group names.
setuid(uid) Version of os.setuid() supporting usernames.
maybe_drop_privileges(uid=None,gid=None) Change process privileges to new user/group.
_setuid(uid,gid)
signal_name(signum) Return name of signal from signal number.
strargv(argv)
set_process_title(progname,info=None) Set the ps name for the currently running process.
set_mp_process_title(progname,info=None,hostname=None) Set the ps name from the current process name.
set_mp_process_title(progname,info=None,hostname=None) Set the ps name from the current process name.
get_errno_name(n) Get errno for string (e.g., ENOENT).
ignore_errno(*errnos,**kwargs) Context manager to ignore specific POSIX error codes.
check_privileges(accept_content)
isatty(fh)

Return true if the process has a controlling terminal.

pyimplementation()

Return string identifying the current Python implementation.

class LockFailed

Raised if a PID lock can’t be acquired.

class Pidfile(path)

Pidfile.

This is the type returned by create_pidlock().

See Also:
Best practice is to not use this directly but rather use the create_pidlock() function instead: more convenient and also removes stale pidfiles (when the process holding the lock is no longer running).
__init__(path)
acquire()

Acquire lock.

is_locked()

Return true if the pid lock exists.

release(*args)

Release lock.

read_pid()

Read and return the current pid.

remove()

Remove the lock.

remove_if_stale()

Remove the lock if the process isn’t running.

I.e. process does not respons to signal.

write_pid()
create_pidlock(pidfile)

Create and verify pidfile.

If the pidfile already exists the program exits with an error message, however if the process it refers to isn’t running anymore, the pidfile is deleted and the program continues.

This function will automatically install an atexit handler to release the lock at exit, you can skip this by calling _create_pidlock() instead.

Returns:
Pidfile: used to manage the lock.
Example:
>>> pidlock = create_pidlock('/var/run/app.pid')
_create_pidlock(pidfile)
fd_by_path(paths)

Return a list of file descriptors.

This method returns list of file descriptors corresponding to file paths passed in paths variable.

Arguments:
paths: List[str]: List of file paths.
Returns:
List[int]: List of file descriptors.
Example:
>>> keep = fd_by_path(['/dev/urandom', '/my/precious/'])
class DaemonContext(pidfile=None, workdir=None, umask=None, fake=False, after_chdir=None, after_forkers=True, **kwargs)

Context manager daemonizing the process.

__init__(pidfile=None, workdir=None, umask=None, fake=False, after_chdir=None, after_forkers=True, **kwargs)
redirect_to_null(fd)
open()
close(*args)
_detach()
detached(logfile=None, pidfile=None, uid=None, gid=None, umask=0, workdir=None, fake=False, **opts)

Detach the current process in the background (daemonize).

Arguments:
logfile (str): Optional log file.
The ability to write to this file will be verified before the process is detached.
pidfile (str): Optional pid file.
The pidfile won’t be created, as this is the responsibility of the child. But the process will exit if the pid lock exists and the pid written is still running.
uid (int, str): Optional user id or user name to change
effective privileges to.
gid (int, str): Optional group id or group name to change
effective privileges to.
umask (str, int): Optional umask that’ll be effective in
the child process.

workdir (str): Optional new working directory. fake (bool): Don’t actually detach, intended for debugging purposes. **opts (Any): Ignored.

Example:
>>> from celery.platforms import detached, create_pidlock
>>> with detached(
...           logfile='/var/log/app.log',
...           pidfile='/var/run/app.pid',
...           uid='nobody'):
... # Now in detached child process with effective user set to nobody,
... # and we know that our logfile can be written to, and that
... # the pidfile isn't locked.
... pidlock = create_pidlock('/var/run/app.pid')
...
... # Run the program
... program.run(logfile='/var/log/app.log')
parse_uid(uid)

Parse user id.

Arguments:
uid (str, int): Actual uid, or the username of a user.
Returns:
int: The actual uid.
parse_gid(gid)

Parse group id.

Arguments:
gid (str, int): Actual gid, or the name of a group.
Returns:
int: The actual gid of the group.
_setgroups_hack(groups)
setgroups(groups)

Set active groups from a list of group ids.

initgroups(uid, gid)

Init process group permissions.

Compat version of os.initgroups() that was first added to Python 2.7.

setgid(gid)

Version of os.setgid() supporting group names.

setuid(uid)

Version of os.setuid() supporting usernames.

maybe_drop_privileges(uid=None, gid=None)

Change process privileges to new user/group.

If UID and GID is specified, the real user/group is changed.

If only UID is specified, the real user is changed, and the group is changed to the users primary group.

If only GID is specified, only the group is changed.

_setuid(uid, gid)
class Signals

Convenience interface to signals.

If the requested signal isn’t supported on the current platform, the operation will be ignored.

Example:
>>> from celery.platforms import signals
>>> from proj.handlers import my_handler
>>> signals['INT'] = my_handler
>>> signals['INT']
my_handler
>>> signals.supported('INT')
True
>>> signals.signum('INT')
2
>>> signals.ignore('USR1')
>>> signals['USR1'] == signals.ignored
True
>>> signals.reset('USR1')
>>> signals['USR1'] == signals.default
True
>>> from proj.handlers import exit_handler, hup_handler
>>> signals.update(INT=exit_handler,
...                TERM=exit_handler,
...                HUP=hup_handler)
arm_alarm(seconds)
arm_alarm(seconds)
arm_alarm(seconds)
reset_alarm()
supported(name)

Return true value if signal by name exists on this platform.

signum(name)

Get signal number by name.

reset(*signal_names)

Reset signals to the default signal handler.

Does nothing if the platform has no support for signals, or the specified signal in particular.

ignore(*names)

Ignore signal using SIG_IGN.

Does nothing if the platform has no support for signals, or the specified signal in particular.

__getitem__(name)
__setitem__(name, handler)

Install signal handler.

Does nothing if the current platform has no support for signals, or the specified signal in particular.

update(_d_=None, **sigmap)

Set signal handlers from a mapping.

signal_name(signum)

Return name of signal from signal number.

strargv(argv)
set_process_title(progname, info=None)

Set the ps name for the currently running process.

Only works if :pypi:`setproctitle` is installed.

set_mp_process_title(*a, **k)

Disabled feature.

set_mp_process_title(progname, info=None, hostname=None)

Set the ps name from the current process name.

Only works if :pypi:`setproctitle` is installed.

get_errno_name(n)

Get errno for string (e.g., ENOENT).

ignore_errno(*errnos, **kwargs)

Context manager to ignore specific POSIX error codes.

Takes a list of error codes to ignore: this can be either the name of the code, or the code integer itself:

>>> with ignore_errno('ENOENT'):
...     with open('foo', 'r') as fh:
...         return fh.read()

>>> with ignore_errno(errno.ENOENT, errno.EPERM):
...    pass
Arguments:
types (Tuple[Exception]): A tuple of exceptions to ignore
(when the errno matches). Defaults to Exception.
check_privileges(accept_content)