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

mmrelay/matrix_utils.py

@@ -21,6 +21,18 @@ from nio import (
 from nio.events.room_events import RoomMemberEvent
 from PIL import Image
 
+from mmrelay.constants.config import (
+    CONFIG_KEY_ACCESS_TOKEN,
+    CONFIG_KEY_HOMESERVER,
+    CONFIG_SECTION_MATRIX,
+)
+from mmrelay.constants.database import DEFAULT_MSGS_TO_KEEP
+from mmrelay.constants.formats import (
+    DEFAULT_MATRIX_PREFIX,
+    DEFAULT_MESHTASTIC_PREFIX,
+    DETECTION_SENSOR_APP,
+)
+from mmrelay.constants.network import MILLISECONDS_PER_SECOND
 from mmrelay.db_utils import (
     get_message_map_by_matrix_event_id,
     prune_message_map,
@@ -37,14 +49,14 @@ logger = get_logger(name="matrix_utils")
 
 def _get_msgs_to_keep_config():
     """
-    Retrieve the configured number of messages to retain for message mapping, supporting both current and legacy configuration formats.
+    Returns the configured number of messages to retain for message mapping, supporting both current and legacy configuration sections.
 
     Returns:
-        int: The number of messages to keep in the database for message mapping (default is 500).
+        int: Number of messages to keep for message mapping; defaults to the predefined constant if not set.
     """
     global config
     if not config:
-        return 500
+        return DEFAULT_MSGS_TO_KEEP
 
     msg_map_config = config.get("database", {}).get("msg_map", {})
 
@@ -58,26 +70,19 @@ def _get_msgs_to_keep_config():
                 "Using 'db.msg_map' configuration (legacy). 'database.msg_map' is now the preferred format and 'db.msg_map' will be deprecated in a future version."
             )
 
-    return msg_map_config.get("msgs_to_keep", 500)
+    return msg_map_config.get("msgs_to_keep", DEFAULT_MSGS_TO_KEEP)
 
 
 def _create_mapping_info(
     matrix_event_id, room_id, text, meshnet=None, msgs_to_keep=None
 ):
     """
-    Constructs a dictionary containing metadata for mapping a Matrix event to a Meshtastic message in the message queue.
+    Create a metadata dictionary linking a Matrix event to a Meshtastic message for message mapping.
 
-    Removes quoted lines from the message text and includes relevant identifiers and configuration for message retention. Returns `None` if required parameters are missing.
-
-    Parameters:
-        matrix_event_id: The Matrix event ID to map.
-        room_id: The Matrix room ID where the event occurred.
-        text: The message text to be mapped; quoted lines are removed.
-        meshnet: Optional name of the target mesh network.
-        msgs_to_keep: Optional number of messages to retain for mapping; uses configuration default if not provided.
+    Removes quoted lines from the message text and includes identifiers and message retention settings. Returns `None` if any required parameter is missing.
 
     Returns:
-        dict: A dictionary with mapping information for use by the message queue, or `None` if required fields are missing.
+        dict: Mapping information for the message queue, or `None` if required fields are missing.
     """
     if not matrix_event_id or not room_id or not text:
         return None
@@ -94,16 +99,11 @@ def _create_mapping_info(
     }
 
 
-# Default prefix format constants
-DEFAULT_MESHTASTIC_PREFIX = "{display5}[M]: "
-DEFAULT_MATRIX_PREFIX = "[{long}/{mesh}]: "
-
-
 def get_interaction_settings(config):
     """
-    Returns a dictionary indicating whether message reactions and replies are enabled based on the provided configuration.
+    Determine if message reactions and replies are enabled in the configuration.
 
-    Supports both the new `message_interactions` structure and the legacy `relay_reactions` flag for backward compatibility. Defaults to disabling both features if not specified.
+    Checks for both the new `message_interactions` structure and the legacy `relay_reactions` flag for backward compatibility. Returns a dictionary with boolean values for `reactions` and `replies`, defaulting to both disabled if not specified.
     """
     if config is None:
         return {"reactions": False, "replies": False}
@@ -244,28 +244,19 @@ def get_meshtastic_prefix(config, display_name, user_id=None):
 
 def get_matrix_prefix(config, longname, shortname, meshnet_name):
     """
-    Generate a formatted prefix for Meshtastic messages relayed to Matrix, using configurable templates and variable-length truncation for sender and mesh network names.
+    Generates a formatted prefix string for Meshtastic messages relayed to Matrix, based on configuration settings and sender/mesh network names.
+
+    The prefix format supports variable-length truncation for the sender and mesh network names using template variables (e.g., `{long4}` for the first 4 characters of the sender name). Returns an empty string if prefixing is disabled in the configuration.
 
     Parameters:
-        config (dict): The application configuration dictionary.
         longname (str): Full Meshtastic sender name.
         shortname (str): Short Meshtastic sender name.
         meshnet_name (str): Name of the mesh network.
 
     Returns:
-        str: The formatted prefix string if prefixing is enabled; otherwise, an empty string.
-
-    Examples:
-        Basic usage:
-            get_matrix_prefix(config, "Alice", "Ali", "MyMesh")
-            # Returns: "[Alice/MyMesh]: " (with default format)
-
-        Custom format:
-            config = {"matrix": {"prefix_format": "({long4}): "}}
-            get_matrix_prefix(config, "Alice", "Ali", "MyMesh")
-            # Returns: "(Alic): "
+        str: The formatted prefix string, or an empty string if prefixing is disabled.
     """
-    matrix_config = config.get("matrix", {})
+    matrix_config = config.get(CONFIG_SECTION_MATRIX, {})
 
     # Enhanced debug logging for configuration troubleshooting
     logger.debug(
@@ -327,7 +318,7 @@ matrix_access_token = None
 bot_user_id = None
 bot_user_name = None  # Detected upon logon
 bot_start_time = int(
-    time.time() * 1000
+    time.time() * MILLISECONDS_PER_SECOND
 )  # Timestamp when the bot starts, used to filter out old messages
 
 logger = get_logger(name="Matrix")
@@ -372,11 +363,9 @@ def bot_command(command, event):
 
 async def connect_matrix(passed_config=None):
     """
-    Establish a connection to the Matrix homeserver.
-    Sets global matrix_client and detects the bot's display name.
+    Asynchronously connects to the Matrix homeserver, initializes the Matrix client, and retrieves the bot's device ID and display name.
 
-    Args:
-        passed_config: The configuration dictionary to use (will update global config)
+    If a configuration dictionary is provided, it updates the global configuration before connecting. Returns the initialized Matrix AsyncClient instance, or `None` if configuration is missing. Raises `ConnectionError` if SSL context creation fails.
     """
     global matrix_client, bot_user_name, matrix_homeserver, matrix_rooms, matrix_access_token, bot_user_id, config
 
@@ -390,9 +379,9 @@ async def connect_matrix(passed_config=None):
         return None
 
     # Extract Matrix configuration
-    matrix_homeserver = config["matrix"]["homeserver"]
+    matrix_homeserver = config[CONFIG_SECTION_MATRIX][CONFIG_KEY_HOMESERVER]
     matrix_rooms = config["matrix_rooms"]
-    matrix_access_token = config["matrix"]["access_token"]
+    matrix_access_token = config[CONFIG_SECTION_MATRIX][CONFIG_KEY_ACCESS_TOKEN]
     bot_user_id = config["matrix"]["bot_user_id"]
 
     # Check if client already exists
@@ -400,7 +389,11 @@ async def connect_matrix(passed_config=None):
         return matrix_client
 
     # Create SSL context using certifi's certificates
-    ssl_context = ssl.create_default_context(cafile=certifi.where())
+    try:
+        ssl_context = ssl.create_default_context(cafile=certifi.where())
+    except Exception as e:
+        logger.error(f"Failed to create SSL context: {e}")
+        raise ConnectionError(f"SSL context creation failed: {e}") from e
 
     # Initialize the Matrix client with custom SSL context
     client_config = AsyncClientConfig(encryption_enabled=False)
@@ -487,9 +480,9 @@ async def matrix_relay(
     reply_to_event_id=None,
 ):
     """
-    Relays a message from Meshtastic to a Matrix room, supporting replies and message mapping for interactions.
+    Relay a message from the Meshtastic network to a Matrix room, supporting replies, emotes, emoji reactions, and message mapping for future interactions.
 
-    If `reply_to_event_id` is provided, sends the message as a Matrix reply, formatting the content to include quoted original text and appropriate Matrix reply relations. When message interactions (reactions or replies) are enabled in the configuration, stores a mapping between the Meshtastic message ID and the resulting Matrix event ID to enable cross-referencing for future interactions. Prunes old message mappings based on configuration to limit storage.
+    If a reply target is specified, formats the message as a Matrix reply with quoted original content. When message interactions (reactions or replies) are enabled, stores a mapping between the Meshtastic message ID and the resulting Matrix event ID to support cross-network interactions. Prunes old message mappings according to configuration to limit storage.
 
     Parameters:
         room_id (str): The Matrix room ID to send the message to.
@@ -504,9 +497,6 @@ async def matrix_relay(
         emote (bool, optional): Whether to send the message as an emote.
         emoji (bool, optional): Whether the message is an emoji reaction.
         reply_to_event_id (str, optional): The Matrix event ID being replied to, if sending a reply.
-
-    Returns:
-        None
     """
     global config
 
@@ -540,8 +530,8 @@ async def matrix_relay(
                 "Using 'db.msg_map' configuration (legacy). 'database.msg_map' is now the preferred format and 'db.msg_map' will be deprecated in a future version."
             )
     msgs_to_keep = msg_map_config.get(
-        "msgs_to_keep", 500
-    )  # Default is 500 if not specified
+        "msgs_to_keep", DEFAULT_MSGS_TO_KEEP
+    )  # Default from constants
 
     try:
         # Always use our own local meshnet_name for outgoing events
@@ -875,9 +865,9 @@ async def on_room_message(
     event: Union[RoomMessageText, RoomMessageNotice, ReactionEvent, RoomMessageEmote],
 ) -> None:
     """
-    Handle incoming Matrix room messages, reactions, and replies, relaying them to Meshtastic as appropriate.
+    Asynchronously handles incoming Matrix room messages, reactions, and replies, relaying them to Meshtastic as appropriate.
 
-    This function processes Matrix events—including text messages, reactions, and replies—received in configured Matrix rooms. It relays supported messages to the Meshtastic mesh network if broadcasting is enabled, applying message mapping for cross-referencing when reactions or replies are enabled. The function prevents relaying of reactions to reactions, ignores messages from the bot itself or those sent before the bot started, and integrates with plugins for command and message handling. Only messages that are not commands or handled by plugins are forwarded to Meshtastic, with proper formatting and truncation as needed.
+    Processes Matrix events—including text messages, reactions, and replies—in configured rooms. Relays supported messages to the Meshtastic mesh network if broadcasting is enabled, applying message mapping for cross-referencing when reactions or replies are enabled. Ignores messages from the bot itself, messages sent before the bot started, and reactions to reactions. Integrates with plugins for command and message handling; only messages not handled by plugins or identified as commands are forwarded to Meshtastic, with appropriate formatting and truncation. Handles special cases for relaying messages and reactions from remote mesh networks and detection sensor data.
     """
     # Importing here to avoid circular imports and to keep logic consistent
     # Note: We do not call store_message_map directly here for inbound matrix->mesh messages.
@@ -1227,7 +1217,7 @@ async def on_room_message(
     if not found_matching_plugin:
         if config["meshtastic"]["broadcast_enabled"]:
             portnum = event.source["content"].get("meshtastic_portnum")
-            if portnum == "DETECTION_SENSOR_APP":
+            if portnum == DETECTION_SENSOR_APP:
                 # If detection_sensor is enabled, forward this data as detection sensor data
                 if config["meshtastic"].get("detection_sensor", False):
                     success = queue_message(