Current File : //lib/python3/dist-packages/twisted/python/systemd.py
# -*- test-case-name: twisted.python.test.test_systemd -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.
"""
Integration with systemd.
Currently only the minimum APIs necessary for using systemd's socket activation
feature are supported.
"""
__all__ = ["ListenFDs"]
from os import getpid
from typing import Dict, List, Mapping, Optional, Sequence
from attrs import Factory, define
@define
class ListenFDs:
"""
L{ListenFDs} provides access to file descriptors inherited from systemd.
Typically L{ListenFDs.fromEnvironment} should be used to construct a new
instance of L{ListenFDs}.
@cvar _START: File descriptors inherited from systemd are always
consecutively numbered, with a fixed lowest "starting" descriptor. This
gives the default starting descriptor. Since this must agree with the
value systemd is using, it typically should not be overridden.
@ivar _descriptors: A C{list} of C{int} giving the descriptors which were
inherited.
@ivar _names: A L{Sequence} of C{str} giving the names of the descriptors
which were inherited.
"""
_descriptors: Sequence[int]
_names: Sequence[str] = Factory(tuple)
_START = 3
@classmethod
def fromEnvironment(
cls,
environ: Optional[Mapping[str, str]] = None,
start: Optional[int] = None,
) -> "ListenFDs":
"""
@param environ: A dictionary-like object to inspect to discover
inherited descriptors. By default, L{None}, indicating that the
real process environment should be inspected. The default is
suitable for typical usage.
@param start: An integer giving the lowest value of an inherited
descriptor systemd will give us. By default, L{None}, indicating
the known correct (that is, in agreement with systemd) value will be
used. The default is suitable for typical usage.
@return: A new instance of C{cls} which can be used to look up the
descriptors which have been inherited.
"""
if environ is None:
from os import environ as _environ
environ = _environ
if start is None:
start = cls._START
if str(getpid()) == environ.get("LISTEN_PID"):
descriptors: List[int] = _parseDescriptors(start, environ)
names: Sequence[str] = _parseNames(environ)
else:
descriptors = []
names = ()
# They may both be missing (consistent with not running under systemd
# at all) or they may both be present (consistent with running under
# systemd 227 or newer). It is not allowed for only one to be present
# or for the values to disagree with each other (per
# systemd.socket(5), systemd will use a default value based on the
# socket unit name if the socket unit doesn't explicitly define a name
# with FileDescriptorName).
if len(names) != len(descriptors):
return cls([], ())
return cls(descriptors, names)
def inheritedDescriptors(self) -> List[int]:
"""
@return: The configured descriptors.
"""
return list(self._descriptors)
def inheritedNamedDescriptors(self) -> Dict[str, int]:
"""
@return: A mapping from the names of configured descriptors to
their integer values.
"""
return dict(zip(self._names, self._descriptors))
def _parseDescriptors(start: int, environ: Mapping[str, str]) -> List[int]:
"""
Parse the I{LISTEN_FDS} environment variable supplied by systemd.
@param start: systemd provides only a count of the number of descriptors
that have been inherited. This is the integer value of the first
inherited descriptor. Subsequent inherited descriptors are numbered
counting up from here. See L{ListenFDs._START}.
@param environ: The environment variable mapping in which to look for the
value to parse.
@return: The integer values of the inherited file descriptors, in order.
"""
try:
count = int(environ["LISTEN_FDS"])
except (KeyError, ValueError):
return []
else:
descriptors = list(range(start, start + count))
# Remove the information from the environment so that a second
# `ListenFDs` cannot find the same information. This is a precaution
# against some application code accidentally trying to handle the same
# inherited descriptor more than once - which probably wouldn't work.
#
# This precaution is perhaps somewhat questionable since it is up to
# the application itself to know whether its handling of the file
# descriptor will actually be safe. Also, nothing stops an
# application from getting the same descriptor more than once using
# multiple calls to `ListenFDs.inheritedDescriptors()` on the same
# `ListenFDs` instance.
del environ["LISTEN_PID"], environ["LISTEN_FDS"]
return descriptors
def _parseNames(environ: Mapping[str, str]) -> Sequence[str]:
"""
Parse the I{LISTEN_FDNAMES} environment variable supplied by systemd.
@param environ: The environment variable mapping in which to look for the
value to parse.
@return: The names of the inherited descriptors, in order.
"""
names = environ.get("LISTEN_FDNAMES", "")
if len(names) > 0:
return tuple(names.split(":"))
return ()
Mini Shell