tweak Source to have a defined setup method for easier simple usecases (#783)

Author: tim-quix

docs/connectors/sources/README.md

@@ -136,10 +136,10 @@ if __name__ == "__main__":
 
 ## Connection Callbacks
 
-Assuming a given connector is set up to utilize them, there are two callbacks that can 
-be set for when a client connects/authenticates successfully or not, named 
-`on_client_connect_success` and `on_client_connect_failure`, respectfully.
+Assuming a given connector has a proper `setup` method to utilize them, there are two 
+callbacks that can be set for when a client connects/authenticates successfully or not, 
+named `on_client_connect_success` and `on_client_connect_failure`, respectfully.
 
-Though having a `setup` method is required, it is not guaranteed that it is implemented or
-utilized fully with `community` sources; you can inspect a given Source's `setup` method 
+Though implementing an applicable `setup` method is strongly encouraged, it is not an
+enforced guarantee with `community` sources; you can inspect a given Source's `setup` method 
 to confirm whether it tests the client connection there (and that the callbacks are then applicable).

docs/connectors/sources/custom-sources.md

@@ -13,19 +13,16 @@ The recommended parent class to create a new source. It handles configuring, sta
 To get started, implement the [`run`](../../api-reference/sources.md#sourcerun) method 
 which loops while `self.running` is `True` (or until it's done).
 
-When you also have a client pattern, it is recommended to use the required `setup` 
-method to establish the initial connection/authentication so that the built-in callbacks 
-of `on_client_connect_success` and `on_client_connect_failure` can be utilized. 
-Otherwise, just set it to return.
+>**NOTE**: With client-based sources, it is recommended to also implement the `setup` 
+method for establishing initial connection/authentication so that the built-in callbacks 
+of `on_client_connect_success` and `on_client_connect_failure` can be utilized.
 
 Example subclass:
 
 ```python
 from quixstreams.sources.base import Source
 
 class MySource(Source):
-    def setup(self):
-        return
 
     def run(self):
         with open("file.txt", "r") as f:

docs/tutorials/anomaly-detection/tutorial_app.py

@@ -50,9 +50,6 @@ def __init__(self):
         }
         super().__init__(name="temperature-event-generator")
 
-    def setup(self):
-        return
-
     def update_machine_temp(self, machine_id):
         """
         Updates the temperature for a machine by -1, 0, or 1 based on its current temp.

docs/tutorials/purchase-filtering/tutorial_app.py

@@ -66,9 +66,6 @@ class PurchaseGenerator(Source):
     def __init__(self):
         super().__init__(name="customer-purchases")
 
-    def setup(self):
-        return
-
     def run(self):
         for cid, purchase_info in enumerate(self._purchases_data):
             event = self.serialize(key=f"CUSTOMER_ID{cid}", value=purchase_info)

docs/tutorials/websocket-source/tutorial_app.py

@@ -36,9 +36,6 @@ def __init__(
         self._url = url
         self._product_ids = product_ids
 
-    def setup(self):
-        return
-
     def run(self) -> None:
         """
         The main method of the source with the main logic.

docs/tutorials/word-count/tutorial_app.py

@@ -27,9 +27,6 @@ class ReviewGenerator(Source):
     def __init__(self):
         super().__init__(name="customer-reviews")
 
-    def setup(self):
-        return
-
     def run(self):
         for review in self._review_list:
             event = self.serialize(key=choice(self._product_list), value=review)

quixstreams/sources/base/source.py

@@ -256,6 +256,13 @@ def running(self) -> bool:
         """
         return self._running
 
+    def setup(self):
+        """
+        Though implemented for the sake of making simple sources easier to use,
+        it is still recommended to override this when using a client-based pattern.
+        """
+        return
+
     def cleanup(self, failed: bool) -> None:
         """
         This method is triggered once the `run` method completes.