From dd2b0b89af565a26e2842c648a69e7957324aad4 Mon Sep 17 00:00:00 2001
From: Lee Miller <lee.miller@tutanota.com>
Date: Sat, 12 Aug 2023 03:34:20 +0300
Subject: [PATCH] Improve docstrings in message and structure and add more

---
 minode/message.py   | 14 +++++++++-----
 minode/structure.py |  8 +++++++-
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/minode/message.py b/minode/message.py
index f3d1b4d..c30114c 100644
--- a/minode/message.py
+++ b/minode/message.py
@@ -9,7 +9,7 @@ from . import shared, structure
 
 
 class Header():
-    """Common message header"""
+    """Message header structure"""
     def __init__(self, command, payload_length, payload_checksum):
         self.command = command
         self.payload_length = payload_length
@@ -24,6 +24,7 @@ class Header():
             base64.b16encode(self.payload_checksum).decode())
 
     def to_bytes(self):
+        """Serialize to bytes"""
         b = b''
         b += shared.magic_bytes
         b += self.command.ljust(12, b'\x00')
@@ -33,6 +34,7 @@ class Header():
 
     @classmethod
     def from_bytes(cls, b):
+        """Parse from bytes"""
         magic_bytes, command, payload_length, payload_checksum = struct.unpack(
             '>4s12sL4s', b)
 
@@ -59,6 +61,7 @@ class Message():
             base64.b16encode(self.payload_checksum).decode())
 
     def to_bytes(self):
+        """Serialize to bytes"""
         b = Header(
             self.command, self.payload_length, self.payload_checksum
         ).to_bytes()
@@ -67,6 +70,7 @@ class Message():
 
     @classmethod
     def from_bytes(cls, b):
+        """Parse from bytes"""
         h = Header.from_bytes(b[:24])
 
         payload = b[24:]
@@ -88,7 +92,7 @@ class Message():
 
 
 class Version():
-    """The version message"""
+    """The version message payload"""
     def __init__(
         self, host, port, protocol_version=shared.protocol_version,
         services=shared.services, nonce=shared.nonce,
@@ -159,7 +163,7 @@ class Version():
 
 
 class Inv():
-    """The inv message"""
+    """The inv message payload"""
     def __init__(self, vectors):
         self.vectors = set(vectors)
 
@@ -195,7 +199,7 @@ class Inv():
 
 
 class GetData():
-    """The getdata message"""
+    """The getdata message payload"""
     def __init__(self, vectors):
         self.vectors = set(vectors)
 
@@ -231,7 +235,7 @@ class GetData():
 
 
 class Addr():
-    """The addr message"""
+    """The addr message payload"""
     def __init__(self, addresses):
         self.addresses = addresses
 
diff --git a/minode/structure.py b/minode/structure.py
index 024ea9a..d2352fa 100644
--- a/minode/structure.py
+++ b/minode/structure.py
@@ -46,7 +46,7 @@ class VarInt():
 
 
 class Object():
-    """object message"""
+    """The 'object' message payload"""
     def __init__(
         self, nonce, expires_time, object_type, version,
         stream_number, object_payload
@@ -66,6 +66,7 @@ class Object():
 
     @classmethod
     def from_message(cls, m):
+        """Decode message payload"""
         payload = m.payload
         nonce, expires_time, object_type = struct.unpack('>8sQL', payload[:20])
         payload = payload[20:]
@@ -80,6 +81,7 @@ class Object():
             nonce, expires_time, object_type, version, stream_number, payload)
 
     def to_bytes(self):
+        """Serialize to bytes"""
         payload = b''
         payload += self.nonce
         payload += struct.pack('>QL', self.expires_time, self.object_type)
@@ -90,9 +92,11 @@ class Object():
         return payload
 
     def is_expired(self):
+        """Check if object's TTL is expired"""
         return self.expires_time + 3 * 3600 < time.time()
 
     def is_valid(self):
+        """Checks the object validity"""
         if self.is_expired():
             logging.debug(
                 'Invalid object %s, reason: expired',
@@ -129,6 +133,7 @@ class Object():
         return True
 
     def pow_target(self):
+        """Compute PoW target"""
         data = self.to_bytes()[8:]
         length = len(data) + 8 + shared.payload_length_extra_bytes
         dt = max(self.expires_time - time.time(), 0)
@@ -138,6 +143,7 @@ class Object():
                     length + (dt * length) / (2 ** 16))))
 
     def pow_initial_hash(self):
+        """Compute the initial hash for PoW"""
         return hashlib.sha512(self.to_bytes()[8:]).digest()