mmrelay 1.1.3__py3-none-any.whl → 1.1.4__py3-none-any.whl

mmrelay/__init__.py

@@ -2,4 +2,4 @@
 Meshtastic Matrix Relay - Bridge between Meshtastic mesh networks and Matrix chat rooms.
 """
 
-__version__ = "1.1.3"
+__version__ = "1.1.4"

mmrelay/cli.py

@@ -12,15 +12,36 @@ from yaml.loader import SafeLoader
 
 # Import version from package
 from mmrelay import __version__
+from mmrelay.config import get_config_paths
+from mmrelay.constants.app import WINDOWS_PLATFORM
+from mmrelay.constants.config import (
+    CONFIG_KEY_ACCESS_TOKEN,
+    CONFIG_KEY_BOT_USER_ID,
+    CONFIG_KEY_HOMESERVER,
+    CONFIG_SECTION_MATRIX,
+    CONFIG_SECTION_MESHTASTIC,
+)
+from mmrelay.constants.network import (
+    CONFIG_KEY_BLE_ADDRESS,
+    CONFIG_KEY_CONNECTION_TYPE,
+    CONFIG_KEY_HOST,
+    CONFIG_KEY_SERIAL_PORT,
+    CONNECTION_TYPE_BLE,
+    CONNECTION_TYPE_NETWORK,
+    CONNECTION_TYPE_SERIAL,
+    CONNECTION_TYPE_TCP,
+)
 from mmrelay.tools import get_sample_config_path
 
 
 def parse_arguments():
     """
-    Parse command-line arguments.
+    Parse and validate command-line arguments for the Meshtastic Matrix Relay CLI.
+
+    Supports options for specifying configuration file, data directory, logging preferences, version display, sample configuration generation, service installation, and configuration validation. On Windows, also accepts a deprecated positional argument for the config file path with a warning. Ignores unknown arguments outside of test environments and warns if any are present.
 
     Returns:
-        argparse.Namespace: The parsed command-line arguments
+        argparse.Namespace: Parsed command-line arguments.
     """
     parser = argparse.ArgumentParser(
         description="Meshtastic Matrix Relay - Bridge between Meshtastic and Matrix"
@@ -61,16 +82,20 @@ def parse_arguments():
 
     # Windows-specific handling for backward compatibility
     # On Windows, add a positional argument for the config file path
-    if sys.platform == "win32":
+    if sys.platform == WINDOWS_PLATFORM:
         parser.add_argument(
             "config_path", nargs="?", help=argparse.SUPPRESS, default=None
         )
 
-    args = parser.parse_args()
+    # Use parse_known_args to handle unknown arguments gracefully (e.g., pytest args)
+    args, unknown = parser.parse_known_args()
+    # If there are unknown arguments and we're not in a test environment, warn about them
+    if unknown and not any("pytest" in arg or "test" in arg for arg in sys.argv):
+        print(f"Warning: Unknown arguments ignored: {unknown}")
 
     # If on Windows and a positional config path is provided but --config is not, use the positional one
     if (
-        sys.platform == "win32"
+        sys.platform == WINDOWS_PLATFORM
         and hasattr(args, "config_path")
         and args.config_path
         and not args.config
@@ -105,15 +130,16 @@ def print_version():
 
 def check_config(args=None):
     """
-    Check if the configuration file is valid.
+    Validates the application's configuration file for required structure and fields.
 
-    Args:
-        args: The parsed command-line arguments
+    If a configuration file is found, checks for the presence and correctness of required sections and keys, including Matrix and Meshtastic settings, and validates the format of matrix rooms. Prints errors or warnings for missing or deprecated fields. Returns True if the configuration is valid, otherwise False.
+
+    Parameters:
+        args: Parsed command-line arguments. If None, arguments are parsed internally.
 
     Returns:
