BC-02: General clean-up of code comments, and code readability.

BAC0/core/app/ScriptApplication.py

@@ -7,17 +7,13 @@
 '''
 ScriptApplication 
 =================
-Built around bacpypes::BIPSimpleApplication this module deals with requests
-created by a child app. It prepares requests and interacts with the BACnet stack.
 
-This module will also listen for responses to requests (indication or confirmation).
+A basic BACnet application (bacpypes BIPSimpleApplication) for interacting with 
+the bacpypes BACnet stack.  It enables the base-level BACnet functionality 
+(a.k.a. device discovery) - meaning it can send & receive WhoIs & IAm messages.
 
-Response will be added to a Queue, we'll wait for the response to be processed
-by the caller, then resume.
-
-This object will be added to script objects and will be runned as thread
-
-See BAC0.scripts for more details.
+Additional functionality is enabled by inheriting this application, and then 
+extending it with more functions. [See BAC0.scripts for more examples of this.]
 
 '''
 #--- standard Python modules ---
@@ -39,16 +35,13 @@
 @bacpypes_debugging
 class ScriptApplication(BIPSimpleApplication):
     """
-    Defines a BACnet application to process requests
-    """
-
-    def __init__(self, *args):
-        """
-        Creation of the application. Adding properties to basic B/IP App.
+    Defines a basic BACnet/IP application to process BACnet requests.
 
-        :param *args: local object device, local IP address
+    :param *args: local object device, local IP address
         See BAC0.scripts.BasicScript for more details.
-        """
+        
+    """
+    def __init__(self, *args):
         logging.getLogger("comtypes").setLevel(logging.INFO)
 
         self.localAddress = None
@@ -66,8 +59,6 @@ def __init__(self, *args):
         else:
             self.local_unicast_tuple = ('', 47808)
             self.local_broadcast_tuple = ('255.255.255.255', 47808)
-
-        #log_debug(ScriptApplication, "__init__ %r" % args)
 
 
     def do_WhoIsRequest(self, apdu):
@@ -77,8 +68,7 @@ def do_WhoIsRequest(self, apdu):
         # build a key from the source and parameters
         key = (str(apdu.pduSource),
             apdu.deviceInstanceRangeLowLimit,
-            apdu.deviceInstanceRangeHighLimit,
-            )
+            apdu.deviceInstanceRangeHighLimit )
 
         # count the times this has been received
         self.who_is_counter[key] += 1

BAC0/core/devices/Device.py

@@ -75,19 +75,17 @@ class Device(SQLMixin):
     """
     Represent a BACnet device.  Once defined, it allows use of read, write, sim, release 
     functions to communicate with the device on the network.
+    
+    :param addr: address of the device (ex. '2:5')
+    :param device_id: bacnet device ID (boid)
+    :param network: defined by BAC0.connect()
+    :param poll: (int) if > 0, will poll every points each x seconds.
+
+    :type address: (str)
+    :type device_id: int
+    :type network: BAC0.scripts.ReadWriteScript.ReadWriteScript
     """
-
     def __init__(self, address, device_id, network, *, poll=10, from_backup = None, segmentation_supported = True):
-        """
-        Initialization require address, device id and bacnetApp (the script itself)
-        :param addr: address of the device (ex. '2:5')
-        :param device_id: bacnet device ID (boid)
-        :param network: defined by BAC0.connect()
-        :param poll: (int) if > 0, will poll every points each x seconds.
-        :type address: (str)
-        :type device_id: int
-        :type network: BAC0.scripts.ReadWriteScript.ReadWriteScript
-        """
         self.properties = DeviceProperties()
 
         self.properties.address = address
@@ -168,6 +166,7 @@ def notes(self):
         """
         Allow the addition of text notes to the device.
         Notes are stored as timeseries (same than points)
+
         :returns: pd.Series
         """
         notes_table = pd.Series(self._notes.notes, index=self._notes.timestamp)
@@ -178,6 +177,7 @@ def notes(self):
     def notes(self, note):
         """
         Setter for notes
+
         :param note: (str)
         """
         self._notes.timestamp.append(datetime.now())
@@ -198,6 +198,7 @@ def chart(self, list_of_points, *, title='Live Trending', show_notes=True):
         """
         Draw a chart from a list of points.  Refer to the pandas and matplotlib doc for details on 
         the plot() function and the args they accept.
+
         :param list_of_points: a list of point name as str
         :param plot_args: arg for plot function
         :returns: plot()
