pyqmh-tools 0.0.1__tar.gz

pyqmh_tools-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PCLabTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyqmh_tools-0.0.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: pyqmh-tools
+Version: 0.0.1
+Summary: CLI tooling to scaffold and manage Python Queued Message Handler projects
+Author-email: PCLabTools <pclabtools@github.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PCLabTools/pyqmh-tools
+Project-URL: Issues, https://github.com/PCLabTools/pyqmh-tools/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+Dynamic: license-file
+
+# pyqmh-tools
+
+Scaffolding and maintenance utilities for building a Python Queued Message Handler (QMH) project.
+
+This repository is intended to be published as a PyPI package so the tooling can be installed with `pip` and used as project commands.
+
+## Installation
+
+Install from PyPI (after publish):
+
+```bash
+pip install pyqmh-tools
+```
+
+## Commands
+
+This package provides three main commands:
+
+1. `pyqmh_project_init`
+2. `pyqmh_module_add`
+3. `pyqmh_module_remove`
+
+Note: if you see `pyqmg-module-remove` elsewhere, treat that as a typo. The command name in this project is `pyqmh_module_remove`.
+
+---
+
+### `pyqmh_project_init`
+
+Initializes a new QMH project in the current directory.
+
+What it does:
+
+- Creates `src/` and `src/modules/` if they do not already exist.
+- Creates `src/modules/__init__.py` if missing.
+- Copies template `app.py` into `src/app.py` if it does not already exist.
+- Prompts for app/project description (only when creating `app.py`).
+- Fills template placeholders such as description/author.
+- Creates root `.gitignore` from template if `.gitignore` does not exist.
+
+Run from your target project directory:
+
+```bash
+pyqmh_project_init
+```
+
+---
+
+### `pyqmh_module_add`
+
+Adds a new module to `src/modules`, or adds a new implementation to an existing factory module.
+
+Behavior summary:
+
+- Prompts for module name first.
+- If module already exists and is a factory module, prompts to add a new implementation.
+- If module does not exist, prompts for module type:
+  - `standard`
+  - `factory`
+  - `repository`
+
+`standard` creation:
+
+- Creates `src/modules/<module_name>/module.py` from template.
+- Creates module `__init__.py` from template with imports/exports.
+- Updates `src/modules/__init__.py` import and `__all__` (if file exists).
+- Updates `src/app.py` import and constructor registration (if file exists).
+
+`factory` creation:
+
+- Creates `factory.py`, `base.py`, and `simulated.py` from templates.
+- Creates module `__init__.py` from template with imports/exports.
+- Includes factory/base/simulated exports.
+- Updates `src/modules/__init__.py` import and `__all__` (if file exists).
+- Updates `src/app.py` import and constructor registration (if file exists).
+
+`repository` creation:
+
+- Prompts for Git repository URL.
+- Adds the repository as a Git submodule under `src/modules/<module_name>`.
+- If repository URL is blank, falls back to template-based creation prompts.
+
+Add new module:
+
+```bash
+pyqmh_module_add
+```
+
+---
+
+### `pyqmh_module_remove`
+
+Removes an existing module from `src/modules`.
+
+Behavior summary:
+
+- Prints available modules before prompting.
+- Accepts module name as folder name or CamelCase class name.
+- Shows files to be removed and asks for confirmation.
+- If module is a Git submodule:
+  - deinitializes submodule
+  - removes it from Git index
+  - removes submodule metadata
+- If module is a regular folder:
+  - removes the folder directly
+- Cleans up references after removal:
+  - `src/modules/__init__.py` imports and `__all__`
+  - `src/app.py` import and constructor registration
+
+Remove module:
+
+```bash
+pyqmh_module_remove
+```
+
+## Typical New Project Flow
+
+From a new directory:
+
+1. Initialize project scaffold.
+2. Add one or more modules.
+3. Run app.
+
+Example:
+
+```bash
+mkdir my-qmh-project
+cd my-qmh-project
+
+pyqmh_project_init
+pyqmh_module_add
+pyqmh_module_add
+
+python src/app.py --debug
+```
+
+## Development Notes
+
+- Commands are designed to be run from the project root where `src/` should exist.
+- The tools are idempotent for common setup steps (existing files/folders are generally preserved).
+- Generated files are template-driven from `src/pyqmh_tools/assets`.

pyqmh_tools-0.0.1/README.md

@@ -0,0 +1,140 @@
+# pyqmh-tools
+
+Scaffolding and maintenance utilities for building a Python Queued Message Handler (QMH) project.
+
+This repository is intended to be published as a PyPI package so the tooling can be installed with `pip` and used as project commands.
+
+## Installation
+
+Install from PyPI (after publish):
+
+```bash
+pip install pyqmh-tools
+```
+
+## Commands
+
+This package provides three main commands:
+
+1. `pyqmh_project_init`
+2. `pyqmh_module_add`
+3. `pyqmh_module_remove`
+
+Note: if you see `pyqmg-module-remove` elsewhere, treat that as a typo. The command name in this project is `pyqmh_module_remove`.
+
+---
+
+### `pyqmh_project_init`
+
+Initializes a new QMH project in the current directory.
+
+What it does:
+
+- Creates `src/` and `src/modules/` if they do not already exist.
+- Creates `src/modules/__init__.py` if missing.
+- Copies template `app.py` into `src/app.py` if it does not already exist.
+- Prompts for app/project description (only when creating `app.py`).
+- Fills template placeholders such as description/author.
+- Creates root `.gitignore` from template if `.gitignore` does not exist.
+
+Run from your target project directory:
+
+```bash
+pyqmh_project_init
+```
+
+---
+
+### `pyqmh_module_add`
+
+Adds a new module to `src/modules`, or adds a new implementation to an existing factory module.
+
+Behavior summary:
+
+- Prompts for module name first.
+- If module already exists and is a factory module, prompts to add a new implementation.
+- If module does not exist, prompts for module type:
+  - `standard`
+  - `factory`
+  - `repository`
+
+`standard` creation:
+
+- Creates `src/modules/<module_name>/module.py` from template.
+- Creates module `__init__.py` from template with imports/exports.
+- Updates `src/modules/__init__.py` import and `__all__` (if file exists).
+- Updates `src/app.py` import and constructor registration (if file exists).
+
+`factory` creation:
+
+- Creates `factory.py`, `base.py`, and `simulated.py` from templates.
+- Creates module `__init__.py` from template with imports/exports.
+- Includes factory/base/simulated exports.
+- Updates `src/modules/__init__.py` import and `__all__` (if file exists).
+- Updates `src/app.py` import and constructor registration (if file exists).
+
+`repository` creation:
+
+- Prompts for Git repository URL.
+- Adds the repository as a Git submodule under `src/modules/<module_name>`.
+- If repository URL is blank, falls back to template-based creation prompts.
+
+Add new module:
+
+```bash
+pyqmh_module_add
+```
+
+---
+
+### `pyqmh_module_remove`
+
+Removes an existing module from `src/modules`.
+
+Behavior summary:
+
+- Prints available modules before prompting.
+- Accepts module name as folder name or CamelCase class name.
+- Shows files to be removed and asks for confirmation.
+- If module is a Git submodule:
+  - deinitializes submodule
+  - removes it from Git index
+  - removes submodule metadata
+- If module is a regular folder:
+  - removes the folder directly
+- Cleans up references after removal:
+  - `src/modules/__init__.py` imports and `__all__`
+  - `src/app.py` import and constructor registration
+
+Remove module:
+
+```bash
+pyqmh_module_remove
+```
+
+## Typical New Project Flow
+
+From a new directory:
+
+1. Initialize project scaffold.
+2. Add one or more modules.
+3. Run app.
+
+Example:
+
+```bash
+mkdir my-qmh-project
+cd my-qmh-project
+
+pyqmh_project_init
+pyqmh_module_add
+pyqmh_module_add
+
+python src/app.py --debug
+```
+
+## Development Notes
+
+- Commands are designed to be run from the project root where `src/` should exist.
+- The tools are idempotent for common setup steps (existing files/folders are generally preserved).
+- Generated files are template-driven from `src/pyqmh_tools/assets`.

pyqmh_tools-0.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyqmh-tools"
+version = "0.0.1"
+authors = [
+	{ name = "PCLabTools", email = "pclabtools@github.io" },
+]
+description = "CLI tooling to scaffold and manage Python Queued Message Handler projects"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+		"Programming Language :: Python :: 3",
+		"Programming Language :: Python :: 3 :: Only",
+		"Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+Homepage = "https://github.com/PCLabTools/pyqmh-tools"
+Issues = "https://github.com/PCLabTools/pyqmh-tools/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=9.0"]
+
+[project.scripts]
+pyqmh_module_add = "pyqmh_tools.pyqmh_module_add:main"
+pyqmh_module_remove = "pyqmh_tools.pyqmh_module_remove:main"
+pyqmh_project_init = "pyqmh_tools.pyqmh_project_init:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pyqmh_tools*"]
+
+[tool.setuptools.package-data]
+pyqmh_tools = ["assets/*.py", "assets/new-.gitignore"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+addopts = "-q"

pyqmh_tools-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyqmh_tools-0.0.1/src/pyqmh_tools/__init__.py

@@ -0,0 +1 @@
+"""pyqmh-tools package."""

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-.gitignore

@@ -0,0 +1,29 @@
+.venv
+__pycache__/
+*.egg-info
+.pytest_cache/
+.coverage
+
+# Packaging/build outputs
+build/
+dist/
+*.egg
+pip-wheel-metadata/
+
+# Coverage outputs
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type/lint/test tooling caches
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+
+# Editor/IDE
+.vscode/
+.idea/
+
+# Optional local Python version file
+.python-version

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-app.py

@@ -0,0 +1,79 @@
+"""
+file: app.py
+description: {{DESCRIPTION}}
+author: {{AUTHOR}}
+"""
+
+import logging
+import argparse
+from pyqmh import Protocol, Message
+
+class App():
+    def __init__(self, debug: bool = False):
+        self.debug = debug
+        self.address = "main"
+        self.protocol = Protocol(self.address)
+        self.logger = logging.getLogger("pyqmh.module").getChild(self.address)
+        self.logger.setLevel(logging.DEBUG if self.debug else logging.INFO)
+
+        # Register modules here
+        # {{MODULE_NAME}}("{{MODULE_NAME}}", self.protocol, debug=self.debug)
+
+    def __del__(self):
+        """Clean up the main module by deleting the protocol instance.
+        """
+        del self.protocol
+
+    def run(self):
+        """Run the main application loop and handles application shutdown.
+        """
+        self.logger.debug("Starting main application loop.")
+
+        # Perform any actions needed before entering the main loop, such as initializing modules or setting up resources.
+
+        print(f"\033[92mMain application loop has started. Press Ctrl+C to exit.\033[0m")
+
+        while True:
+            try:
+                message = self.protocol.receive_message(self.address, timeout=0.2)
+                if self.handle_message(message):
+                    break
+            except TimeoutError:
+                continue
+            except KeyboardInterrupt:
+                self.logger.debug("Keyboard interrupt received. Shutting down.")
+                self.protocol.broadcast_message("shutdown")
+                break
+
+    def handle_message(self, message: Message) -> bool:
+        """Handle incoming messages.
+
+        Args:
+            message: The message to handle.
+
+        Returns:
+            bool: True if the message was handled successfully, False otherwise.
+        """
+        self.logger.debug(f"Handling message: {message}")
+        if message.command == "shutdown":
+            self.logger.debug("Received shutdown command. Shutting down.")
+            self.protocol.broadcast_message("shutdown")
+            try:
+                self.protocol.receive_message(self.address, timeout=5)  # Wait for acknowledgments
+            except TimeoutError:
+                self.logger.debug("Timeout occurred while waiting for acknowledgments.")
+            return True
+        return False
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run the pyqmh app.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging.")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.debug else logging.INFO,
+        format="%(name)s - %(levelname)s - %(message)s",
+    )
+    app = App(debug=args.debug)
+    app.run()

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-base.py

@@ -0,0 +1,57 @@
+"""
+file: base.py
+description: Base implementation contract for {{MODULE_NAME}} modules.
+author: {{AUTHOR}}
+"""
+
+import logging
+from typing import Optional
+from abc import ABC, abstractmethod
+from pyqmh import Message, Protocol, Module
+
+
+class Base{{MODULE_NAME}}(Module, ABC):
+    """Abstract base class for {{MODULE_NAME}} implementations."""
+
+    def __init__(self, address: str, protocol: Protocol, debug: Optional[bool] = None):
+        """Initialises the factory module.
+
+        Args:
+            address (str): Unique address for the module.
+            protocol (Protocol): The protocol instance.
+            debug (bool, optional): Debug flag. Defaults to None.
+        """
+        super().__init__(address, protocol, debug=debug)
+        self.logger = logging.getLogger("pyqmh.module").getChild(self.address)
+        self.logger.setLevel(logging.DEBUG if debug else logging.INFO)
+
+    def handle_message(self, message: Message) -> bool:
+        """Handle incoming messages.
+
+        Args:
+            message (Message): The message to handle.
+
+        Returns:
+            bool: True if the module should shutdown, False otherwise.
+        """
+        self.logger.debug(f"Handling message: {message}")
+        if message.command == "greet":
+            return self.greet(message)
+        return super().handle_message(message)
+
+    @abstractmethod
+    def background_task(self):
+        """Background task - must be implemented by each factory implementation."""
+        raise NotImplementedError("background_task must be implemented by subclasses")
+
+    @abstractmethod
+    def greet(self, message: Message) -> bool:
+        """Handle the greet message - must be implemented by each factory implementation.
+
+        Args:
+            message (Message): Incoming message.
+
+        Returns:
+            bool: False to continue running.
+        """
+        raise NotImplementedError("greet must be implemented by subclasses")

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-factory.py

@@ -0,0 +1,73 @@
+"""
+file: factory.py
+description: Factory module for creating {{MODULE_NAME}} instances with swappable implementations.
+author: {{AUTHOR}}
+"""
+
+from typing import Optional
+from pyqmh import Protocol
+
+from .base import Base{{MODULE_NAME}}
+
+
+class {{MODULE_NAME}}:
+    """Factory for creating {{MODULE_NAME}} instances with swappable implementations at runtime.
+
+    Raises:
+        ValueError: When an invalid implementation type is specified.
+
+    Returns:
+        Base{{MODULE_NAME}}: An instance of the factory module based on the specified implementation type.
+    """
+
+    _implementations: dict[str, type[Base{{MODULE_NAME}}]] = {}
+
+    @classmethod
+    def register(cls, implementation: str, module_class: type[Base{{MODULE_NAME}}]):
+        """Registers a factory implementation.
+
+        Args:
+            implementation (str): The name of the implementation.
+            module_class (type[Base{{MODULE_NAME}}]): The class to register.
+        """
+        cls._implementations[implementation.lower()] = module_class
+
+    @classmethod
+    def create(
+        cls,
+        address: str,
+        protocol: Protocol,
+        debug: Optional[bool] = None,
+        implementation_type: str = "simulated",
+    ) -> Base{{MODULE_NAME}}:
+        """Creates a factory module instance based on implementation type.
+
+        Args:
+            address (str): Unique address for the module.
+            protocol (Protocol): The protocol instance.
+            debug (bool, optional): Debug flag. Defaults to None.
+            implementation_type (str, optional): Implementation to create. Defaults to "simulated".
+
+        Returns:
+            Base{{MODULE_NAME}}: The created module instance.
+
+        Raises:
+            ValueError: If the specified implementation type is not registered.
+        """
+        implementation_type = implementation_type.lower()
+        if implementation_type not in cls._implementations:
+            raise ValueError(f"{{MODULE_NAME}}: No factory implementation registered for type '{implementation_type}'")
+        return cls._implementations[implementation_type](address, protocol, debug)
+
+    def __new__(
+        cls,
+        address: str,
+        protocol: Protocol,
+        debug: Optional[bool] = None,
+        implementation_type: str = "simulated",
+    ) -> Base{{MODULE_NAME}}:
+        return cls.create(address, protocol, debug, implementation_type)
+
+
+# Import implementations to register them.
+from . import simulated  # noqa: E402,F401

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-implementation.py

@@ -0,0 +1,39 @@
+"""
+file: {{IMPLEMENTATION_NAME}}.py
+description: {{IMPLEMENTATION_NAME}} implementation of {{MODULE_NAME}}. {{DESCRIPTION}}
+author: {{AUTHOR}}
+"""
+
+from time import sleep
+from pyqmh import Message
+
+from .factory import {{MODULE_NAME}}
+from .base import Base{{MODULE_NAME}}
+
+
+class {{IMPLEMENTATION_NAME}}{{MODULE_NAME}}(Base{{MODULE_NAME}}):
+    """Simulated implementation of {{MODULE_NAME}}."""
+
+    def background_task(self):
+        """Simulated background task."""
+        while self.background_task_running:
+            self.logger.debug("Performing background task.")
+            # TODO: implement simulated background task logic
+            sleep(1)
+
+    def message_custom_action(self, message: Message) -> bool:
+        """Handles the custom_action message.
+
+        Args:
+            message (Message): Incoming message.
+
+        Returns:
+            bool: False to continue running.
+        """
+        self.logger.debug(f"Handling custom action: {message}")
+        # TODO: implement simulated custom action logic
+        return False
+
+
+# Register this implementation with the factory.
+{{MODULE_NAME}}.register("{{IMPLEMENTATION_NAME}}", {{IMPLEMENTATION_NAME}}{{MODULE_NAME}})

pyqmh_tools-0.0.1/src/pyqmh_tools/assets/new-init.py

@@ -0,0 +1,9 @@
+"""
+file: __init__.py
+description: Public exports for the {{MODULE_NAME}} module.
+author: {{AUTHOR}}
+"""
+
+{{MODULE_IMPORTS}}
+
+__all__ = [{{MODULE_EXPORTS}}]