complete docstrings and beta release prep

Author: Ricks-Lab

README.md

@@ -2,12 +2,16 @@
 A set of utilities to monitor and react to the status of a supported UPS
 
 ## Getting Started
-For any of the utilities to function, the config.py files must be customized using config.py.template as 
-a template. This file contains information required for the daemon utility to function.
+A set of configuration parameters are used when the config.py file is not provided.  These can be viewed with
+the command *ups-daemon --list_params*. Alternatives to these defaults can be specified in the config.py file 
+using the config.py.template file as a template.
 
 Also, a UPS list must be specified in the config.json file using config.json.template as a template.  This file
-contains details about each UPS that make snmp communication possible.  The utility required snmp v2c in order
-to communicate with the network accessible UPSs.
+contains details about each UPS that make snmp communication possible.  The utility requires snmp v2c in order
+to communicate with the network accessible UPSs.  As a result, you must configure your target Network attached 
+UPS devices to use SNMPv2 with a know Private Community String.
+
+The ups-utils rely on the command *snmpget* which is part of the snmp package that must be installed.
 
 ## ups-daemon
 With no options specified, the utility will give the current status of the UPS configured with *daemon = true*
@@ -42,14 +46,18 @@ output a table of the current status.  The *--long* option will include addition
 informational parameters. By default, unresponsive UPSs will not be displayed, but the
 *--show_unresponsive* can be used to force their display.
 
+## New in the Release  -  [v0.9.0](https://github.com/Ricks-Lab/ups-utils/releases/tag/v0.9.0)
+* Initial Beta Release - Please feedback your question/issues in the project's issues.  Thanks!
+
 ## Under Development
 The utility currently supports:
 * APC UPS with AP9630 NMC 
 * EATON UPS with PowerWalker NMC
 
 It monitors the specified UPS using snmp v2c.  I have not implemented the ability to listen to snmp traps
 yet, as I still have some research to do.  If you have different UPS and would like to extend the dictionary