-        bool: True if the configuration is valid, False otherwise.
+        bool: True if the configuration file is valid, False otherwise.
     """
-    from mmrelay.config import get_config_paths
 
     # If args is None, parse them now
     if args is None:
@@ -137,12 +163,16 @@ def check_config(args=None):
                     return False
 
                 # Check matrix section
-                if "matrix" not in config:
+                if CONFIG_SECTION_MATRIX not in config:
                     print("Error: Missing 'matrix' section in config")
                     return False
 
-                matrix_section = config["matrix"]
-                required_matrix_fields = ["homeserver", "access_token", "bot_user_id"]
+                matrix_section = config[CONFIG_SECTION_MATRIX]
+                required_matrix_fields = [
+                    CONFIG_KEY_HOMESERVER,
+                    CONFIG_KEY_ACCESS_TOKEN,
+                    CONFIG_KEY_BOT_USER_ID,
+                ]
                 missing_matrix_fields = [
                     field
                     for field in required_matrix_fields
@@ -178,47 +208,55 @@ def check_config(args=None):
                         return False
 
                 # Check meshtastic section
-                if "meshtastic" not in config:
+                if CONFIG_SECTION_MESHTASTIC not in config:
                     print("Error: Missing 'meshtastic' section in config")
                     return False
 
-                meshtastic_section = config["meshtastic"]
+                meshtastic_section = config[CONFIG_SECTION_MESHTASTIC]
                 if "connection_type" not in meshtastic_section:
                     print("Error: Missing 'connection_type' in 'meshtastic' section")
                     return False
 
-                connection_type = meshtastic_section["connection_type"]
-                if connection_type not in ["tcp", "serial", "ble", "network"]:
+                connection_type = meshtastic_section[CONFIG_KEY_CONNECTION_TYPE]
+                if connection_type not in [
+                    CONNECTION_TYPE_TCP,
+                    CONNECTION_TYPE_SERIAL,
+                    CONNECTION_TYPE_BLE,
+                    CONNECTION_TYPE_NETWORK,
+                ]:
                     print(
-                        f"Error: Invalid 'connection_type': {connection_type}. Must be 'tcp', 'serial', or 'ble'"
+                        f"Error: Invalid 'connection_type': {connection_type}. Must be '{CONNECTION_TYPE_TCP}', '{CONNECTION_TYPE_SERIAL}', or '{CONNECTION_TYPE_BLE}'"
                     )
                     return False
 
                 # Check for deprecated connection_type
-                if connection_type == "network":
+                if connection_type == CONNECTION_TYPE_NETWORK:
                     print(
                         "\nWarning: 'network' connection_type is deprecated. Please use 'tcp' instead."
                     )
                     print(
-                        "See ANNOUNCEMENT.md for more information about deprecated options.\n"
+                        "This option still works but may be removed in future versions.\n"
                     )
 
                 # Check connection-specific fields
                 if (
-                    connection_type == "serial"
-                    and "serial_port" not in meshtastic_section
+                    connection_type == CONNECTION_TYPE_SERIAL
+                    and CONFIG_KEY_SERIAL_PORT not in meshtastic_section
                 ):
                     print("Error: Missing 'serial_port' for 'serial' connection type")
                     return False
 
                 if (
-                    connection_type in ["tcp", "network"]
-                    and "host" not in meshtastic_section
+                    connection_type in [CONNECTION_TYPE_TCP, CONNECTION_TYPE_NETWORK]
+                    and CONFIG_KEY_HOST not in meshtastic_section
                 ):
                     print("Error: Missing 'host' for 'tcp' connection type")
                     return False
 
-                if connection_type == "ble" and "ble_address" not in meshtastic_section:
+                if (
+                    connection_type == CONNECTION_TYPE_BLE
+                    and CONFIG_KEY_BLE_ADDRESS not in meshtastic_section
+                ):
                     print("Error: Missing 'ble_address' for 'ble' connection type")
                     return False
 
@@ -228,7 +266,7 @@ def check_config(args=None):
                         "\nWarning: 'db' section is deprecated. Please use 'database' instead."
                     )
                     print(
-                        "See ANNOUNCEMENT.md for more information about deprecated options.\n"
+                        "This option still works but may be removed in future versions.\n"
                     )
 
                 print("Configuration file is valid!")
@@ -248,36 +286,50 @@ def check_config(args=None):
 
 
 def main():
-    """Entry point for CLI commands.
+    """
+    Runs the Meshtastic Matrix Relay CLI, handling argument parsing, command execution, and error reporting.
 
     Returns:
-        int: Exit code (0 for success, non-zero for failure)
+        int: Exit code indicating success (0) or failure (non-zero).
     """
-    args = parse_arguments()
+    try:
+        args = parse_arguments()
 
