Skip to content

Commit 7197c18

Browse files
daescalonadaescalona
committed
typehints: add typhints for Application Monitor Daemon API
Signed-off-by: David Escalona <david.escalona@digi.com>
1 parent e90c117 commit 7197c18

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎typehints/common/digidevice/appmonitor.pyi‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
"""
2+
APIs for accessing the application monitor daemon.
3+
4+
This module allows to access and interact with the application monitor daemon:
5+
6+
from digidevice import appmonitor
7+
from digidevice.appmonitor import AppMonitorAction
8+
9+
mon_handle = AppMonitor.register_app(5000, AppMonitorAction.RESTART,
10+
"<restart_command_to_execute>")
11+
mon_handle.refresh()
12+
. . .
13+
mon_handle.unregister()
14+
"""
15+
# Copyright 2022, Digi International Inc.
16+
#
17+
# This Source Code Form is subject to the terms of the Mozilla Public
18+
# License, v. 2.0. If a copy of the MPL was not distributed with this
19+
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
20+
#
21+
# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
22+
# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
23+
# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
24+
# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
25+
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
26+
# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
27+
# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
28+
29+
from enum import Enum
30+
31+
32+
class AppMonitorError(Exception):
33+
"""
34+
Exception raised when an error occurs in the application monitor daemon.
35+
"""
36+
37+
38+
class AppMonitorAction(Enum):
39+
"""
40+
Enum for the available application monitor actions.
41+
"""
42+
KILL = ...
43+
RESTART = ...
44+
REBOOT = ...
45+
46+
def __str__(self):
47+
"""
48+
The string representation of this ``AppMonitorAction``.
49+
"""
50+
...
51+
52+
def __int__(self):
53+
"""
54+
Class constructor. Instantiates a ``AppMonitorAction`` object.
55+
"""
56+
...
57+
58+
59+
class _AppMonitorHandler:
60+
"""
61+
Helper class used to interact with the Application Monitor daemon after an application
62+
is registered.
63+
"""
64+
65+
def __init__(self, app_id: int, timeout: int, action: AppMonitorAction, restart_command: str = ""):
66+
"""
67+
Class constructor. Instantiates a new :class:`AppMonitorHandler` with the given parameters.
68+
69+
:param app_id: Application ID obtained from the registration call.
70+
:param timeout: The configured application timeout.
71+
:param action: The configured application action as :class:`AppMonitorAction`
72+
:param restart_command: The configured application restart command.
73+
"""
74+
...
75+
76+
@property
77+
def timeout(self) -> int:
78+
"""
79+
Returns the timeout configured for the application.
80+
81+
:return: The configured application timeout.
82+
"""
83+
...
84+
85+
@property
86+
def action(self) -> AppMonitorAction:
87+
"""
88+
Returns the action configured for the application.
89+
90+
:return: :class:`AppMonitorAction` The configured application action.
91+
"""
92+
...
93+
94+
@property
95+
def restart_command(self) -> str:
96+
"""
97+
Returns the command to execute after the application is killed.
98+
99+
Only takes effect when the configured application action is AppMonitorAction.RESTART
100+
101+
:return: The configured application restart command.
102+
"""
103+
...
104+
105+
def refresh(self) -> None:
106+
"""
107+
Refreshes the application in the application monitor daemon.
108+
109+
If the monitor daemon is not refreshed by the application in the configured timeout
110+
because the registered application hangs or ends unexpectedly, the daemon will execute
111+
the action configured in the registration process.
112+
113+
The application can be unregistered from the application monitor daemon at any time by
114+
calling the unregister function.
115+
116+
Usage::
117+
mon_handle.refresh()
118+
119+
:raises AppMonitorError if there is any error refreshing the application.
120+
"""
121+
...
122+
123+
def unregister(self) -> None:
124+
"""
125+
Unregisters the application from the application monitor daemon.
126+
127+
Usage::
128+
mon_handle.unregister()
129+
130+
:raises AppMonitorError if there is any error unregistering the application.
131+
"""
132+
...
133+
134+
135+
def register_app(timeout: int, action: AppMonitorAction, restart_command: str = None) -> _AppMonitorHandler:
136+
"""
137+
Registers a new application to the application monitor daemon with the given data.
138+
139+
If the register process succeeds, an :class:`AppMonitorHandler` is returned to use in further
140+
communications with the application monitor daemon.
141+
142+
The application should now start sending refresh requests to the application monitor
143+
daemon with an interval lower than the configured timeout.
144+
145+
If the monitor daemon is not refreshed by the application in the configured timeout
146+
because the registered application hangs or ends unexpectedly, the daemon will execute
147+
the action configured in the registration process.
148+
149+
The application can be unregistered from the application monitor daemon at any time by
150+
calling the unregister function.
151+
152+
Available register actions are:
153+
AppMonitorAction.KILL: Kill the application
154+
AppMonitorAction.RESTART: Kill the application and execute the provided restart command
155+
AppMonitorAction.REBOOT: Reboot the device
156+
157+
Usage::
158+
from digidevice import appmonitor
159+
from digidevice.appmonitor import AppMonitorAction
160+
161+
mon_handle = appmonitor.register_app(5000, AppMonitorAction.KILL)
162+
mon_handle = appmonitor.register_app(5000, AppMonitorAction.REBOOT)
163+
mon_handle = appmonitor.register_app(5000, AppMonitorAction.RESTART, "<restart_command>")
164+
165+
:param timeout: Maximum amount of time -in milliseconds- to wait without a refresh to
166+
consider the application dead or hang.
167+
:param action: :class:`AppMonitorAction` Action to execute when the application dies
168+
or hangs.
169+
:param restart_command: Command to execute after application is killed when the configured action
170+
is RESTART.
171+
172+
:raises ValueError if pid, timeout, or action is not valid.
173+
:raises AppMonitorError if there is any error registering the application
174+
175+
:return: :class:`AppMonitorHandler` handler to use to refresh or unregister the application from
176+
the Application Monitor daemon .
177+
"""
178+
...

0 commit comments

Comments
 (0)