ship some documentation
[~helmut/onoff.git] / onoff / common.py
1 """
2 Defined states:
3  * 0: The device is inactive.
4  * ST_ACTIVE|ST_TRANSITION: The device is transitioning from inactive to active.
5  * ST_ACTIVE: The device is active.
6  * ST_TRANSITION: The device is transitioning from active to inactive.
7 """
8
9 ST_ACTIVE = 1
10 ST_TRANSITION = 2
11
12 class OnoffDevice(object):
13     """A device is a thing with two states, that can be asked to transition
14     from either state to the other. It can signal state changes to interested
15     parties.
16
17     @type notify: {int -> None}
18     @ivar notify: A set of functions taking a changed state.
19
20     @type state: int
21     @ivar state: is a read-only attribute to retrieve the current state
22     """
23     def __init__(self):
24         self.notify = set()
25
26     def changestate(self, state):
27         """Tell interested parties that the state has changed to the given
28         state."""
29         for func in self.notify:
30             func(state)
31
32     def activate(self):
33         """Ask the device to power on."""
34         raise NotImplementedError
35
36     def deactivate(self):
37         """Ask the device to power off."""
38         raise NotImplementedError
39
40     def close(self):
41         """Release resources acquired by the constructor."""
42         pass
43
44 class InvertedDevice(OnoffDevice):
45     """A device that swaps active and inactive states of a give device."""
46     def __init__(self, device):
47         OnoffDevice.__init__(self)
48         self.device = device
49         self.device.activate()
50         self.device.notify.add(self.changestate)
51
52     def changestate(self, state):
53         OnoffDevice.changestate(self, state ^ ST_ACTIVE)
54
55     @property
56     def state(self):
57         return self.device.state ^ ST_ACTIVE
58
59     def activate(self):
60         self.device.deactivate()
61
62     def deactivate(self):
63         self.device.activate()
64
65     def close(self):
66         self.device.notify.remove(self.changestate)
67         self.device.close()