mooring-data-generator 0.9.0__tar.gz

mooring_data_generator-0.9.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.3
+Name: mooring-data-generator
+Version: 0.9.0
+Summary: Random-data generator to simulate fictional port data flows for use at a Hackathon
+Author: Ben Fitzhardinge
+Author-email: Ben Fitzhardinge <ben@benjamin.dog>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing :: Traffic Generation
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic>=2.8
+Maintainer: Ben Fitzhardinge
+Maintainer-email: Ben Fitzhardinge <ben@benjamin.dog>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Mooring Data Generator
+
+A simple script to generate fake mooring data for use in a hackathon.
+This script will send data payloads to and endpoint to simulate the data which might exist.
+
+These will be http POST queries to the url provided as an argument at run time.
+
+The script will run forever until the user sends a Ctrl+C command to end the script.
+
+## Usage
+
+### With UV (recommended)
+
+If you don't have UV on your system, read [the install instructions for UV](https://docs.astral.sh/uv/getting-started/installation/)
+
+```shell
+uvx mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+[//]: # (TODO: this needs to be confirmed after we release the package to PyPI)
+
+> [!IMPORTANT]
+> replace `http://127.0.0.1:8000/my/endpoint/` with the appropriate url for your system
+
+### Vanilla python (If you don't want UV)
+
+#### Install the package
+
+```shell
+pip install -U mooring-data-generator
+```
+
+### Running the package
+
+```shell
+mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+> [!IMPORTANT]
+> replace `http://127.0.0.1:8000/my/endpoint/` with the appropriate url for your system
+
+## Testing data is being sent
+
+There's a helper application included in this package
+to allow you to check that the data is being sent.
+
+`mooring-data-receiver` will display to the console all http traffic it receives.
+
+```shell
+mooring-data-receiver
+```
+
+By default it will run listening to any traffic `0.0.0.0` on port `8000`
+
+You can adjust this if needed by using a commend like
+
+```shell
+mooring-data-receiver --host 127.0.0.1 --port 5000
+```
+
+## Troubleshooting
+
+### Command not found
+
+If you are having trouble with the command not being found,
+you can attempt to run it as a module calling python
+
+```shell
+python -m mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+### Pip not found
+
+If `pip` can't be found on your system.
+
+First, make sure you have Python installed.
+
+```shell
+python --version
+```
+
+you can call `pip` from python directly as a module.
+
+```shell
+python -m pip install -U mooring-data-generator
+```
+
+## Release a new version
+
+### Be sure the tests pass
+
+```shell
+uv run ruff format
+uv run ruff check
+uv run tox
+```
+
+### bump version and tag new release
+
+```shell
+uv version --bump minor
+git commit -am "Release version v$(uv version --short)"
+git tag -a "v$(uv version --short)" -m "v$(uv version --short)"
+```
+
+### push to github
+
+```shell
+git push
+git push --tags
+```

mooring_data_generator-0.9.0/README.md

@@ -0,0 +1,111 @@
+# Mooring Data Generator
+
+A simple script to generate fake mooring data for use in a hackathon.
+This script will send data payloads to and endpoint to simulate the data which might exist.
+
+These will be http POST queries to the url provided as an argument at run time.
+
+The script will run forever until the user sends a Ctrl+C command to end the script.
+
+## Usage
+
+### With UV (recommended)
+
+If you don't have UV on your system, read [the install instructions for UV](https://docs.astral.sh/uv/getting-started/installation/)
+
+```shell
+uvx mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+[//]: # (TODO: this needs to be confirmed after we release the package to PyPI)
+
+> [!IMPORTANT]
+> replace `http://127.0.0.1:8000/my/endpoint/` with the appropriate url for your system
+
+### Vanilla python (If you don't want UV)
+
+#### Install the package
+
+```shell
+pip install -U mooring-data-generator
+```
+
+### Running the package
+
+```shell
+mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+> [!IMPORTANT]
+> replace `http://127.0.0.1:8000/my/endpoint/` with the appropriate url for your system
+
+## Testing data is being sent
+
+There's a helper application included in this package
+to allow you to check that the data is being sent.
+
+`mooring-data-receiver` will display to the console all http traffic it receives.
+
+```shell
+mooring-data-receiver
+```
+
+By default it will run listening to any traffic `0.0.0.0` on port `8000`
+
+You can adjust this if needed by using a commend like
+
+```shell
+mooring-data-receiver --host 127.0.0.1 --port 5000
+```
+
+## Troubleshooting
+
+### Command not found
+
+If you are having trouble with the command not being found,
+you can attempt to run it as a module calling python
+
+```shell
+python -m mooring-data-generator http://127.0.0.1:8000/my/endpoint/
+```
+
+### Pip not found
+
+If `pip` can't be found on your system.
+
+First, make sure you have Python installed.
+
+```shell
+python --version
+```
+
+you can call `pip` from python directly as a module.
+
+```shell
+python -m pip install -U mooring-data-generator
+```
+
+## Release a new version
+
+### Be sure the tests pass
+
+```shell
+uv run ruff format
+uv run ruff check
+uv run tox
+```
+
+### bump version and tag new release
+
+```shell
+uv version --bump minor
+git commit -am "Release version v$(uv version --short)"
+git tag -a "v$(uv version --short)" -m "v$(uv version --short)"
+```
+
+### push to github
+
+```shell
+git push
+git push --tags
+```

mooring_data_generator-0.9.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "mooring-data-generator"
+version = "0.9.0"
+description = "Random-data generator to simulate fictional port data flows for use at a Hackathon"
+authors = [
+  {name = "Ben Fitzhardinge", email = "ben@benjamin.dog"},
+]
+maintainers = [
+  {name = "Ben Fitzhardinge", email = "ben@benjamin.dog"}
+]
+classifiers = [
+  # How mature is this project? Common values are
+  #   3 - Alpha
+  #   4 - Beta
+  #   5 - Production/Stable
+  "Development Status :: 4 - Beta",
+  # Indicate who your project is intended for
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Testing :: Traffic Generation",
+  # Specify the Python versions you support here.
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.8",
+]
+
+[project.scripts]
+mooring-data-generator = "mooring_data_generator.cli:main"
+mooring-data-receiver = "mooring_data_receiver.http_server:cli"
+
+[dependency-groups]
+dev = [
+    "pytest~=8.4",
+]
+test = [
+    "ruff>=0.14.4",
+    "tox~=4.32",
+    "tox-uv>=1.20.0",
+]
+build = [
+    "uv-build~=0.9",
+]
+
+# UV Build tooling
+[build-system]
+requires = ["uv_build>=0.9"]
+build-backend = "uv_build"
+
+# RUFF settings
+[tool.ruff]
+target-version = "py313"
+line-length = 99
+
+[tool.ruff.lint]
+select = [
+    "C",  # mccabe rules
+    "F",  # pyflakes rules
+    "E",  # pycodestyle error rules
+    "W",  # pycodestyle warning rules
+    "B",  # flake8-bugbear rules
+    "I",  # isort rules
+]
+ignore = [
+    # "C901",  # max-complexity-10
+    "E501",  # line-too-long
+]
+
+# Rumdl settings
+# This is a tool for formatting markdown files, it can be used to fix issues automatically.
+[tool.rumdl]
+line-length = 100

mooring_data_generator-0.9.0/src/mooring_data_generator/builder.py

@@ -0,0 +1,340 @@
+import json
+import logging
+import random
+from math import ceil
+
+from .models import BentData, BerthData, HookData, PortData, RadarData, ShipData
+
+logger = logging.getLogger(__name__)
+
+# A list of well-known Western Australian port names
+WA_PORT_NAMES: list[str] = [
+    "Port Hedland",
+    "Dampier",
+    "Fremantle",
+    "Kwinana",
+    "Bunbury",
+    "Esperance",
+    "Albany",
+    "Geraldton",
+    "Broome",
+    "Wyndham",
+    "Derby",
+    "Carnarvon",
+]
+
+
+NAUTICAL_SUPERLATIVES: list[str] = [
+    "Majestic",
+    "Sovereign",
+    "Resolute",
+    "Valiant",
+    "Vigilant",
+    "Dauntless",
+    "Liberty",
+    "Enduring",
+    "Gallant",
+    "Noble",
+    "Guardian",
+    "Intrepid",
+    "Courageous",
+    "Steadfast",
+    "Regal",
+    "Stalwart",
+    "Indomitable",
+    "Invincible",
+    "Triumphant",
+    "Victorious",
+    "Glorious",
+    "Fearless",
+    "Mighty",
+    "Bold",
+    "Brave",
+    "Formidable",
+    "Relentless",
+    "Valorous",
+    "Audacious",
+    "Diligent",
+    "Implacable",
+    "Indefatigable",
+    "Prosperous",
+    "Seaborne",
+    "Seagoing",
+    "Oceanic",
+    "Maritime",
+    "Coastal",
+    "Pelagic",
+    "Windward",
+    "Leeward",
+    "Tempestuous",
+    "Sturdy",
+]
+
+NAUTICAL_BASE_NAMES: list[str] = [
+    # Western
+    "Amelia",
+    "Charlotte",
+    "Olivia",
+    "Sophia",
+    "Emily",
+    "Grace",
+    # East Asian
+    "Hana",
+    "Mei",
+    "Yuna",
+    "Sakura",
+    "Aiko",
+    "Keiko",
+    # South Asian
+    "Asha",
+    "Priya",
+    "Anika",
+    "Riya",
+    "Sana",
+    "Neha",
+    # Southeast Asian
+    "Linh",
+    "Thao",
+    "Trang",
+    "Ngoc",
+    "Anh",
+    "Nicha",
+    # Latin (Spanish/Portuguese/LatAm)
+    "Camila",
+    "Valentina",
+    "Isabela",
+    "Gabriela",
+    "Lucia",
+    "Paula",
+]
+
+
+BENT_NAMES: list[str] = [f"BNT{x:03d}" for x in range(1, 999)]
+
+SHIP_IDS: list[str] = [f"{x:04d}" for x in range(1, 9999)]
+
+
+MEAN_TENSIONS = 6
+STDEV_TENSIONS = 5
+MEAN_DISTANCES = 9.38
+STDEV_DISTANCES = 6.73
+MEAN_CHANGES = 0.68
+STDEV_CHANGES = 2.6
+
+BENT_COUNT_MIN = 9
+BENT_COUNT_MAX = 15
+
+HOOK_COUNT_MULTIPLIER = 3
+
+
+def random_single_use_choice(list_of_strings: list[str]) -> str:
+    """Source a one-time random string from a list of strings"""
+    random_str = random.choice(list_of_strings)
+    list_of_strings.remove(random_str)
+    return random_str
+
+
+def random_ship_name() -> str:
+    """Generate a random ship name by combining a nautical superlative with a potential ship name.
+
+    The format will be "<Superlative> <Name>". Example: "Majestic Amelia" or "Valiant Sophia".
+    """
+    global NAUTICAL_SUPERLATIVES
+    global NAUTICAL_BASE_NAMES
+    return f"{random_single_use_choice(NAUTICAL_SUPERLATIVES)} {random_single_use_choice(NAUTICAL_BASE_NAMES)}"
+
+
+def random_wa_port_name() -> str:
+    """Return a random Western Australian port name.
+    Preventing the option from being selected in the future."""
+    global WA_PORT_NAMES
+    return random_single_use_choice(WA_PORT_NAMES)
+
+
+def random_bent_name() -> str:
+    """Return a random bent name."""
+    global BENT_NAMES
+    return random_single_use_choice(BENT_NAMES)
+
+
+def generate_ship() -> ShipData:
+    """Generate a ship data instance with unique random name and unique id"""
+    global SHIP_IDS
+    return ShipData(
+        name=random_ship_name(),
+        vessel_id=random_single_use_choice(SHIP_IDS),
+    )
+
+
+class HookWorker:
+    """a worker class for generating and managing changes in Hook data."""
+
+    def __init__(self, hook_number: int, attached_line: str):
+        self.name: str = f"Hook {hook_number}"
+        self.active: bool = random.choice([True, False, False])
+        # a 5% change of being in fault state
+        self.fault: bool = random.choices([True, False], weights=[0.05, 0.95])[0]
+        self.attached_line = None
+        self.tension = None
+        if self.active:
+            self.attached_line = attached_line
+            self.update()
+
+    def update(self):
+        if self.active:
+            self.tension = abs(ceil(random.gauss(MEAN_CHANGES, STDEV_CHANGES)))
+
+    @property
+    def data(self) -> HookData:
+        # noinspection PyTypeChecker
+        return HookData(
+            name=self.name,
+            tension=self.tension,
+            faulted=self.fault,
+            attached_line=self.attached_line,
+        )
+
+
+class BentWorker:
+    """a worker class for managing bents and cascading data"""
+
+    def __init__(self, bent_number: int, total_bents: int):
+        self.bent_number: int = bent_number
+        self.name = random_bent_name()
+        self.hooks: list[HookWorker] = []
+        bent_position = bent_number / total_bents
+        if bent_position < 0.2:
+            attached_line = "HEAD"
+        elif 0.8 < bent_position:
+            attached_line = "STERN"
+        elif 0.4 < bent_position < 0.6:
+            attached_line = "BREAST"
+        else:
+            attached_line = "SPRING"
+        hook_count_start: int = (
+            (self.bent_number * HOOK_COUNT_MULTIPLIER) - HOOK_COUNT_MULTIPLIER + 1
+        )
+        for hook_number in range(hook_count_start, hook_count_start + HOOK_COUNT_MULTIPLIER):
+            self.hooks.append(HookWorker(hook_number, attached_line=attached_line))
+
+    def update(self):
+        """update the bent and cascading data"""
+        for hook in self.hooks:
+            hook.update()
+
+    @property
+    def data(self) -> BentData:
+        return BentData(
+            name=self.name,
+            hooks=[hook.data for hook in self.hooks],
+        )
+
+
+class RadarWorker:
+    """a worker class for generating and managing changes in Radar data."""
+
+    def __init__(self, name: str):
+        self.name: str = name
+        self.active: bool = random.choice([True, False, False])
+        self.distance: float | None = None
+        self.change: float | None = None
+        if self.active:
+            self.distance: float = abs(random.gauss(MEAN_DISTANCES, STDEV_DISTANCES))
+            self.change: float = abs(random.gauss(MEAN_CHANGES, STDEV_CHANGES))
+
+    def update(self) -> tuple[float, float]:
+        if self.active:
+            new_distance: float = abs(random.gauss(MEAN_TENSIONS, STDEV_TENSIONS))
+            new_change: float = abs(self.distance - new_distance)
+            self.distance = new_distance
+            self.change = new_change
+        return self.distance, self.change
+
+    @property
+    def data(self) -> RadarData:
+        # noinspection PyTypeChecker
+        return RadarData(
+            name=self.name,
+            ship_distance=self.distance,
+            distance_change=self.change,
+            distance_status="ACTIVE" if self.active else "INACTIVE",
+        )
+
+
+class BerthWorker:
+    """a worker class for generating and managing changes in Berth data."""
+
+    def __init__(self, berth_code: str):
+        self.berth_code: str = berth_code
+        self.bent_count: int = random.randint(BENT_COUNT_MIN, BENT_COUNT_MAX)
+        self.hook_count: int = self.bent_count * HOOK_COUNT_MULTIPLIER
+        self.ship: ShipData = generate_ship()
+        self.radars: list[RadarWorker] = []
+        for radar_num in range(1, random.choice([5, 6, 6, 6]) + 1):
+            radar_name = f"B{berth_code}RD{radar_num}"
+            self.radars.append(RadarWorker(radar_name))
+
+        self.bents: list[BentWorker] = []
+        for bent_num in range(1, self.bent_count + 1):
+            self.bents.append(BentWorker(bent_num, self.bent_count))
+
+    @property
+    def name(self) -> str:
+        return f"Berth {self.berth_code}"
+
+    def update(self):
+        for radar in self.radars:
+            radar.update()
+        for bent in self.bents:
+            bent.update()
+
+    @property
+    def data(self) -> BerthData:
+        return BerthData(
+            name=self.name,
+            bent_count=self.bent_count,
+            hook_count=self.hook_count,
+            ship=self.ship,
+            radars=[radar.data for radar in self.radars],
+            bents=[bent.data for bent in self.bents],
+        )
+
+
+class PortWorker:
+    """a worker class for generating and managing change of ports"""
+
+    def __init__(self):
+        self.name: str = random_wa_port_name()
+        self.berth_count: int = random.randint(1, 8)
+        self.berths: list[BerthWorker] = []
+        for berth_num in range(1, self.berth_count + 1):
+            berth_code: str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[berth_num]
+            self.berths.append(BerthWorker(berth_code))
+
+    def update(self):
+        for berth in self.berths:
+            berth.update()
+
+    @property
+    def data(self) -> PortData:
+        return PortData(
+            name=self.name,
+            berths=[berth.data for berth in self.berths],
+        )
+
+
+def build_random_port() -> PortWorker:
+    """Construct a `PortData` instance with a random WA port name."""
+    return PortWorker()
+
+
+def main() -> None:
+    """Generate a single random WA port and print it as JSON."""
+    port = build_random_port()
+    # Use Pydantic's by_alias to apply PascalCase field names from BasePayloadModel
+    payload = port.data.model_dump(by_alias=True)
+    logger.info(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

mooring_data_generator-0.9.0/src/mooring_data_generator/cli.py

@@ -0,0 +1,25 @@
+import argparse
+import logging
+
+from .http_worker import run
+
+logger = logging.getLogger(__name__)
+
+parser = argparse.ArgumentParser(description="Mooring data generator")
+parser.add_argument("url")
+
+
+def main() -> None:
+    """Run the cli tooling for mooring data generator"""
+    args = parser.parse_args()
+    url: str = args.url
+
+    # build a random structure for this port
+    logger.info(f"Starting mooring data generator and will HTTP POST to {url}")
+    print(f"Starting mooring data generator and will HTTP POST to {url}")
+    print("Press CTRL+C to stop mooring data generator.")
+    run(url)
+
+
+if __name__ == "__main__":
+    main()

mooring_data_generator-0.9.0/src/mooring_data_generator/http_worker.py

@@ -0,0 +1,69 @@
+import json
+import logging
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from .builder import build_random_port
+
+logger = logging.getLogger(__name__)
+
+
+def run(url: str) -> None:
+    """Continuously POST generated port data to the given URL every 2 seconds.
+
+    - Builds a random port via builder.build_random_port(), store in variable `port`.
+    - Forever loop until interrupted (Ctrl+C):
+        - Send JSON payload from `port.data.model_dump(by_alias=True)` to the URL.
+          If the HTTP request fails, print a message to stdout and continue.
+        - Call `port.update()` to mutate the generated data for next iteration.
+        - Sleep for 2 seconds.
+    """
+    port = build_random_port()
+    loops = 0
+    payloads = 1
+    try:
+        while True:
+            loops += 1
+            try:
+                print(f"    loop: {loops:<8} sending payload: {payloads}", end="\r")
+                payload = port.data.model_dump(by_alias=True)
+                data_bytes = json.dumps(payload, indent=2).encode("utf-8")
+                req = urllib.request.Request(
+                    url,
+                    data=data_bytes,
+                    headers={"Content-Type": "application/json"},
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310 (stdlib only)
+                    # We don't need to print on success; quietly proceed.
+                    _ = resp.read()
+                payloads += 1
+            except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
+                # Notify stdout on failure but continue processing
+                logger.error(f"HTTP send failed: {e}")
+
+            except Exception as e:
+                logger.error(f"Unknown Error: {e}")
+                logger.exception(e)
+            finally:
+                # Update model and wait regardless of send success
+                try:
+                    port.update()
+                except Exception as e:  # Defensive: updating should not kill the loop
+                    logger.error(f"Port update failed: {e}")
+                    logger.exception(e)
+                    raise e
+                time.sleep(2)
+    except KeyboardInterrupt:
+        # Graceful shutdown on Ctrl+C
+        logger.info("Interrupted by user. Exiting.")
+
+
+if __name__ == "__main__":
+    # Allow running this module directly: python -m mooring_data_generator.http_worker <URL>
+    if len(sys.argv) != 2:
+        print("Usage: http_worker.py <URL>")
+        sys.exit(1)
+    run(sys.argv[1])

mooring_data_generator-0.9.0/src/mooring_data_generator/models.py

@@ -0,0 +1,73 @@
+from typing import Annotated, Literal, TypedDict
+
+from pydantic import AliasGenerator, BaseModel, ConfigDict, Field, alias_generators
+
+
+class TensionLimits(TypedDict):
+    high_tension: int
+    medium_tension: int
+    low_tension: int
+
+
+TENSION_LIMITS: dict[str, TensionLimits] = {
+    "default": TensionLimits(
+        high_tension=24,
+        medium_tension=14,
+        low_tension=4,
+    ),
+    "Berth A": TensionLimits(
+        high_tension=25,
+        medium_tension=15,
+        low_tension=5,
+    ),
+}
+
+
+class BasePayloadModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=AliasGenerator(
+            serialization_alias=alias_generators.to_pascal,
+        )
+    )
+
+
+class ShipData(BasePayloadModel):
+    name: str
+    vessel_id: Annotated[str, Field(pattern=r"^[0-9]{4}$")]
+
+
+class RadarData(BasePayloadModel):
+    name: Annotated[str, Field(pattern=r"^B[A-Z]RD[0-9]$")]
+    # Radar Should share the name of the Berth, Berth A Radar 1 = BARD1
+    ship_distance: Annotated[float, Field(ge=0, lt=100)] | None
+    # min 2.8 - 6.7 | max 3.4 - 30.7
+    distance_change: Annotated[float, Field(gt=-100, lt=100)] | None
+    # min 0.0007 - 0.06 | max 0.029 - 5.76
+    distance_status: Literal["INACTIVE", "ACTIVE"]
+
+
+class HookData(BasePayloadModel):
+    name: Annotated[str, Field(pattern=r"^Hook [1-9][0-9]?$")]
+    tension: Annotated[int, Field(ge=0, lt=99)] | None
+    faulted: bool
+    attached_line: Literal["BREAST", "HEAD", "SPRING", "STERN"] | None
+
+
+class BentData(BasePayloadModel):
+    name: Annotated[str, Field(pattern=r"^BNT[0-9]{3}$")]
+    # naming convention BNT + unique id
+    hooks: list[HookData]
+
+
+class BerthData(BasePayloadModel):
+    name: Annotated[str, Field(pattern=r"^Berth [A-Z]$")]
+    bent_count: Annotated[int, Field(gt=0, lt=40)]  # the count of bents: min 9 | max 15
+    hook_count: Annotated[int, Field(gt=0, lt=60)]  # the count of hooks: min 27 | max 48
+    ship: ShipData
+    radars: list[RadarData]
+    bents: list[BentData]
+
+
+class PortData(BasePayloadModel):
+    name: str  # the name of the port
+    berths: list[BerthData]