@@ -229,6 +230,7 @@ def chart(self, list_of_points, *, title='Live Trending', show_notes=True):
     def simulated_points(self):
         """
         iterate over simulated points
+
         :returns: points if simulated (out_of_service == True)
         :rtype: BAC0.core.devices.Points.Point
         """
@@ -287,6 +289,7 @@ def to_excel(self):
     def __setitem__(self, point_name, value):
         """
         Write, sim or ovr value
+
         :param point_name: Name of the point to set
         :param value: value to write to the point
         :type point_name: str
@@ -317,22 +320,18 @@ def _parseArgs(self, arg):
     def analog_units(self):
         raise NotImplementedError()
 
-
     @property
     def temperatures(self):
         raise NotImplementedError()
 
-
     @property
     def percent(self):
         raise NotImplementedError()
 
-
     @property
     def multi_states(self):
         raise NotImplementedError()
 
-
     @property
     def binary_states(self):
         raise NotImplementedError()
@@ -343,12 +342,9 @@ def _findPoint(self, name, force_read=True):
         Helper that retrieve point based on its name.
 
         :param name: (str) name of the point
-        :param force_read: (bool) read value of the point each time the func
-                            is called.
+        :param force_read: (bool) read value of the point each time the function is called.
         :returns: Point object
-        :rtype: BAC0.core.devices.Point.Point (NumericPoint, EnumPoint or
-        BooleanPoint)
-
+        :rtype: BAC0.core.devices.Point.Point (NumericPoint, EnumPoint or BooleanPoint)
         """
         raise NotImplementedError()
 
@@ -743,12 +739,8 @@ def __repr__(self):
 #@fix_docs
 class DeviceFromDB(DeviceConnected):
     """
-    This state is used when replaying previous data.
-    Every call to 
-        device['point_name'] 
-    will result on last valid value.
-    
-    Histories for each point are available
+    [Device state] Where requests for a point's present value returns the last 
+    valid value from the point's history.
     """
     def _init_state(self):
         try:

BAC0/core/devices/Points.py

@@ -528,7 +528,6 @@ class EnumPoint(Point):
     """
     Representation of an Enumerated (multiState) value
     """
-
     def __init__(self, device=None,
                  pointType=None,    pointAddress=None,  pointName=None,
                  description=None,  presentValue=None,  units_state=None):

BAC0/core/functions/discoverPoints.py

@@ -33,13 +33,13 @@ def discoverPoints(bacnetapp, address, devID):
 
     :returns: a tuple with deviceName, pss, objList, df
 
-    *deviceName* : name of the device
-    *pss* : protocole service supported
-    *objList* : list of bacnet object (ex. analogInput, 1)
-    *df* : is a dataFrame containing pointType, pointAddress, pointName, description
-    presentValue and units
+        * *deviceName* : name of the device
+        * *pss* : protocole service supported
+        * *objList* : list of bacnet object (ex. analogInput, 1)
+        * *df* : is a dataFrame containing pointType, pointAddress, pointName, description
+        presentValue and units
 
-    If pandas can't be found, df will be a simple array
+        If pandas can't be found, df will be a simple array
     """
     pss = bacnetapp.read('{} device {} protocolServicesSupported'.format(address, devID))
     deviceName = bacnetapp.read('{} device {} objectName'.format(address, devID))

BAC0/core/io/Read.py

@@ -9,9 +9,11 @@
 
     Used while defining an app:
     Example::
+
         class BasicScript(WhoisIAm, ReadProperty)
 
     Class::
+
         ReadProperty()
             def read()
             def readMultiple()
@@ -64,7 +66,8 @@ class ReadProperty():
 #        self._started = False
 
     def read(self, args, arr_index = None):
-        """ Build a ReadProperty request, wait for the answer and return the value
+        """
+        Build a ReadProperty request, wait for the answer and return the value
 
         :param args: String with <addr> <type> <inst> <prop> [ <indx> ]
         :returns: data read from device (str representing data like 10 or True)

BAC0/scripts/BasicScript.py

@@ -53,23 +53,26 @@ def stopApp()
 class BasicScript():
     """
     Build a running BACnet/IP device that accepts WhoIs and IAm requests