-    # Handle --check-config
-    if args.check_config:
-        return 0 if check_config(args) else 1
+        # Handle --check-config
+        if args.check_config:
+            return 0 if check_config(args) else 1
 
-    # Handle --install-service
-    if args.install_service:
-        from mmrelay.setup_utils import install_service
+        # Handle --install-service
+        if args.install_service:
+            try:
+                from mmrelay.setup_utils import install_service
 
-        return 0 if install_service() else 1
+                return 0 if install_service() else 1
+            except ImportError as e:
+                print(f"Error importing setup utilities: {e}")
+                return 1
 
-    # Handle --generate-config
-    if args.generate_config:
-        return 0 if generate_sample_config() else 1
+        # Handle --generate-config
+        if args.generate_config:
+            return 0 if generate_sample_config() else 1
 
-    # Handle --version
-    if args.version:
-        print_version()
-        return 0
+        # Handle --version
+        if args.version:
+            print_version()
+            return 0
 
-    # If no command was specified, run the main functionality
-    from mmrelay.main import run_main
+        # If no command was specified, run the main functionality
+        try:
+            from mmrelay.main import run_main
 
-    return run_main(args)
+            return run_main(args)
+        except ImportError as e:
+            print(f"Error importing main module: {e}")
+            return 1
+
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return 1
 
 
 if __name__ == "__main__":
@@ -332,16 +384,17 @@ def handle_cli_commands(args):
 
 
 def generate_sample_config():
-    """Generate a sample config.yaml file.
+    """
+    Generate a sample configuration file (`config.yaml`) in the default location if one does not already exist.
+
+    Attempts to copy a sample config from various sources, handling directory creation and file system errors gracefully. Prints informative messages on success or failure.
 
     Returns:
-        bool: True if the config was generated successfully, False otherwise.
+        bool: True if the sample config was generated successfully, False otherwise.
     """
 
     import shutil
 
-    from mmrelay.config import get_config_paths
-
     # Get the first config path (highest priority)
     config_paths = get_config_paths()
 
@@ -362,8 +415,7 @@ def generate_sample_config():
     # No config file exists, generate one in the first location
     target_path = config_paths[0]
 
-    # Ensure the directory exists
-    os.makedirs(os.path.dirname(target_path), exist_ok=True)
+    # Directory should already exist from get_config_paths() call
 
     # Use the helper function to get the sample config path
     sample_config_path = get_sample_config_path()
@@ -372,12 +424,16 @@ def generate_sample_config():
         # Copy the sample config file to the target path
         import shutil
 
-        shutil.copy2(sample_config_path, target_path)
-        print(f"Generated sample config file at: {target_path}")
-        print(
-            "\nEdit this file with your Matrix and Meshtastic settings before running mmrelay."
-        )
-        return True
+        try:
+            shutil.copy2(sample_config_path, target_path)
+            print(f"Generated sample config file at: {target_path}")
+            print(
+                "\nEdit this file with your Matrix and Meshtastic settings before running mmrelay."
+            )
+            return True
+        except (IOError, OSError) as e:
+            print(f"Error copying sample config file: {e}")
+            return False
 
     # If the helper function failed, try using importlib.resources directly
     try:
@@ -418,12 +474,16 @@ def generate_sample_config():
 
         for path in sample_config_paths:
             if os.path.exists(path):
-                shutil.copy(path, target_path)
-                print(f"Generated sample config file at: {target_path}")
-                print(
-                    "\nEdit this file with your Matrix and Meshtastic settings before running mmrelay."
-                )
-                return True
+                try:
+                    shutil.copy(path, target_path)
+                    print(f"Generated sample config file at: {target_path}")
+                    print(
+                        "\nEdit this file with your Matrix and Meshtastic settings before running mmrelay."
+                    )
+                    return True
+                except (IOError, OSError) as e:
+                    print(f"Error copying sample config file from {path}: {e}")
+                    return False
 
         print("Error: Could not find sample_config.yaml")
         return False

mmrelay/config.py

@@ -6,10 +6,14 @@ import platformdirs
 import yaml
 from yaml.loader import SafeLoader
 
-# Define custom base directory for Unix systems
-APP_NAME = "mmrelay"
-APP_AUTHOR = None  # No author directory
-
+# Import application constants
+from mmrelay.constants.app import APP_AUTHOR, APP_NAME
+from mmrelay.constants.config import (
+    CONFIG_KEY_ACCESS_TOKEN,
+    CONFIG_KEY_BOT_USER_ID,
+    CONFIG_KEY_HOMESERVER,
+    CONFIG_SECTION_MATRIX,
+)
 
 # Global variable to store the custom data directory
 custom_data_dir = None
@@ -49,14 +53,15 @@ def get_app_path():
 
 def get_config_paths(args=None):
     """
-    Returns a list of possible config file paths in order of priority:
-    1. Command line argument (if provided)
-    2. User config directory (~/.mmrelay/config/ on Linux)
-    3. Current directory (for backward compatibility)
-    4. Application directory (for backward compatibility)
-
-    Args:
-        args: The parsed command-line arguments
+    Return a prioritized list of possible configuration file paths for the application.
+
+    The search order is: a command-line specified path (if provided), the user config directory, the current working directory, and the application directory. The user config directory is skipped if it cannot be created due to permission or OS errors.
+
+    Parameters:
+        args: Parsed command-line arguments, expected to have a 'config' attribute specifying a config file path.
+
+    Returns:
+        List of absolute paths to candidate configuration files, ordered by priority.
     """
     paths = []
 
@@ -72,9 +77,13 @@ def get_config_paths(args=None):
         # Use platformdirs default for Windows
         user_config_dir = platformdirs.user_config_dir(APP_NAME, APP_AUTHOR)
 
-    os.makedirs(user_config_dir, exist_ok=True)
-    user_config_path = os.path.join(user_config_dir, "config.yaml")
-    paths.append(user_config_path)
+    try:
+        os.makedirs(user_config_dir, exist_ok=True)
+        user_config_path = os.path.join(user_config_dir, "config.yaml")
+        paths.append(user_config_path)
+    except (OSError, PermissionError):
+        # If we can't create the user config directory, skip it
+        pass
 
     # Check current directory (for backward compatibility)
     current_dir_config = os.path.join(os.getcwd(), "config.yaml")
@@ -164,14 +173,12 @@ config_path = None
 
 def set_config(module, passed_config):
     """
-    Set the configuration for a module.
+    Assigns the provided configuration dictionary to a module and sets additional attributes for known module types.
 
-    Args:
-        module: The module to set the configuration for
-        passed_config: The configuration dictionary to use
+    For modules named "matrix_utils" or "meshtastic_utils", sets specific configuration attributes if present. Calls the module's `setup_config()` method if it exists for backward compatibility.
 
     Returns:
-        The updated config
+        dict: The configuration dictionary that was assigned to the module.
     """
     # Set the module's config variable
     module.config = passed_config
@@ -181,11 +188,20 @@ def set_config(module, passed_config):
 
     if module_name == "matrix_utils":
         # Set Matrix-specific configuration
-        if hasattr(module, "matrix_homeserver") and "matrix" in passed_config:
-            module.matrix_homeserver = passed_config["matrix"]["homeserver"]
+        if (
+            hasattr(module, "matrix_homeserver")
+            and CONFIG_SECTION_MATRIX in passed_config
+        ):
+            module.matrix_homeserver = passed_config[CONFIG_SECTION_MATRIX][
+                CONFIG_KEY_HOMESERVER
+            ]
             module.matrix_rooms = passed_config["matrix_rooms"]
-            module.matrix_access_token = passed_config["matrix"]["access_token"]
-            module.bot_user_id = passed_config["matrix"]["bot_user_id"]
+            module.matrix_access_token = passed_config[CONFIG_SECTION_MATRIX][
+                CONFIG_KEY_ACCESS_TOKEN
+            ]
+            module.bot_user_id = passed_config[CONFIG_SECTION_MATRIX][
+                CONFIG_KEY_BOT_USER_ID
+            ]
 
     elif module_name == "meshtastic_utils":
         # Set Meshtastic-specific configuration
@@ -200,24 +216,31 @@ def set_config(module, passed_config):
 
 
 def load_config(config_file=None, args=None):
-    """Load the configuration from the specified file or search for it.
+    """
+    Load the application configuration from a specified file or by searching standard locations.
+
+    If a config file path is provided and valid, attempts to load and parse it as YAML. If not, searches for a configuration file in prioritized locations and loads the first valid one found. Returns an empty dictionary if no valid configuration is found or if loading fails due to file or YAML errors.
 
-    Args:
-        config_file (str, optional): Path to the config file. If None, search for it.
-        args: The parsed command-line arguments
+    Parameters:
+        config_file (str, optional): Path to a specific configuration file. If None, searches default locations.
+        args: Parsed command-line arguments, used to determine config search order.
 
     Returns:
-        dict: The loaded configuration
+        dict: The loaded configuration dictionary, or an empty dictionary if loading fails.
     """
     global relay_config, config_path
 
     # If a specific config file was provided, use it
     if config_file and os.path.isfile(config_file):
         # Store the config path but don't log it yet - will be logged by main.py
-        with open(config_file, "r") as f:
-            relay_config = yaml.load(f, Loader=SafeLoader)
-        config_path = config_file
-        return relay_config
+        try:
+            with open(config_file, "r") as f:
+                relay_config = yaml.load(f, Loader=SafeLoader)
+            config_path = config_file
+            return relay_config
+        except (yaml.YAMLError, PermissionError, OSError) as e:
+            logger.error(f"Error loading config file {config_file}: {e}")
+            return {}
 
     # Otherwise, search for a config file
     config_paths = get_config_paths(args)
@@ -227,9 +250,13 @@ def load_config(config_file=None, args=None):
         if os.path.isfile(path):
             config_path = path
             # Store the config path but don't log it yet - will be logged by main.py
-            with open(config_path, "r") as f:
-                relay_config = yaml.load(f, Loader=SafeLoader)
-            return relay_config
+            try:
+                with open(config_path, "r") as f:
+                    relay_config = yaml.load(f, Loader=SafeLoader)
+                return relay_config
+            except (yaml.YAMLError, PermissionError, OSError) as e:
+                logger.error(f"Error loading config file {path}: {e}")
+                continue  # Try the next config path
 
     # No config file found
     logger.error("Configuration file not found in any of the following locations:")

mmrelay/config_checker.py

@@ -1,18 +1,37 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
+"""
+Configuration checker module for MMRelay.
+
+Note: This module contains similar functionality to the check_config function
+in mmrelay.cli. The CLI version is more complete and uses centralized constants.
+Future refactoring should consider consolidating these implementations to reduce
+code duplication while maintaining backward compatibility and test coverage.
+"""
+
 import os
 
 import yaml
 from yaml.loader import SafeLoader
 
+from mmrelay.constants.network import (
+    CONFIG_KEY_BLE_ADDRESS,
+    CONFIG_KEY_CONNECTION_TYPE,
+    CONFIG_KEY_HOST,
+    CONFIG_KEY_SERIAL_PORT,
+    CONNECTION_TYPE_BLE,
+    CONNECTION_TYPE_SERIAL,
+    CONNECTION_TYPE_TCP,
+)
+
 
 def get_config_paths():
     """
-    Get a list of possible configuration file paths.
+    Return a list of possible file paths where the mmrelay configuration file may be located.
 
     Returns:
-        list: A list of possible configuration file paths
+        list: Paths to potential configuration files.
     """
     from mmrelay.config import get_config_paths as get_paths
 
@@ -21,10 +40,10 @@ def get_config_paths():
 
 def check_config():
     """
-    Check if the configuration file is valid.
+    Validates the mmrelay configuration file by checking for required sections and fields.
 
     Returns:
-        bool: True if the configuration is valid, False otherwise.
+        bool: True if a valid configuration file is found and passes all checks; False otherwise.
     """
     config_paths = get_config_paths()
     config_path = None
@@ -90,30 +109,40 @@ def check_config():
                     return False
 
                 meshtastic_section = config["meshtastic"]
-                if "connection_type" not in meshtastic_section:
+                if CONFIG_KEY_CONNECTION_TYPE not in meshtastic_section:
                     print("Error: Missing 'connection_type' in 'meshtastic' section")
                     return False
 
