adding some documentation

Signed-off-by: Jesse Jaggars <jjaggars@redhat.com>

Author: jhjaggars

receptor/buffers/file.py

@@ -27,13 +27,13 @@ def __init__(self, dir_, key, loop):
             pass
         for item in self._read_manifest():
             self.q.put_nowait(item)
-    
+
     async def put(self, data):
         ident = str(uuid.uuid4())
         await self._loop.run_in_executor(pool, self._write_file, data, ident)
         await self.q.put(ident)
         await self._save_manifest()
-    
+
     async def get(self, handle_only=False, delete=True):
         while True:
             msg = await self.q.get()
@@ -42,15 +42,15 @@ async def get(self, handle_only=False, delete=True):
                 return await self._get_file(msg, handle_only=handle_only, delete=delete)
             except FileNotFoundError:
                 pass
-    
+
     async def _save_manifest(self):
         async with self._manifest_lock:
             await self._loop.run_in_executor(pool, self._write_manifest)
-    
+
     def _write_manifest(self):
         with open(self._manifest_path, "w") as fp:
             json.dump(list(self.q._queue), fp)
-    
+
     def _read_manifest(self):
         try:
             with open(self._manifest_path, "r") as fp:

receptor/messages/envelope.py

@@ -15,7 +15,7 @@
 
 class FramedMessage:
     """
-    A complete message constructed from one or more Frames.
+    A complete, two-part message.
     """
 
     __slots__ = ("msg_id", "header", "payload")
@@ -27,7 +27,6 @@ def __init__(self, msg_id=None, header=None, payload=None):
         self.header = header
         self.payload = payload
 
-
     def serialize(self):
         h = json.dumps(self.header).encode("utf-8")
         return b''.join([
@@ -39,6 +38,10 @@ def serialize(self):
 
 
 class CommandMessage(FramedMessage):
+    """
+    A complete, single part message, meant to encapsulate point to point
+    commands or naive broadcasts.
+    """
 
     def serialize(self):
         h = json.dumps(self.header).encode("utf-8")
@@ -116,6 +119,12 @@ async def get(self):
 
 
 class Frame:
+    """
+    A Frame represents the minimal metadata about a transmission.
+
+    Usually you should not create one directly, but rather use the
+    FramedMessage or CommandMessage classes.
+    """
 
     class Types(IntEnum):
         HEADER = 0
@@ -126,7 +135,6 @@ class Types(IntEnum):
 
     __slots__ = ('type', 'version', 'length', 'msg_id', 'id')
 
-
     def __init__(self, type_, version, length, msg_id, id_):
         self.type = type_
         self.version = version
@@ -164,10 +172,12 @@ def wrap(cls, data, type_=Types.PAYLOAD, msg_id=None):
 
 
 def split_uuid(data):
+    "Splits a 128 bit int into two 64 bit words for binary encoding"
     return ((data >> 64) & MAX_INT64, data & MAX_INT64)
 
 
 def join_uuid(hi, lo):
+    "Joins two 64 bit words into a 128bit int from binary encoding"
     return (hi << 64) | lo