Cli (#4)

* NEW: Restructured github actions

---------

Co-authored-by: Lewis Chambers <[email protected]>

.github/workflows/static.yml → .github/workflows/doc-deployment.yml

@@ -4,7 +4,8 @@ name: Deploy static content to Pages
 on:
   # Runs on pushes targeting the default branch
   workflow_run:
-      workflows: ["Python Tests"]
+      workflows: ["Test Package"]
+      branches: ["main"]
       types:
           - completed
 

.github/workflows/doc-test.yml

@@ -0,0 +1,28 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Build Documentation
+
+on: [workflow_call]
+
+permissions:
+  contents: read
+
+jobs:  
+  test_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[docs]
+      - name: Build Docs
+        run: |
+          python -c "import iotdevicesimulator; print(iotdevicesimulator.__version__)"
+          pushd docs
+          . ./make.sh build

.github/workflows/test-pipeline.yml

@@ -0,0 +1,12 @@
+name: Test Package
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    uses: ./.github/workflows/test.yml
+  docs:
+    uses: ./.github/workflows/doc-test.yml

.github/workflows/test.yml

@@ -3,7 +3,7 @@
 
 name: Python Tests
 
-on: [push, pull_request]
+on: [workflow_call]
 
 permissions:
   contents: read
@@ -31,4 +31,4 @@ jobs:
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Test with pytest
-      run: pytest -m "not oracle"
+      run: pytest -m "not oracle"

docs/index.rst

@@ -129,7 +129,7 @@ To create an IoT Swarm you must write a script such as the following:
          CosmosQuery.LEVEL_1_SOILMET_30MIN,
          mqtt_connection,
          swarm_name="soilmet",
-         delay_first_cycle=True,
+         delay_start=True,
          max_cycles=5,
          max_sites=5,
          sleep_time=30,

pyproject.toml

@@ -21,7 +21,7 @@ description = "Package for simulating a net of IoT devices for stress testing."
 
 [project.optional-dependencies]
 test = ["pytest", "pytest-cov", "pytest-asyncio", "parameterized"]
-docs = ["sphinx", "sphinx-copybutton", "sphinx-rtd-theme"]
+docs = ["sphinx", "sphinx-copybutton", "sphinx-rtd-theme", "sphinx-click"]
 
 [project.scripts]
 iot-swarm = "iotdevicesimulator.scripts.cli:main"

src/iotdevicesimulator/devices.py

@@ -16,7 +16,7 @@ class SensorSite:
         sleep_time: Time to sleep between requests (seconds).
         max_cycles: Maximum number of cycles before shutdown.
         inherit_logger: Override for the module logger.
-        delay_first_cycle: Adds a random delay to first invocation from 0 - `sleep_time`.
+        delay_start: Adds a random delay to first invocation from 0 - `sleep_time`.
         topic_prefix: Prefixes the sensor topic.
     """
 
@@ -32,7 +32,7 @@ class SensorSite:
     site_id: str
     """ID of the site."""
 
-    delay_first_cycle: bool = False
+    delay_start: bool = False
     """Adds a random delay to first invocation from 0 - `sleep_time`."""
 
     _instance_logger: logging.Logger
@@ -58,7 +58,7 @@ def topic(self, query):
 
     def __init__(self, site_id: str,*, sleep_time: int|None=None,
                  max_cycles: int|None=None, inherit_logger:logging.Logger|None=None,
-                 delay_first_cycle:bool|None=None, topic_prefix: str|None=None) -> None:
+                 delay_start:bool|None=None, topic_prefix: str|None=None) -> None:
 
         self.site_id = str(site_id)
 
@@ -81,13 +81,16 @@ def __init__(self, site_id: str,*, sleep_time: int|None=None,
 
             self.sleep_time = sleep_time
 
-        if delay_first_cycle is not None:
-            if not isinstance(delay_first_cycle, bool):
+        if delay_start is not None:
+            if not isinstance(delay_start, bool):
                 raise TypeError(
-                    f"`delay_first_cycle` must be a bool. Received: {delay_first_cycle}."
+                    f"`delay_start` must be a bool. Received: {delay_start}."
                 )
 
-            self.delay_first_cycle = delay_first_cycle
+            self.delay_start = delay_start
+
+        if topic_prefix is not None:
+            self.topic_prefix = str(topic_prefix)
 
         if topic_prefix is not None:
             self.topic_prefix = str(topic_prefix)
@@ -113,7 +116,7 @@ async def run(self, oracle: Oracle, query: CosmosQuery,
         self.topic = query.name
         while True:
 
-            if self.delay_first_cycle and self.cycle == 0:
+            if self.delay_start and self.cycle == 0:
                 delay = random.randint(0, self.sleep_time)
                 self._instance_logger.debug(f"Delaying first cycle for: {delay}s")
                 await asyncio.sleep(delay)

src/iotdevicesimulator/example.py

@@ -36,7 +36,7 @@ async def main(config_path: str):
         mqtt_connection,
         oracle_config,
         swarm_name="soilmet",
-        delay_first_cycle=True,
+        delay_start=True,
         max_cycles=5,
         max_sites=5,
         sleep_time=30,

src/iotdevicesimulator/swarm.py

@@ -46,7 +46,7 @@ class CosmosSwarm:
     sites: List[SensorSite]
     """List of site objects."""
 
-    delay_first_cycle: bool = False
+    delay_start: bool = False
     """Adds a random delay to first invocation from 0 - `sleep_time`."""
 
     oracle: Oracle
@@ -69,7 +69,7 @@ def __repr__(self):
         return (
             f"CosmosSwarm({type(self.query)}, {self.message_connection}, site_ids={[x.site_id for x in self.sites]}"
             f", sleep_time={self.sleep_time}, max_cycles={self.max_cycles}, max_sites={self.max_sites}"
-            f', swarm_name="{self.swarm_name}", delay_first_cycle={self.delay_first_cycle}{topic_prefix})'
+            f', swarm_name="{self.swarm_name}", delay_start={self.delay_start}{topic_prefix})'
         )
 
     def __str__(self):
@@ -78,7 +78,7 @@ def __str__(self):
         )
         return (
             f'CosmosSwarm({self.query.__class__.__name__}.{self.query.name}, swarm_name="{self.swarm_name}"'
-            f"{topic_prefix}, sleep_time={self.sleep_time}, max_cycles={self.max_cycles}, delay_start={self.delay_first_cycle})"
+            f"{topic_prefix}, sleep_time={self.sleep_time}, max_cycles={self.max_cycles}, delay_start={self.delay_start})"
         )
 
     @classmethod
@@ -92,7 +92,7 @@ async def create(
         max_cycles: int | None = None,
         max_sites: int | None = None,
         swarm_name: str | None = None,
-        delay_first_cycle: bool | None = None,
+        delay_start: bool | None = None,
         topic_prefix: str | None = None,
     ) -> None:
         """Factory method for initialising the class.
@@ -106,7 +106,7 @@ async def create(
             max_cycles: Maximum number of data sending cycles.
             max_sites: Maximum number of sites to initialise.
             swarm_name: Name / ID given to swarm.
-            delay_first_cycle: Adds a random delay to first invocation from 0 - `sleep_time`.
+            delay_start: Adds a random delay to first invocation from 0 - `sleep_time`.
             topic_prefix: Prefixes the sensor topic.
         """
         self = cls()
@@ -164,12 +164,12 @@ async def create(
                 )
             self.max_sites = max_sites
 
-        if delay_first_cycle is not None:
-            if not isinstance(delay_first_cycle, bool):
+        if delay_start is not None:
+            if not isinstance(delay_start, bool):
                 raise TypeError(
-                    f"`delay_first_cycle` must be a bool. Received: {delay_first_cycle}."
+                    f"`delay_start` must be a bool. Received: {delay_start}."
                 )
-            self.delay_first_cycle = delay_first_cycle
+            self.delay_start = delay_start
 
         if topic_prefix is not None:
             self.topic_prefix = str(topic_prefix)
@@ -189,7 +189,7 @@ async def create(
             max_cycles=self.max_cycles,
             max_sites=self.max_sites,
             swarm_logger=self._instance_logger,
-            delay_first_cycle=self.delay_first_cycle,
+            delay_start=self.delay_start,
             topic_prefix=self.topic_prefix,
         )
 
@@ -256,7 +256,7 @@ def _init_sites(
         max_cycles: int = 3,
         max_sites: int = 0,
         swarm_logger: logging.Logger | None = None,
-        delay_first_cycle: bool = False,
+        delay_start: bool = False,
         topic_prefix: str | None = None,
     ):
         """Initialises a list of SensorSites.
@@ -267,7 +267,7 @@ def _init_sites(
             max_cycles: Maximum number of data sending cycles.
             max_sites: Maximum number of sites to initialise. Picks randomly from list if given
             swarm_logger: Passes the instance logger to sites
-            delay_first_cycle: Adds a random delay to first invocation from 0 - `sleep_time`.
+            delay_start: Adds a random delay to first invocation from 0 - `sleep_time`.
             topic_prefix: Prefixes the sensor topic.
 
         Returns:
@@ -282,7 +282,7 @@ def _init_sites(
                 sleep_time=sleep_time,
                 max_cycles=max_cycles,
                 inherit_logger=swarm_logger,
-                delay_first_cycle=delay_first_cycle,
+                delay_start=delay_start,
                 topic_prefix=topic_prefix,
             )
             for site_id in site_ids

src/tests/test_swarm.py

@@ -83,20 +83,20 @@ async def test_delay_set(self):
             MockMessageConnection(),
             self.config,
             site_ids="MORLY",
-            delay_first_cycle=True,
+            delay_start=True,
         )
 
-        self.assertTrue(swarm.delay_first_cycle)
+        self.assertTrue(swarm.delay_start)
 
         swarm = await CosmosSwarm.create(
             query,
             MockMessageConnection(),
             self.config,
             site_ids="MORLY",
-            delay_first_cycle=False,
+            delay_start=False,
         )
 
-        self.assertFalse(swarm.delay_first_cycle)
+        self.assertFalse(swarm.delay_start)
 
     @pytest.mark.asyncio
     @config_exists
@@ -110,7 +110,7 @@ async def test_error_if_delay_set_not_bool(self):
                 MockMessageConnection(),
                 self.config,
                 site_ids="MORLY",
-                delay_first_cycle=4,
+                delay_start=4,
             )
 
     @pytest.mark.asyncio