SignalWaiter

Complexity

Total Complexity

6

Size/Duplication

Total Lines	51
Duplicated Lines	0 %

Importance

Changes	1
Bugs	0	Features	0

2 Methods

Rating	Name	Duplication	Size	Complexity
A	wait()	0	9	2
B	__init__()	0	22	4

# -*- coding: utf-8 -*-
"""Various helper classes.

.. moduleauthor:: Kenny Freeman <kenny.freeman@gmail.com>

"""

__author__ = 'Kenny Freeman'
__email__ = 'kenny.freeman@gmail.com'
__license__     = "ISCL"
__docformat__   = 'reStructuredText'

import os
import os.path
import time
import fcntl
import socket
import signal


def get_hostname():
    """
    Returns the hostname of the system the code is running on. Eventually this
    may include more checks.

    :rtype: str
    """
    return socket.gethostname().split(".")[0]


def escape_tag(tag):
    """Escapes a string for use in eg. an influxdb measurement tag.
    todo: regexp replacements

    :param tag: a string
    :type tag: str
    :rtype: str
    """
    rpls = [(" ", "\ "), (",", "\,"), ("\n", "\\n")]
    for rpl in rpls:
        tag = tag.replace(*rpl)
    return tag


def escape_field(field):
    """Escapes a string for use in eg. an influxdb measurement field.
    todo: regexp replacements

    :param field: a string
    :type field: str
    :rtype: str
    """
    rpls = [(" ", "\ "), (",", "\,"), ("\n", "\\n"), ('"', '\"')]
    for rpl in rpls:
        field = field.replace(*rpl)
    return '""{0}""'.format(field)


def replace_chars(tag, rpls=None, rpl_with=None):
    """Rewrites a string to make it suitable for use in eg. a graphite metric.
    todo: regexp replacements

    :param tag: the tag to process
    :type tag: str
    :param repl_chars: a list of strings to replace
    :type repl_chars: list
    :param repl_char: a string to replace each repl_chars with
    :type repl_char: str
    :rtype: str
    """
    if not rpls:
        rpls = [" ", ".", "\n", "="]
    if not rpl_with:
        rpl_with = "_"
    for rpl in rpls:
        tag = tag.replace(rpl, rpl_with)
    return tag


class Interval(object):
    """A simple helper class to ensure a loop occours every ltime seconds
    while optionally providing a means to interupt the loop with a
    :class:`threading.Event`.


    :param ltime: The target duration of a loop
    :type ltime: int or float
    :param evt: An event object that will cause the loop to complete early if
        the event is triggered while waiting.
    :type evt: threading.Event
    :raises: ValueError if the passed loop time is not an int or float or is < 0


    As an example, use it like this to loop on an interval:

    :Example:

        >>> import threading
        >>> evt = threading.Event()
        >>> while loop:
        >>>     with Interval(111.1, evt) as timer:
        >>>         do_things_here()

    .. note:: if the do_things_here() call returns before the loop timer
        completes the timer object will either evt.wait() if evt was defined or
        time.sleep() for the time remaining in the interval.
    """

    def __init__(self, ltime, evt=None):
        if ltime is None or ltime < 0:
            raise ValueError("an interval must be defined")
        self.ltime = ltime
        self.evt = evt
        self.lstart = None


    @property
    def remaining(self):
        """Return the remaining time in the loop.

        :rtype: float
        """
        if self.lstart is not None:
            return self.ltime - (time.time() - self.lstart)
        return 0.0


    @property
    def elapsed(self):
        """Return the elapsed time of the loop.

        :rtype: float
        """
        if self.lstart is not None:
            return time.time() - self.lstart
        return 0.0


    def __str__(self):
        """Return a nicely formatted string.

        :rtype: str
        """
        elapsed = None
        if self.lstart is not None:
            elapsed = time.time() - self.lstart
        s = "Interval {0} seconds, {1} elapsed, {2} started"
        return s.format(self.ltime, elapsed, self.lstart)


    def __repr__(self):
        """Return a nicely formatted string.

        :rtype: str
        """
        elapsed = None
        if self.lstart is not None:
            elapsed = time.time() - self.lstart
        s = "Interval {0} seconds, {1} elapsed, {2} started"
        return s.format(self.ltime, elapsed, self.lstart)


    def __enter__(self):
        """Called on entrance to with() statement - simply records loop start
        time.

        :rtype: Interval"""
        self.lstart = time.time()
        return self


    def __exit__(self, *args):
        """Called on exit from a with() statement and either waits on the
        self.evt :class:`threading.Event` event if defined or time.sleep()'s
        the remaining interval time."""
        if self.lstart is None:
            self.ltstart = time.time()
        # block on the event for the remaining time, if any
        wtime = self.ltime - (time.time() - self.lstart)
        if wtime > 0:
            if self.evt is not None:
                self.evt.wait(wtime)
            else:
                time.sleep(wtime)


class SignalWaiter(object):
    """A helper class that makes waiting on signals very easy. Define the
    list of signals to wait for and to ignore and then call wait(). Instead of
    using signal handler functions it uses the signal.set_wakeup_fd() function
    and blocks on read().

    See http://www.pocketnix.org/doc/Fighting_set__wakeup__fd/ and others for
    more details.

    :param sig_wait: :class:`list` signals to wait for
    :type sig_wait: list
    :param sig_ignore: :class:`list` signals to ignore
    :type sig_ignore: list
    """

    def __init__(self, sig_wait, sig_ignore):
        """Create a :class:`SignalWaiter`"""
        self.sig_wait = sig_wait
        self.sig_ignore = sig_ignore

        # use a pipe to listen for signals
        self.rpipe, self.wpipe = os.pipe()
        # set non blocking mode on the write end of the pipe
        flags = fcntl.fcntl(self.wpipe, fcntl.F_GETFL, 0)
        flags = flags | os.O_NONBLOCK
        flags = fcntl.fcntl(self.wpipe, fcntl.F_SETFL, flags)

        # set the write end as a signal wakeup fd - we read signals from it
        signal.set_wakeup_fd(self.wpipe)

        # install dummy signal handlers that do nothing
        for signum in self.sig_wait:
            signal.signal(signum, lambda x,y: None)

        # install the ignore signal handler for sig_ignore signals
        for signum in self.sig_ignore:
            signal.signal(signum, signal.SIG_IGN)

        # now a call to wait() blocks the caller until a signal is received
        # only the signals we've registered handlers for will trigger


    def wait(self):
        """Blocks the calling thread until signal(s) are received.

        :rtype: :class:`int` or :class:`Exception`
        """
        try:
            return os.read(self.rpipe, 1)
        except Exception as e:
            return e