+    Initialization requires some minimial information about the local device.
+    
+    :param localIPAddr='127.0.0.1':
+    :param localObjName='BAC0':
+    :param DeviceId=None:
+    :param maxAPDULengthAccepted='1024':
+    :param maxSegmentsAccepted='1024':
+    :param segmentationSupported='segmentedBoth':
     """
-
-    def __init__(self, localIPAddr=None, localObjName='BAC0', DevId=None,
+    def __init__(self, localIPAddr='127.0.0.1', localObjName='BAC0', DeviceId=None,
                  maxAPDULengthAccepted='1024', maxSegmentsAccepted='1024', segmentationSupported='segmentedBoth'):
-        """
-        Initialization requires some minimial information about the local device.
-            Name, Device ID, IP Address, Vendor, packet sizes, and packet segmentation capabilities.
-        """
         log_debug("Configure App")
 
         self.response = None
         self._initialized = False
         self._started = False
         self._stopped = False
 
-        self.localIPAddr = localIPAddr if localIPAddr else '127.0.0.1'
-        self.Boid = int(DevId) if DevId else (3056177 + int(random.uniform(0, 1000)))
+        self.localIPAddr= localIPAddr
+        self.Boid = int(DeviceId) if DeviceId else (3056177 + int(random.uniform(0, 1000)))
 
         self.segmentationSupported = segmentationSupported
         self.maxSegmentsAccepted = maxSegmentsAccepted

BAC0/scripts/ReadWriteScript.py

@@ -53,17 +53,13 @@ class ReadWriteScript(BasicScript, WhoisIAm, ReadProperty, WriteProperty, Simula
     """
     Build a BACnet application to accept read and write requests.
     [Basic Whois/IAm functions are implemented in parent BasicScript class.]
-
     Once created, execute a whois() to build a list of available controllers.
-    """
+    Initialization requires information on the local device.
 
-    def __init__(self, ip=None):
-        """
-        Initialization requires information on the local device
-        :param ip: (str) '127.0.0.1'
-
-        Address must be in the same subnet as the BACnet network [BBMD and Foreign Device - not supported] 
-        """
+    :param ip='127.0.0.1': Address must be in the same subnet as the BACnet network 
+        [BBMD and Foreign Device - not supported] 
+    """
+    def __init__(self, ip='127.0.0.1'):
         log_debug("Configurating app")
         if ip is None:
             host = HostIP()

doc/source/BAC0.core.app.rst

@@ -1,22 +1,18 @@
 BAC0.core.app package
 =====================
 
-Submodules
-----------
-
-BAC0.core.app.ScriptApplication module
---------------------------------------
+BAC0.core.app.ScriptApplication
+-------------------------------
 
 .. automodule:: BAC0.core.app.ScriptApplication
     :members:
     :undoc-members:
     :show-inheritance:
 
-
 Module contents
 ---------------
 
 .. automodule:: BAC0.core.app
     :members:
     :undoc-members:
-    :show-inheritance:
+    :show-inheritance:

doc/source/BAC0.core.devices.rst

@@ -1,22 +1,20 @@
 BAC0.core.devices package
 =========================
 
-Submodules
-----------
 
-BAC0.core.devices.Device module
--------------------------------
+BAC0.core.devices.Device
+------------------------
 
 .. automodule:: BAC0.core.devices.Device
     :members:
     :undoc-members:
     :show-inheritance:
 
 
-Module contents
----------------
+BAC0.core.devices.Points
+------------------------
 
-.. automodule:: BAC0.core.devices
+.. automodule:: BAC0.core.devices.Points
     :members:
     :undoc-members:
     :show-inheritance:

doc/source/BAC0.core.functions.rst

@@ -1,35 +1,33 @@
 BAC0.core.functions package
 ===========================
 
-Submodules
-----------
 
-BAC0.core.functions.GetIPAddr module
-------------------------------------
+BAC0.core.functions.GetIPAddr
+-----------------------------
 
 .. automodule:: BAC0.core.functions.GetIPAddr
     :members:
     :undoc-members:
     :show-inheritance:
 
-BAC0.core.functions.PrintDebug module
--------------------------------------
+BAC0.core.functions.PrintDebug
+------------------------------
 
 .. automodule:: BAC0.core.functions.PrintDebug
     :members:
     :undoc-members:
     :show-inheritance:
 
-BAC0.core.functions.WhoisIAm module
------------------------------------
+BAC0.core.functions.WhoisIAm
+----------------------------
 
 .. automodule:: BAC0.core.functions.WhoisIAm
     :members:
     :undoc-members:
     :show-inheritance:
 
-BAC0.core.functions.discoverPoints module
------------------------------------------
+BAC0.core.functions.discoverPoints
+----------------------------------
 
 .. automodule:: BAC0.core.functions.discoverPoints
     :members: