Massive documentation overhaul

Author: Maxusmusti

README.md

@@ -6,8 +6,8 @@ Adds two new, simple-to-use objects:
  - SignalResponder     (for receiving state signals, locking onto publishers, and publishing responses)
 
 Also provides two dataclass specifications:
- - Signal              (state signal protocol definition)
- - Response            (response protocol definition)
+ - Signal              (state signal protocol payload definition)
+ - Response            (response protocol payload definition)
 
 Combining redis pubsub features with state signal + response protocols, 
 these additions make state signal publishing, subscribing, receiving, 
@@ -19,3 +19,17 @@ See full documentation [here](https://distributed-system-analysis.github.io/stat
 The state-signals PyPI package is available [here](https://pypi.org/project/state-signals)
 
 To install, run `pip install state-signals`
+
+# REQUIREMENTS
+The use of this module requires the existence of an accessible redis server.
+ - Redis can easily be installed with a `yum install redis` (or replace yum with package manager of choice).
+
+A redis server can be started with the `redis-server` command.
+ - The default port is 6379 (also default for state-signals), but can be changed with `--port (port)`
+ - A config file can also be used for greater control/detail `redis-server \path\to\config`
+ - Example/default config available (here)[https://download.redis.io/redis-stable/redis.conf]
+
+See https://redis.io/ for more details and usage
+
+# PROTOCOL / BEHAVIORS
+

docs/index.html

@@ -5,7 +5,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
 <meta name="generator" content="pdoc 0.10.0" />
 <title>state_signals API documentation</title>
-<meta name="description" content="" />
+<meta name="description" content="State/Event Signal Module …" />
 <link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/sanitize.min.css" integrity="sha256-PK9q560IAAa6WVRRh76LtCaI8pjTJ2z11v0miyNNjrs=" crossorigin>
 <link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/typography.min.css" integrity="sha256-7l/o7C8jubJiy74VsKTidCy1yBkRtiUGbVkYBylBqUg=" crossorigin>
 <link rel="stylesheet preload" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/github.min.css" crossorigin>
@@ -22,38 +22,60 @@
 <h1 class="title">Module <code>state_signals</code></h1>
 </header>
 <section id="section-intro">
+<p>State/Event Signal Module</p>
+<p>Adds two new, simple-to-use objects:</p>
+<ul>
+<li>SignalExporter
+(for publishing state signals and handling subscribers + responses)
+</li>
+<li>SignalResponder
+(for receiving state signals, locking onto publishers, and publishing responses)</li>
+</ul>
+<p>Also provides two dataclass specifications:</p>
+<ul>
+<li>Signal
+(state signal protocol payload definition)
+</li>
+<li>Response
+(response protocol payload definition)</li>
+</ul>
+<p>Combining redis pubsub features with state signal + response protocols,
+these additions make state signal publishing, subscribing, receiving,
+and responding incredibly easy to integrate into any code.</p>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
-<pre><code class="python">from dataclasses import dataclass
-from enum import Enum
-from typing import Any, Dict, Iterator, List, Optional, Tuple
-import redis
-import platform
-import json
-import time
-import uuid
-import logging
-
-
-&#34;&#34;&#34;
+<pre><code class="python">&#34;&#34;&#34;
 State/Event Signal Module
 
 Adds two new, simple-to-use objects:
- - SignalExporter      (for publishing state signals and handling subscribers + responses)
- - SignalResponder     (for receiving state signals, locking onto publishers, and publishing responses)
+
+   - SignalExporter      (for publishing state signals and handling subscribers + responses)  
+   - SignalResponder     (for receiving state signals, locking onto publishers, and publishing responses)
 
 Also provides two dataclass specifications:
- - Signal              (state signal protocol payload definition)
- - Response            (response protocol payload definition)
+
+   - Signal              (state signal protocol payload definition)  
+   - Response            (response protocol payload definition)
 
 Combining redis pubsub features with state signal + response protocols, 
 these additions make state signal publishing, subscribing, receiving, 
 and responding incredibly easy to integrate into any code.
 &#34;&#34;&#34;
 
 
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+import redis
+import platform
+import json
+import time
+import uuid
+import logging
+
+
 def _create_logger(
     class_name: str, process_name: str, log_level: str
 ) -&gt; logging.Logger:
@@ -77,6 +99,10 @@ <h1 class="title">Module <code>state_signals</code></h1>
 
 
 class ResultCodes(Enum):
+    &#34;&#34;&#34;
+    All potential result codes when publishing a signal. See the publish_signal
+    method under SignalExporter for more details.
+    &#34;&#34;&#34;
     ALL_SUBS_SUCCESS = 0
     SUB_FAILED = 1
     MISSING_RESPONSE = 2
@@ -198,7 +224,7 @@ <h1 class="title">Module <code>state_signals</code></h1>
         log_level: str = &#34;INFO&#34;,
     ) -&gt; None:
         &#34;&#34;&#34;
-        Sets exporter object fields and generates unique publisher_id.
+        init: Sets exporter object fields and generates unique publisher_id.
         Allows for specification of redis host/port. Also allows runner
         hostname to be inputted manually (otherwise will default to 
         platform.node() value)
@@ -334,10 +360,11 @@ <h1 class="title">Module <code>state_signals</code></h1>
         is reached (default = 20s). Returns one of the below result codes based on
         signal publish/response success.
 
-        RESULT CODES:
-        ALL_SUBS_SUCCESS = 0 = ALL SUBS RESPONDED WELL
-        SUB_FAILED = 1 = ONE OR MORE SUB RESPONDED BADLY
-        MISSING_RESPONE = 2 = NOT ALL SUBS RESPONDED
+        Result Codes:
+
+           - ALL_SUBS_SUCCESS = 0 = all subs responded well 
+           - SUB_FAILED = 1 = one or more sub responded badly  
+           - MISSING_RESPONE = 2 = not all subs responded
         &#34;&#34;&#34;
         if not isinstance(timeout, int):
             raise TypeError(&#34;&#39;timeout&#39; arg must be an int value&#34;)
@@ -437,7 +464,7 @@ <h1 class="title">Module <code>state_signals</code></h1>
         log_level=&#34;INFO&#34;,
     ) -&gt; None:
         &#34;&#34;&#34;
-        Sets exporter object fields and generates unique responder_id.
+        init: Sets responder object fields and generates unique responder_id.
         Allows for specification of redis host/port.
         &#34;&#34;&#34;
         self.logger = _create_logger(&#34;SignalResponder&#34;, responder_name, log_level)
@@ -667,12 +694,17 @@ <h3>Methods</h3>
 <span>(</span><span>value, names=None, *, module=None, qualname=None, type=None, start=1)</span>
 </code></dt>
 <dd>
-<div class="desc"><p>An enumeration.</p></div>
+<div class="desc"><p>All potential result codes when publishing a signal. See the publish_signal
+method under SignalExporter for more details.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class ResultCodes(Enum):
+    &#34;&#34;&#34;
+    All potential result codes when publishing a signal. See the publish_signal
+    method under SignalExporter for more details.
+    &#34;&#34;&#34;
     ALL_SUBS_SUCCESS = 0
     SUB_FAILED = 1
     MISSING_RESPONSE = 2</code></pre>
@@ -840,7 +872,7 @@ <h3>Methods</h3>
 Also handles subscriber recording and response reading/awaiting. Uses the standard
 signal protocol for all published messages. Easy-to-use interface for publishing
 legal signals and handling responders.</p>
-<p>Sets exporter object fields and generates unique publisher_id.
+<p>init: Sets exporter object fields and generates unique publisher_id.
 Allows for specification of redis host/port. Also allows runner
 hostname to be inputted manually (otherwise will default to
 platform.node() value)</p></div>
@@ -865,7 +897,7 @@ <h3>Methods</h3>
         log_level: str = &#34;INFO&#34;,
     ) -&gt; None:
         &#34;&#34;&#34;
-        Sets exporter object fields and generates unique publisher_id.
+        init: Sets exporter object fields and generates unique publisher_id.
         Allows for specification of redis host/port. Also allows runner
         hostname to be inputted manually (otherwise will default to 
         platform.node() value)
@@ -1001,10 +1033,11 @@ <h3>Methods</h3>
         is reached (default = 20s). Returns one of the below result codes based on
         signal publish/response success.
 
-        RESULT CODES:
-        ALL_SUBS_SUCCESS = 0 = ALL SUBS RESPONDED WELL
-        SUB_FAILED = 1 = ONE OR MORE SUB RESPONDED BADLY
-        MISSING_RESPONE = 2 = NOT ALL SUBS RESPONDED
+        Result Codes:
+
+           - ALL_SUBS_SUCCESS = 0 = all subs responded well 
+           - SUB_FAILED = 1 = one or more sub responded badly  
+           - MISSING_RESPONE = 2 = not all subs responded
         &#34;&#34;&#34;
         if not isinstance(timeout, int):
             raise TypeError(&#34;&#39;timeout&#39; arg must be an int value&#34;)
@@ -1137,10 +1170,13 @@ <h3>Methods</h3>
 subscribed responders (if any). The method will give up once the timeout period
 is reached (default = 20s). Returns one of the below result codes based on
 signal publish/response success.</p>
-<p>RESULT CODES:
-ALL_SUBS_SUCCESS = 0 = ALL SUBS RESPONDED WELL
-SUB_FAILED = 1 = ONE OR MORE SUB RESPONDED BADLY
-MISSING_RESPONE = 2 = NOT ALL SUBS RESPONDED</p></div>
+<p>Result Codes:</p>
+<ul>
+<li>ALL_SUBS_SUCCESS = 0 = all subs responded well </li>
+<li>SUB_FAILED = 1 = one or more sub responded badly
+</li>
+<li>MISSING_RESPONE = 2 = not all subs responded</li>
+</ul></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
@@ -1160,10 +1196,11 @@ <h3>Methods</h3>
     is reached (default = 20s). Returns one of the below result codes based on
     signal publish/response success.
 
-    RESULT CODES:
-    ALL_SUBS_SUCCESS = 0 = ALL SUBS RESPONDED WELL
-    SUB_FAILED = 1 = ONE OR MORE SUB RESPONDED BADLY
-    MISSING_RESPONE = 2 = NOT ALL SUBS RESPONDED
+    Result Codes:
+
+       - ALL_SUBS_SUCCESS = 0 = all subs responded well 
+       - SUB_FAILED = 1 = one or more sub responded badly  
+       - MISSING_RESPONE = 2 = not all subs responded
     &#34;&#34;&#34;
     if not isinstance(timeout, int):
         raise TypeError(&#34;&#39;timeout&#39; arg must be an int value&#34;)
@@ -1243,7 +1280,7 @@ <h3>Methods</h3>
 Can be used both for listening for signals as well as responding to them. Also
 allows for locking onto specific tags/publisher_ids. Uses the standard signal
 response protocol for all published messages.</p>
-<p>Sets exporter object fields and generates unique responder_id.
+<p>init: Sets responder object fields and generates unique responder_id.
 Allows for specification of redis host/port.</p></div>
 <details class="source">
 <summary>
@@ -1265,7 +1302,7 @@ <h3>Methods</h3>
         log_level=&#34;INFO&#34;,
     ) -&gt; None:
         &#34;&#34;&#34;
-        Sets exporter object fields and generates unique responder_id.
+        init: Sets responder object fields and generates unique responder_id.
         Allows for specification of redis host/port.
         &#34;&#34;&#34;
         self.logger = _create_logger(&#34;SignalResponder&#34;, responder_name, log_level)

state_signals.py

@@ -1,31 +1,33 @@
-from dataclasses import dataclass
-from enum import Enum
-from typing import Any, Dict, Iterator, List, Optional, Tuple
-import redis
-import platform
-import json
-import time
-import uuid
-import logging
-
-
 """
 State/Event Signal Module
 
 Adds two new, simple-to-use objects:
- - SignalExporter      (for publishing state signals and handling subscribers + responses)
- - SignalResponder     (for receiving state signals, locking onto publishers, and publishing responses)
+
+   - SignalExporter      (for publishing state signals and handling subscribers + responses)  
+   - SignalResponder     (for receiving state signals, locking onto publishers, and publishing responses)
 
 Also provides two dataclass specifications:
- - Signal              (state signal protocol payload definition)
- - Response            (response protocol payload definition)
+
+   - Signal              (state signal protocol payload definition)  
+   - Response            (response protocol payload definition)
 
 Combining redis pubsub features with state signal + response protocols, 
 these additions make state signal publishing, subscribing, receiving, 
 and responding incredibly easy to integrate into any code.
 """
 
 
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+import redis
+import platform
+import json
+import time
+import uuid
+import logging
+
+
 def _create_logger(
     class_name: str, process_name: str, log_level: str
 ) -> logging.Logger:
@@ -49,6 +51,10 @@ def _create_logger(
 
 
 class ResultCodes(Enum):
+    """
+    All potential result codes when publishing a signal. See the publish_signal
+    method under SignalExporter for more details.
+    """
     ALL_SUBS_SUCCESS = 0
     SUB_FAILED = 1
     MISSING_RESPONSE = 2
@@ -170,7 +176,7 @@ def __init__(
         log_level: str = "INFO",
     ) -> None:
         """
-        Sets exporter object fields and generates unique publisher_id.
+        init: Sets exporter object fields and generates unique publisher_id.
         Allows for specification of redis host/port. Also allows runner
         hostname to be inputted manually (otherwise will default to 
         platform.node() value)
@@ -306,10 +312,11 @@ def publish_signal(
         is reached (default = 20s). Returns one of the below result codes based on
         signal publish/response success.
 
-        RESULT CODES:
-        ALL_SUBS_SUCCESS = 0 = ALL SUBS RESPONDED WELL
-        SUB_FAILED = 1 = ONE OR MORE SUB RESPONDED BADLY
-        MISSING_RESPONE = 2 = NOT ALL SUBS RESPONDED
+        Result Codes:
+
+           - ALL_SUBS_SUCCESS = 0 = all subs responded well 
+           - SUB_FAILED = 1 = one or more sub responded badly  
+           - MISSING_RESPONE = 2 = not all subs responded
         """
         if not isinstance(timeout, int):
             raise TypeError("'timeout' arg must be an int value")
@@ -409,7 +416,7 @@ def __init__(
         log_level="INFO",
     ) -> None:
         """
-        Sets exporter object fields and generates unique responder_id.
+        init: Sets responder object fields and generates unique responder_id.
         Allows for specification of redis host/port.
         """
         self.logger = _create_logger("SignalResponder", responder_name, log_level)