-                connection_type = meshtastic_section["connection_type"]
-                if connection_type not in ["tcp", "serial", "ble"]:
+                connection_type = meshtastic_section[CONFIG_KEY_CONNECTION_TYPE]
+                if connection_type not in [
+                    CONNECTION_TYPE_TCP,
+                    CONNECTION_TYPE_SERIAL,
+                    CONNECTION_TYPE_BLE,
+                ]:
                     print(
-                        f"Error: Invalid 'connection_type': {connection_type}. Must be 'tcp', 'serial', or 'ble'"
+                        f"Error: Invalid 'connection_type': {connection_type}. Must be '{CONNECTION_TYPE_TCP}', '{CONNECTION_TYPE_SERIAL}', or '{CONNECTION_TYPE_BLE}'"
                     )
                     return False
 
                 # Check connection-specific fields
                 if (
-                    connection_type == "serial"
-                    and "serial_port" not in meshtastic_section
+                    connection_type == CONNECTION_TYPE_SERIAL
+                    and CONFIG_KEY_SERIAL_PORT not in meshtastic_section
                 ):
                     print("Error: Missing 'serial_port' for 'serial' connection type")
                     return False
 
-                if connection_type == "tcp" and "host" not in meshtastic_section:
+                if (
+                    connection_type == CONNECTION_TYPE_TCP
+                    and CONFIG_KEY_HOST not in meshtastic_section
+                ):
                     print("Error: Missing 'host' for 'tcp' connection type")
                     return False
 
-                if connection_type == "ble" and "ble_address" not in meshtastic_section:
+                if (
+                    connection_type == CONNECTION_TYPE_BLE
+                    and CONFIG_KEY_BLE_ADDRESS not in meshtastic_section
+                ):
                     print("Error: Missing 'ble_address' for 'ble' connection type")
                     return False
 

mmrelay/constants/__init__.py

@@ -0,0 +1,54 @@
+"""
+Constants package for MMRelay.
+
+This package organizes all application constants by functional area:
+- app: Application metadata and version information
+- queue: Message queue configuration constants
+- network: Network connection and timeout constants
+- formats: Message format templates and prefixes
+- messages: User-facing strings and templates
+- database: Database-related constants
+- config: Configuration section and key constants
+
+Usage:
+    from mmrelay.constants import queue
+    from mmrelay.constants.app import APP_NAME
+    from mmrelay.constants.queue import DEFAULT_MESSAGE_DELAY
+"""
+
+# Re-export commonly used constants for convenience
+from .app import APP_AUTHOR, APP_NAME
+from .config import (
+    CONFIG_KEY_LEVEL,
+    CONFIG_SECTION_LOGGING,
+    CONFIG_SECTION_MATRIX,
+    CONFIG_SECTION_MESHTASTIC,
+    DEFAULT_LOG_LEVEL,
+)
+from .formats import DEFAULT_MATRIX_PREFIX, DEFAULT_MESHTASTIC_PREFIX
+from .queue import (
+    DEFAULT_MESSAGE_DELAY,
+    MAX_QUEUE_SIZE,
+    QUEUE_HIGH_WATER_MARK,
+    QUEUE_MEDIUM_WATER_MARK,
+)
+
+__all__ = [
+    # App constants
+    "APP_NAME",
+    "APP_AUTHOR",
+    # Config constants
+    "CONFIG_SECTION_MATRIX",
+    "CONFIG_SECTION_MESHTASTIC",
+    "CONFIG_SECTION_LOGGING",
+    "CONFIG_KEY_LEVEL",
+    "DEFAULT_LOG_LEVEL",
+    # Queue constants
+    "DEFAULT_MESSAGE_DELAY",
+    "MAX_QUEUE_SIZE",
+    "QUEUE_HIGH_WATER_MARK",
+    "QUEUE_MEDIUM_WATER_MARK",
+    # Format constants
+    "DEFAULT_MESHTASTIC_PREFIX",
+    "DEFAULT_MATRIX_PREFIX",
+]

mmrelay/constants/app.py

@@ -0,0 +1,17 @@
+"""
+Application metadata constants.
+
+Contains version information, application name, and other metadata
+used throughout the MMRelay application.
+"""
+
+# Application identification
+APP_NAME = "mmrelay"
+APP_AUTHOR = None  # No author directory for platformdirs
+
+# Application display names
+APP_DISPLAY_NAME = "M<>M Relay"
+APP_FULL_NAME = "Meshtastic Matrix Relay"
+
+# Platform-specific constants
+WINDOWS_PLATFORM = "win32"