-in this [code](https://github.com/Ricks-Lab/ups-utils/blob/master/UPSmodules/UPSmodule.py) to support it, feel free to make a pull request.
+in this [code](https://github.com/Ricks-Lab/ups-utils/blob/master/UPSmodules/UPSmodule.py) to support it, feel
+free to make a pull request.
 
 ## Reference Material
 * [apc-ups-snmp](https://github.com/phillipsnick/apc-ups-snmp)

UPSmodules/UPSmodule.py

@@ -628,27 +628,44 @@ def read_all_ups_list_items(self, command_list, errups=True):
             results[ups_name] = self.read_ups_list_items(command_list)
         return results
 
-    def read_ups_list_items(self, command_list):
-        results = {'display_name': self.ups_name(),
-                   'name': self.ups_name(),
-                   'uuid': self.ups_uuid(),
-                   'ups_IP': self.ups_ip(),
-                   'ups_type': self.ups_type()}
+    def read_ups_list_items(self, command_list, tups=None):
+        """ Read the specified list of monitor mib commands for all UPSs.
+        :param command_list:  A list of mib commands to be read from the active UPS
+        :type command_list: list
+        :param tups:  The target ups dictionary from list or None.
+        :type tups: dict
+        :return:  dict of results from the reading of all commands target UPS.
+        """
+        if not tups:
+            tups = self.active_ups
+        results = {'display_name': self.ups_name(tups=tups),
+                   'name': self.ups_name(tups=tups),
+                   'uuid': self.ups_uuid(tups=tups),
+                   'ups_IP': self.ups_ip(tups=tups),
+                   'ups_type': self.ups_type(tups=tups)}
         for cmd in command_list:
-            results[cmd] = self.send_snmp_command(cmd)
+            results[cmd] = self.send_snmp_command(cmd, tups=tups)
         return results
 
-    def send_snmp_command(self, command_name, target_ups=None, display=False):
-        if not target_ups:
-            target_ups = self.active_ups
-        if not self.is_responsive(target_ups):
+    def send_snmp_command(self, command_name, tups=None, display=False):
+        """ Read the specified mib commands results for specified UPS or active UPS if not specified.
+        :param command_name:  A command to be read from the target UPS
+        :type command_name: str
+        :param tups:  The target ups dictionary from list or None.
+        :type tups: dict
+        :param display: If true the results will be printed
+        :type display: bool
+        :return:  The results from the read
+        """
+        if not tups:
+            tups = self.active_ups
+        if not self.is_responsive(tups):
             return 'Invalid UPS'
-        snmp_mib_commands = self.get_mib_commands(target_ups)
+        snmp_mib_commands = self.get_mib_commands(tups)
         if command_name not in snmp_mib_commands:
             return 'No data'
         cmd_mib = snmp_mib_commands[command_name]['iso']
-        cmd_str = 'snmpget -v2c -c {} {} {}'.format(target_ups['snmp_community'],
-                                                    target_ups['ups_IP'], cmd_mib)
+        cmd_str = 'snmpget -v2c -c {} {} {}'.format(tups['snmp_community'], tups['ups_IP'], cmd_mib)
         try:
             snmp_output = subprocess.check_output(shlex.split(cmd_str), shell=False,
                                                   stderr=subprocess.DEVNULL).decode().split('\n')
@@ -667,7 +684,7 @@ def send_snmp_command(self, command_name, target_ups=None, display=False):
         if snmp_mib_commands[command_name]['decode']:
             if value in snmp_mib_commands[command_name]['decode'].keys():
                 value = snmp_mib_commands[command_name]['decode'][value]
-        if target_ups['ups_type'] == 'eaton-pw':
+        if tups['ups_type'] == 'eaton-pw':
             if command_name == 'mib_output_voltage' or command_name == 'mib_output_frequency':
                 value = int(value) / 10.0
             elif command_name == 'mib_output_current':
@@ -676,11 +693,11 @@ def send_snmp_command(self, command_name, target_ups=None, display=False):
                 value = int(value) / 10.0
             elif command_name == 'mib_system_temperature':
                 value = int(value) / 10.0
-        if command_name == 'mib_system_status' and target_ups['ups_type'] == 'apc-ap9630':
+        if command_name == 'mib_system_status' and tups['ups_type'] == 'apc-ap9630':
             value = self.bit_str_decoder(value, self.decoders['apc_system_status'])
         if command_name == 'mib_time_on_battery' or command_name == 'mib_battery_runtime_remain':
             # Create a minute, string tuple
-            if target_ups['ups_type'] == 'eaton-pw':
+            if tups['ups_type'] == 'eaton-pw':
                 # Process time for eaton-pw
                 if command_name == 'mib_time_on_battery':
                     # Measured in seconds.
@@ -704,10 +721,11 @@ def send_snmp_command(self, command_name, target_ups=None, display=False):
     @staticmethod
     def bit_str_decoder(value, decode_key):
         """ Bit string decoder
-            
-            :param value: A string representing a bit encoded set of flags
-            :param decode_key: A list representing the meaning of a 1 for each bit field
-            :returns: A string of concatenated bit decode strings 
+        :param value: A string representing a bit encoded set of flags
+        :type value: str
+        :param decode_key: A list representing the meaning of a 1 for each bit field
+        :type decode_key: list
+        :return: A string of concatenated bit decode strings
         """
         value_str = ''
         for index, bit_value in enumerate(value):
@@ -721,6 +739,11 @@ def bit_str_decoder(value, decode_key):
         return value_str
 
     def print_snmp_commands(self, tups=None):
+        """ Print all supported mib commands for the target UPS, which is the active UPS when not specified.
+        :param tups:  The target ups dictionary from list or None.
+        :type tups: dict
+        :return:  None
+        """
         if not tups:
             tups = self.active_ups
         for k, v in self.get_mib_commands(tups).items():
@@ -733,6 +756,9 @@ def print_snmp_commands(self, tups=None):
 
     # Set parameters required for daemon mode.
     def set_daemon_parameters(self):
+        """ Set all daemon parameters based on defaults in env.ut_const and the config.py file.
+        :return:  None
+        """
         if env.ut_const.ERROR_config:
             print('Error in config.py file.  Using defaults')
             return
@@ -818,11 +844,17 @@ def set_daemon_parameters(self):
                 print('Invalid threshold_battery_capacity_warn in config.py.  Using default.')
 
     def print_daemon_parameters(self):
+        """ Print all daemon parameters.
+        :return:  None
+        """
         print('Daemon parameters:')
         for k, v in self.daemon_params.items():
             print('    {}: {}'.format(k, v))
 
     def shutdown(self):
+        """ Execute the shutdown script as defined in the daemon parameters.
+        :return:  None
+        """
         if not self.daemon_params['shutdown_script']:
             print('No shutdown script defined')
             return
@@ -838,6 +870,9 @@ def shutdown(self):
                   file=sys.stderr)
 
     def cancel_shutdown(self):
+        """ Execute the cancel shutdown script as defined in the daemon parameters.
+        :return:  None
+        """
         if not self.daemon_params['cancel_shutdown_script']:
             print('No cancel shutdown script defined')
             return
@@ -853,6 +888,9 @@ def cancel_shutdown(self):
                   self.daemon_params['cancel_shutdown_script']), file=sys.stderr)
 
     def resume(self):
