Standardize structure

[Poikilos]

TLDR: PEP8 is widely used as a coding style and can help reduce diffs, make code appear more standardized and reduce the output of static analyzers so useful information can be discovered. Doing so led to some fixes either listed below or in individual commit descriptions.

The Python project itself has placed an emphasis on PEP8 (pycodestyle (formerly pep8) package helps lint that specifically), possibly since it is an interpreted language (where static analysis in general can prevent issues). I added IDE notes for highlighting in realtime (some realtime linting enabled by default in some IDEs, so conforming reduces noise).

I also started adding Google-style Sphinx docstrings (PEP8 specifies using a docstring, but Sphinx has a specific tiered formatting and Google-style provides the most specificity regarding types, returns, etc.). For example:

    def segmentAddressedDataArray(self, alias, data):
        '''Segment data into zero or more arrays
        of no more than 8 bytes, with the alias at the start of each,
        for addressed non-datagram messages.

        Args:
            alias (int): _description_
            data (_type_): _description_

        Returns:
            _type_: _description_
        '''

• some more information would be necessary for me to word this correctly in this particular method so I left some placeholders

The classes or init but not both can document arguments. Using the class is helpful to reduce work (provide only one description of what using the class does), so I prefer placing init args in the class definition:

class MemoryReadMemo :
    """Memo carries request and reply.

    Args:
        nodeID (_type_): _description_
        size (_type_): _description_
        space (_type_): _description_
        address (_type_): _description_
        rejectedReply (_type_): _description_
        dataReply (_type_): _description_
    """
    def __init__(self, nodeID, size, space, address, rejectedReply, dataReply):
        # For args see class docstring.

• The arg template above can be generated by typing """ below init if using the autoDocstring extension for VSCode or fully open-source vscodium (see updated readme), but then you can move that to the class docstring manually and type your own comment under init like above. I also usually change """ to ''' to be easier to read (odd number of marks indicates visually to me it is not closed).

You can also document which exceptions your code may raise:

        Raises:
            ValueError: _description_ [in what case, etc.]

• See a related "# TODO" for one place maybe a TypeError should be raised.

Some PEP8 issues solved:

• reduce line length to 79 (72 suggested for comments; For the VSCode "ReWrap" extension, select an area of code and press Alt+Q; I set the rewrap.wrappingColumn setting in the vscode workspace file included in the PR). Example:

      message = Message(MTI.Datagram, self.linkLayer.localNodeID,
                        memo.destID, memo.data)

  Or for literals:

              logging.warning("Could not decode header 0x{:08X}"
                              "".format(frame.header))

  Or the following format ():

  from openlcb.datagramservice import (
  DatagramService,
  DatagramWriteMemo,
  )

  (using the dangling "," is also part of PEP8 since it reduces commit diffs when something is added/removed) ...which is also useful to reduce line length when variables/literals are long:

      self.service.registerDatagramReceivedListener(
          self.datagramReceivedListener
      )

  & other various spacing changes related to PEP8.

Below are diffs for behavior changes not mentioned in commit descriptions so that reviewing the changes below can be double-checked):

-                    aliasToNodeID[destAlias] = destID
-                    nodeIdToAlias[destID] = destAlias
+                    self.aliasToNodeID[destAlias] = destID
+                    self.nodeIdToAlias[destID] = destAlias

-                logging.warning("Did not know source = {} on message send".format(source))
+                logging.warning("Did not know source = {} on message send".format(msg.source))

-        lmsg = Message(MTI.Link_Layer_Restarted, NodeID(0), None, [])
+        msg = Message(MTI.Link_Layer_Restarted, NodeID(0), None, [])
        self.fireListeners(msg)

-                if destt == None:
-                    dest = NodeID(0)
+                if destt is None:
+                    destt = NodeID(0)

and in memoryservice.py:

• Int should be int when combining dmemo.data into address.
• use of spaceLengthCallback without self.
• use of service without self.

[bobjacobsen]

Thanks! This is an amazing amount of improvement.