+        """ Execute the resume script as defined in the daemon parameters.
+        :return:  None
+        """
         if not self.daemon_params['resume_script']:
             print('No resume script defined')
             return
@@ -868,6 +906,9 @@ def resume(self):
                   file=sys.stderr)
 
     def suspend(self):
+        """ Execute the suspend script as defined in the daemon parameters.
+        :return:  None
+        """
         if not self.daemon_params['suspend_script']:
             print('No suspend script defined')
             return
@@ -885,6 +926,9 @@ def suspend(self):
 
 
 def about():
+    """ Display details about this module.
+    :return:  None
+    """
     # About me
     print(__doc__)
     print("Author: ", __author__)

UPSmodules/env.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """env.py - sets environment for ups-utils and establishes global variables
 
-
     Copyright (C) 2019  RueiKe
 
     This program is free software: you can redistribute it and/or modify
@@ -72,11 +71,19 @@ def __init__(self):
 
     @staticmethod
     def now(ltz=False):
+        """ Get current time
+        :param ltz:  Set to True to use local time zone.
+        :type ltz: bool
+        :return:  Returns current time as datetime object
+        """
         if ltz:
             return datetime.now()
         return datetime.utcnow()
 
     def check_env(self):
+        """ Check the user's environment for compatibility.
+        :return: Returns an integer indicating env error code: 0 for passes
+        """
         # Check python version
         required_pversion = [3, 6]
         (python_major, python_minor, python_patch) = platform.python_version_tuple()
@@ -117,6 +124,9 @@ def check_env(self):
 
 
 def about():
+    """ Display details about this module.
+    :return:  None
+    """
     print(__doc__)
     print('Author: ', __author__)
     print('Copyright: ', __copyright__)

ups-monitor

@@ -59,6 +59,17 @@ from gi.repository import GLib, Gtk, Gdk
 
 class MonitorWindow(Gtk.Window):
     def __init__(self, ups, header_items, command_items, devices):
+        """ Initialize the main UPS monitor window.
+        :param ups:  The main ups module object
+        :type ups: UPSsnmp
+        :param header_items:  A list of non-mib parameters
+        :type header_items: list
+        :param command_items:  A list of mib parameter results
+        :type command_items: list
+        :param devices: A dictionary of Gtk components and values
+        :type devices: dict
+        :return: None
+        """
         self.quit = False
 
         Gtk.Window.__init__(self, title='ups-monitor')
@@ -161,10 +172,26 @@ class MonitorWindow(Gtk.Window):
                 row += 1
 
     def set_quit(self, _arg2, _arg3):
+        """ Function called when quit monitor is executed.  Sets flag to end update loop.
+        :param _arg2: Ignored
+        :param _arg3: Ignored
+        :return:
+        """
         self.quit = True
 
 
 def updateData(ups, header_list, command_list, devices):
+    """ Function that updates data in MonitorWindow  with call to read data from ups.
+    :param ups:  The main ups module object
+    :type ups: UPSsnmp
+    :param header_list:  A list of non-mib parameters
+    :type header_list: list
+    :param command_list:  A list of mib parameter results
+    :type command_list: list
+    :param devices: A dictionary of Gtk components and values
+    :type devices: dict
+    :return: None
+    """
     irw = 20
     ups_data = ups.read_all_ups_list_items(command_list, errups=env.ut_const.show_unresponsive)
     if env.ut_const.LOG:
@@ -224,6 +251,23 @@ def updateData(ups, header_list, command_list, devices):
 
 
 def refresh(refreshtime, updateData, ups, header_list, command_list, devices, umonitor):
+    """ Function that continuously updates the Gtk monitor window.
+    :param refreshtime:  Delay time in seconds between monitor display refreshes
+    :type refreshtime: int
+    :param updateData: Function name that does the actual refresh of the monitor table.
+    :type updateData: FunctionType
+    :param ups:  The main ups module object
+    :type ups: UPSsnmp
+    :param header_list:  A list of non-mib parameters
+    :type header_list: list
+    :param command_list:  A list of mib parameter results
+    :type command_list: list
+    :param devices: A dictionary of Gtk components and values
+    :type devices: dict
+    :param umonitor: The main Gtk monitor window.
+    :type umonitor: MonitorWindow
+    :return: None
+    """
     while True:
         if umonitor.quit:
             print('Quitting...')
@@ -239,12 +283,23 @@ def refresh(refreshtime, updateData, ups, header_list, command_list, devices, um
 
 
 def print_monitor_table(ups, header_list, cmd_list, ups_data):
+    """ Print the monitor table in format optimized for terminal window.
+    :param ups:  The main ups module object
+    :type ups: UPSsnmp
+    :param header_list:  A list of non-mib parameters
+    :type header_list: list
+    :param cmd_list:  A list of mib parameter results
+    :type cmd_list: list
+    :param ups_data: A dictionary of results for items listed in header and command lists
+    :type ups_data: dict
+    :return:
+    """
     num_ups = ups.get_num_ups_tuple()
     if num_ups[0] < 1:
         return -1
 
-    hrw = 29
-    irw = 24
+    hrw = 29  # Row header item width
+    irw = 24  # Row data item width
 
     print('┌', '─'.ljust(hrw, '─'), sep='', end='')
     for _, _ in ups_data.items():
@@ -294,6 +349,17 @@ def print_monitor_table(ups, header_list, cmd_list, ups_data):
 
 
 def print_log(fileptr, header_list, command_list, ups_data):
+    """ Print the logfile data line.
+    :param fileptr:  The logfile fileptr
+    :type fileptr: file
+    :param header_list:  A list of non-mib parameters
+    :type header_list: list
+    :param command_list:  A list of mib parameter results
+    :type command_list: list
+    :param ups_data: A dictionary of results for items listed in header and command lists
+    :type ups_data: dict
+    :return:
+    """
     time_str = (str(env.ut_const.now(ltz=True).strftime('%c')).strip())
     for k, v in ups_data.items():
         print('{}'.format(time_str), file=fileptr, end='')
@@ -305,6 +371,15 @@ def print_log(fileptr, header_list, command_list, ups_data):
 
 
 def print_log_header(fileptr, header_list, command_list):
+    """ Print the logfile header line.
+    :param fileptr:  The logfile fileptr
+    :type fileptr: file
+    :param header_list:  A list of non-mib parameters
+    :type header_list: list
+    :param command_list:  A list of mib parameter results
+    :type command_list: list
+    :return:
+    """
     print('time', file=fileptr, end='')
     for item in header_list:
         print('|{}'.format(item), file=fileptr, end='')