mmrelay 1.2.2__tar.gz → 1.2.3__tar.gz

{mmrelay-1.2.2/src/mmrelay.egg-info → mmrelay-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.2.2
+Version: 1.2.3
 Summary: Bridge between Meshtastic mesh networks and Matrix chat rooms
 Home-page: https://github.com/jeremiah-k/meshtastic-matrix-relay
 Author: Geoff Whittington, Jeremiah K., and contributors

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/__init__.py

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

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/cli.py

@@ -238,11 +238,11 @@ def print_version():
 def _validate_e2ee_dependencies():
     """
     Check whether end-to-end encryption (E2EE) is usable on the current platform.
-    
+
     Returns:
         bool: True if the platform is supported and required E2EE libraries can be imported;
         False otherwise.
-    
+
     Notes:
         - This function performs only local checks (platform and importability) and does not perform
           network I/O.
@@ -1499,13 +1499,13 @@ def handle_auth_logout(args):
 def handle_service_command(args):
     """
     Dispatch service-related subcommands.
-    
+
     Currently supports the "install" subcommand which imports and runs mmrelay.setup_utils.install_service().
     Returns 0 on successful installation, 1 on failure or for unknown subcommands.
-    
+
     Parameters:
         args: argparse.Namespace with a `service_command` attribute indicating the requested action.
-    
+
     Returns:
         int: Exit code (0 on success, 1 on error).
     """
@@ -1526,13 +1526,13 @@ def _diagnose_config_paths(args):
     """
     Print a diagnostic summary of resolved configuration file search paths and their directory accessibility.
     
-    Uses get_config_paths(args) to compute the ordered list of candidate config file locations, then prints each path with a concise directory status icon:
+    Computes the ordered list of candidate config file locations via get_config_paths(args) and prints each path with a short directory status icon:
     - ✅ directory exists and is writable
     - ⚠️ directory exists but is not writable
     - ❌ directory does not exist
     
     Parameters:
-        args (argparse.Namespace): Parsed CLI arguments used to determine the config search order.
+        args (argparse.Namespace): CLI arguments used to determine the config search order (passed to get_config_paths).
     """
     print("1. Testing configuration paths...")
     from mmrelay.config import get_config_paths
@@ -1551,11 +1551,11 @@ def _diagnose_config_paths(args):
 def _diagnose_sample_config_accessibility():
     """
     Check availability of the bundled sample configuration and print a short diagnostic.
-    
+
     Performs two non-destructive checks and prints human-readable results:
     1) Verifies whether the sample config file exists at the path returned by mmrelay.tools.get_sample_config_path().
     2) Attempts to read the embedded resource "sample_config.yaml" from the mmrelay.tools package via importlib.resources and reports success and the content length.
-    
+
     Returns:
         bool: True if a filesystem sample config exists at the resolved path; False otherwise.
     """
@@ -1586,18 +1586,19 @@ def _diagnose_sample_config_accessibility():
 
 def _diagnose_platform_specific(args):
     """
-    Run platform-specific diagnostic checks.
+    Run platform-specific diagnostic checks and report results.
     
-    On Windows, imports and runs Windows-specific requirement checks and a configuration-generation
-    test from mmrelay.windows_utils, printing per-component results and any warnings. On non-Windows
-    platforms this reports that platform-specific tests are not required.
+    On Windows, attempts to import and run Windows-specific requirement checks and a
+    configuration-generation test, printing per-component statuses and any warnings.
+    On non-Windows platforms this reports that platform-specific tests are not
+    required.
     
     Parameters:
-        args (argparse.Namespace): Parsed CLI arguments; passed through to the Windows
-            config-generation test when running on Windows.
+        args (argparse.Namespace): CLI arguments passed through to the Windows
+            configuration-generation test (only used when running on Windows).
     
     Returns:
-        bool: True if the platform is Windows (Windows checks were executed), False otherwise.
+        bool: True if Windows checks were executed (running on Windows), False otherwise.
     """
     print("3. Platform-specific diagnostics...")
     import sys
@@ -1704,7 +1705,7 @@ logging:
 def _diagnose_minimal_config_template():
     """
     Validate the built-in minimal YAML configuration template and print a concise pass/fail status.
-    
+
     Attempts to parse the string returned by _get_minimal_config_template() using yaml.safe_load. Prints a single-line result showing a ✅ with the template character length when the template is valid YAML, or a ❌ with the YAML parsing error when invalid. This is a non-destructive diagnostic helper that prints output and does not return a value.
     """
     print("4. Testing minimal config template fallback...")
@@ -1722,13 +1723,13 @@ def handle_config_diagnose(args):
     """
     Run non-destructive diagnostics for the MMRelay configuration subsystem and print a human-readable report.
     
-    Performs four checks: resolves candidate config paths and reports directory accessibility; verifies packaged sample config availability (filesystem and importlib.resources fallback); runs platform-specific diagnostics (Windows-focused where applicable); and validates the built-in minimal YAML template. Prints findings and suggested next steps to stdout/stderr.
+    Performs four checks without modifying user files: (1) resolves and reports candidate configuration file paths and their directory accessibility, (2) verifies availability of the packaged sample configuration, (3) runs platform-specific diagnostics (Windows checks when applicable), and (4) validates the built-in minimal YAML configuration template. Results and actionable guidance are written to stdout/stderr.
     
     Parameters:
-        args (argparse.Namespace): Parsed CLI arguments used to resolve config search paths and to control platform-specific checks.
+        args (argparse.Namespace): Parsed CLI arguments used to resolve configuration search paths and to control platform-specific checks.
     
     Returns:
-        int: Exit code (0 on success, 1 on failure).
+        int: Exit code (0 on success, 1 on failure). On failure an error summary is printed to stderr.
     """
     print("MMRelay Configuration System Diagnostics")
     print("=" * 40)

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/config.py

@@ -196,14 +196,14 @@ def get_log_dir():
 
 def get_e2ee_store_dir():
     """
-    Return the absolute path to the E2EE data store directory, creating it if missing.
+    Return the absolute path to the application's end-to-end-encryption (E2EE) data store directory, creating it if missing.
     
     On Linux and macOS this is "<base_dir>/store" where base_dir is returned by get_base_dir().
-    On Windows this is "<custom_data_dir>/store" when module-level custom_data_dir is set; otherwise it uses
+    On Windows this is "<custom_data_dir>/store" when module-level custom_data_dir is set; otherwise it is
     platformdirs.user_data_dir(APP_NAME, APP_AUTHOR)/store.
     
     Returns:
-        str: Absolute path to the ensured store directory. The directory is created if it does not exist.
+        str: Absolute path to the ensured store directory.
     """
     if sys.platform in ["linux", "darwin"]:
         # Use ~/.mmrelay/store/ for Linux and Mac
@@ -388,12 +388,12 @@ def is_e2ee_enabled(config):
 def check_e2ee_enabled_silently(args=None):
     """
     Check silently whether End-to-End Encryption (E2EE) is enabled in the first readable configuration file.
-    
+
     Searches candidate configuration paths returned by get_config_paths(args) in priority order, loads the first readable YAML file, and returns True if that configuration enables E2EE (via is_e2ee_enabled). I/O and YAML parsing errors are ignored and the function continues to the next candidate. On Windows this always returns False.
-    
+
     Parameters:
         args (optional): Parsed command-line arguments that can influence config search order.
-    
+
     Returns:
         bool: True if E2EE is enabled in the first valid configuration file found; otherwise False.
     """
@@ -493,16 +493,16 @@ def load_credentials():
 def save_credentials(credentials):
     """
     Persist a JSON-serializable credentials mapping to <base_dir>/credentials.json.
-    
+
     Writes the provided credentials (a JSON-serializable mapping) to the application's
     base configuration directory as credentials.json, creating the base directory if
     necessary. On Unix-like systems the file permissions are adjusted to be
     restrictive (0o600) when possible. I/O and permission errors are caught and
     logged; the function does not raise them.
-    
+
     Parameters:
         credentials (dict): JSON-serializable mapping of credentials to persist.
-    
+
     Returns:
         None
     """
@@ -822,18 +822,18 @@ def load_config(config_file=None, args=None):
 def validate_yaml_syntax(config_content, config_path):
     """
     Validate YAML text for syntax and common style issues, parse it with PyYAML, and return results.
-    
+
     Performs lightweight line-based checks for frequent mistakes (using '=' instead of ':'
     for mappings and non-standard boolean words like 'yes'/'no' or 'on'/'off') and then
     attempts to parse the content with yaml.safe_load. If only style warnings are found,
     parsing is considered successful and warnings are returned; if parsing fails or true
     syntax errors are detected, a detailed error message is returned that references
     config_path to identify the source.
-    
+
     Parameters:
         config_content (str): Raw YAML text to validate.
         config_path (str): Path or label used in error messages to identify the source of the content.
-    
+
     Returns:
         tuple:
             is_valid (bool): True if YAML parsed successfully (style warnings allowed), False on syntax/parsing error.

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/e2ee_utils.py

@@ -80,8 +80,13 @@ def get_e2ee_status(
         importlib.import_module("olm")
 
         if os.getenv("MMRELAY_TESTING") != "1":
-            importlib.import_module("nio.crypto").OlmDevice
-            importlib.import_module("nio.store").SqliteStore
+            nio_crypto = importlib.import_module("nio.crypto")
+            if not hasattr(nio_crypto, "OlmDevice"):
+                raise ImportError("nio.crypto.OlmDevice is unavailable")
+
+            nio_store = importlib.import_module("nio.store")
+            if not hasattr(nio_store, "SqliteStore"):
+                raise ImportError("nio.store.SqliteStore is unavailable")
 
         status["dependencies_installed"] = True
     except ImportError:

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/main.py

@@ -154,9 +154,9 @@ async def main(config):
 
     async def shutdown():
         """
-        Signal the application to shut down.
+        Signal the application to begin shutdown.
         
-        Sets the Meshtastic shutdown flag and triggers the local shutdown event so tasks waiting on that event can begin shutdown/cleanup. This coroutine only signals shutdown; it does not close clients or perform cleanup itself.
+        Sets the Meshtastic shutdown flag and triggers the local shutdown event so any coroutines waiting on that event can start their cleanup. This coroutine only signals shutdown; it does not perform client shutdown or resource cleanup itself.
         """
         matrix_logger.info("Shutdown signal received. Closing down...")
         meshtastic_utils.shutting_down = True  # Set the shutting_down flag

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/matrix_utils.py

@@ -113,15 +113,15 @@ def _is_room_alias(value: Any) -> bool:
 def _iter_room_alias_entries(mapping):
     """
     Yield (alias_or_id, setter) pairs for entries in a Matrix room mapping.
-    
+
     Each yielded tuple contains:
     - alias_or_id (str): the room alias or room ID found in the entry (may be an alias starting with '#' or a canonical room ID). If a dict entry has no `"id"` key, an empty string is yielded.
     - setter (callable): a function accepting a single argument `new_id` which updates the underlying mapping in-place to replace the alias with the resolved room ID.
-    
+
     Supports two mapping shapes:
     - list: items may be strings (alias/ID) or dicts with an `"id"` key.
     - dict: values may be strings (alias/ID) or dicts with an `"id"` key.
-    
+
     The setter updates the original collection (list element or dict value) so callers can resolve aliases and persist resolved IDs back into the provided mapping.
     """
 
@@ -150,13 +150,13 @@ def _iter_room_alias_entries(mapping):
 async def _resolve_aliases_in_mapping(mapping, resolver):
     """
     Resolve Matrix room alias entries found in a mapping (list or dict) by calling an async resolver and replacing aliases with resolved room IDs in-place.
-    
+
     This function iterates entries produced by _iter_room_alias_entries(mapping). For each entry whose key/value looks like a Matrix room alias (a string starting with '#'), it awaits the provided resolver coroutine with the alias; if the resolver returns a truthy room ID, the corresponding entry in the original mapping is updated via the entry's setter. If mapping is not a list or dict, the function logs a warning and returns without modifying anything.
-    
+
     Parameters:
         mapping (list|dict): A mapping of Matrix rooms where some entries may be aliases (e.g., "#room:example.org").
         resolver (Callable[[str], Awaitable[Optional[str]]]): Async callable that accepts an alias and returns a resolved room ID (or falsy on failure).
-    
+
     Returns:
         None
     """
@@ -178,12 +178,12 @@ async def _resolve_aliases_in_mapping(mapping, resolver):
 def _update_room_id_in_mapping(mapping, alias, resolved_id) -> bool:
     """
     Replace a room alias with its resolved room ID in a mapping.
-    
+
     Parameters:
         mapping (list|dict): A matrix_rooms mapping represented as a list of aliases or a dict of entries; only list and dict types are supported.
         alias (str): The room alias to replace (e.g., "#room:server").
         resolved_id (str): The canonical room ID to substitute for the alias (e.g., "!abcdef:server").
-    
+
     Returns:
         bool: True if the alias was found and replaced with resolved_id; False if the mapping type is unsupported or the alias was not present.
     """
@@ -789,29 +789,18 @@ def bot_command(command, event):
 
 async def connect_matrix(passed_config=None):
     """
-    Create and initialize a matrix-nio AsyncClient connected to the configured Matrix homeserver, optionally enabling End-to-End Encryption (E2EE).
-
-    This routine selects credentials in the following order:
-    1. credentials.json (preferred; restores full session including device_id and E2EE store).
-    2. Automatic login using username/password from the provided config (saved to credentials.json on success).
-    3. Direct token-based values from the config matrix section.
-
-    Behavior summary:
-    - Validates presence of a top-level "matrix_rooms" configuration and raises ValueError if missing.
-    - Builds an AsyncClient with a certifi-backed SSL context when available.
-    - When E2EE is enabled in configuration and dependencies are present, prepares the encryption store, restores session state, and uploads device keys if needed.
-    - Performs an initial full_state sync and resolves room aliases configured as aliases to room IDs.
-    - Populates module-level globals used elsewhere (e.g., matrix_client, bot_user_name, matrix_homeserver, matrix_rooms, matrix_access_token, bot_user_id).
-    - Returns the initialized AsyncClient instance ready for use.
-
+    Create and initialize a matrix-nio AsyncClient connected to the configured Matrix homeserver.
+    
+    Attempts credential selection in this order: credentials.json (preferred), automatic login using username/password from config (saved to credentials.json), then direct token values from config. Optionally enables End-to-End Encryption (E2EE) when configured and dependencies are available. Performs an initial full-state sync, resolves configured room aliases to room IDs, sets module-level connection state (matrix_client, bot_user_name, matrix_homeserver, matrix_rooms, matrix_access_token, bot_user_id) and returns the ready AsyncClient.
+    
     Parameters:
-        passed_config (dict | None): Optional configuration to use for this connection attempt. If provided, it replaces the module-level config for this call.
-
+        passed_config (dict | None): Optional configuration to use for this connection attempt; if provided, it overrides the module-level config for this call.
+    
     Returns:
-        AsyncClient | None: An initialized matrix-nio AsyncClient on success, or None if connection cannot be established due to missing configuration/credentials.
-
+        AsyncClient | None: An initialized matrix-nio AsyncClient on success, or None if connection/credentials are unavailable.
+    
     Raises:
-        ValueError: If the top-level "matrix_rooms" configuration is missing from the (effective) config.
+        ValueError: If the required top-level "matrix_rooms" configuration is missing.
         ConnectionError: If the initial Matrix sync fails or times out.
     """
     global matrix_client, bot_user_name, matrix_homeserver, matrix_rooms, matrix_access_token, bot_user_id, config
@@ -1010,8 +999,15 @@ async def connect_matrix(passed_config=None):
                     # Also check for other required E2EE dependencies unless tests skip them
                     if os.getenv("MMRELAY_TESTING") != "1":
                         try:
-                            from nio.crypto import OlmDevice as _OlmDevice
-                            from nio.store import SqliteStore as _SqliteStore
+                            nio_crypto = importlib.import_module("nio.crypto")
+                            if not hasattr(nio_crypto, "OlmDevice"):
+                                raise ImportError("nio.crypto.OlmDevice is unavailable")
+
+                            nio_store = importlib.import_module("nio.store")
+                            if not hasattr(nio_store, "SqliteStore"):
+                                raise ImportError(
+                                    "nio.store.SqliteStore is unavailable"
+                                )
 
                             logger.debug("All E2EE dependencies are available")
                         except ImportError:
@@ -1034,6 +1030,10 @@ async def connect_matrix(passed_config=None):
                             "Skipping additional E2EE dependency imports in test mode"
                         )
 
+                    if e2ee_enabled:
+                        # Ensure nio still receives a store path even when dependency
+                        # checks are skipped (e.g. production runs without MMRELAY_TESTING);
+                        # without this the client will not load encryption state.
                         # Get store path from config or use default
                         if (
                             "encryption" in config["matrix"]
@@ -1050,8 +1050,6 @@ async def connect_matrix(passed_config=None):
                                 config["matrix"]["e2ee"]["store_path"]
                             )
                         else:
-                            from mmrelay.config import get_e2ee_store_dir
-
                             e2ee_store_path = get_e2ee_store_dir()
 
                         # Create store directory if it doesn't exist
@@ -1215,7 +1213,7 @@ async def connect_matrix(passed_config=None):
             async def _resolve_alias(alias: str) -> Optional[str]:
                 """
                 Resolve a Matrix room alias to its canonical room ID.
-                
+
                 Attempts to resolve the provided room alias using the module's Matrix client. Returns the resolved room ID string on success; returns None if the alias cannot be resolved or if an error/timeout occurs (errors from the underlying nio client are caught and handled internally).
                 """
                 logger.debug(f"Resolving alias from config: {alias}")
@@ -1778,17 +1776,17 @@ async def login_matrix_bot(
 async def join_matrix_room(matrix_client, room_id_or_alias: str) -> None:
     """
     Join the bot to a Matrix room by ID or alias.
-    
+
     Resolves a room alias (e.g. "#room:server") to its canonical room ID, updates the in-memory
     matrix_rooms mapping with the resolved ID (if available), and attempts to join the resolved
     room ID. No-op if the client is already joined to the room. Errors during alias resolution
     or join are caught and logged; the function does not raise exceptions.
-    
+
     Parameters documented only where meaning is not obvious:
         room_id_or_alias (str): A Matrix room identifier, either a canonical room ID (e.g. "!abc:server")
             or a room alias (starts with '#'). When an alias is provided, it will be resolved and
             the resolved room ID will be used for joining and recorded in the module's matrix_rooms mapping.
-    
+
     Returns:
         None
     """
@@ -2221,12 +2219,12 @@ def strip_quoted_lines(text: str) -> str:
 async def get_user_display_name(room, event):
     """
     Return the display name for the event sender, preferring a room-specific name.
-    
+
     If the room provides a per-room display name for the sender, that name is returned.
     Otherwise the function performs an asynchronous lookup against the homeserver for the
     user's global display name and returns it if present. If no display name is available,
     the sender's Matrix ID (MXID) is returned.
-    
+
     Returns:
         str: A human-readable display name or the sender's MXID.
     """
@@ -2320,15 +2318,17 @@ async def send_reply_to_meshtastic(
     reply_id=None,
 ):
     """
-    Enqueue a Matrix reply for transmission over Meshtastic, either as a structured reply or a regular broadcast.
+    Enqueue a Matrix reply to be sent over Meshtastic, either as a structured reply targeting an existing Meshtastic message or as a regular broadcast.
     
-    If Meshtastic broadcasting is disabled the function returns without action. When storage_enabled is True the function will create a mapping entry (using event.event_id and room.room_id) and attach it to the queued message when possible. If reply_id is provided the message is sent as a structured reply targeting that Meshtastic message ID; otherwise it is sent as a regular text broadcast. Failures are logged; the function does not raise on enqueue errors.
-    Parameters that add non-obvious context:
-        room_config (dict): Room-specific configuration — must include "meshtastic_channel" (an integer channel index).
-        room: Matrix room object (room.room_id is used for mapping metadata).
-        event: Matrix event object (event.event_id is used for mapping metadata).
-        storage_enabled (bool): When True, attempt to create and attach a message-mapping record to the queued item.
-        reply_id (int | None): If provided, send as a structured reply targeting this Meshtastic message ID.
+    If Meshtastic broadcasting is disabled this is a no-op. When storage_enabled is True the function will create a mapping entry (using event.event_id and room.room_id) and attach it to the queued message for later reply/reaction correlation. Failures are logged; the function does not raise exceptions.
+    
+    Parameters:
+        room_config (dict): Room-specific configuration — must include "meshtastic_channel" (integer channel index).
+        room: Matrix room object; room.room_id is used to build mapping metadata.
+        event: Matrix event object; event.event_id is used to build mapping metadata.
+        storage_enabled (bool): If True, create and attach a message-mapping record to the queued Meshtastic message.
+        reply_id (int | None): If provided, send as a structured Meshtastic reply targeting this message ID; otherwise send a regular text broadcast.
+        local_meshnet_name (str | None): Name of the local meshnet used in mapping metadata.
     """
     loop = asyncio.get_running_loop()
     meshtastic_interface = await loop.run_in_executor(None, connect_meshtastic)
@@ -2433,19 +2433,19 @@ async def handle_matrix_reply(
     meshnet_name=None,
 ):
     """
-    Relay a Matrix reply back to Meshtastic when the replied-to Matrix event maps to a Meshtastic message.
+    Handle a Matrix reply by forwarding it to Meshtastic when the replied-to Matrix event maps to a Meshtastic message.
     
-    If the replied-to Matrix event has a stored Meshtastic mapping, format a Meshtastic reply preserving sender attribution and queue it as a reply that references the original Meshtastic message ID. If no mapping exists, do nothing and return False so normal Matrix processing can continue.
+    If the Matrix event identified by reply_to_event_id has an associated Meshtastic mapping, this function formats a Meshtastic reply that preserves sender attribution and enqueues it referencing the original Meshtastic message ID. If no mapping exists, it returns False so normal Matrix processing can continue.
     
     Parameters:
-        reply_to_event_id (str): Matrix event ID being replied to; used to locate the corresponding Meshtastic mapping.
-        storage_enabled (bool): If True, message mappings may be created/updated when sending the reply.
-        local_meshnet_name (str): Local meshnet name used to determine cross-meshnet reply formatting.
+        reply_to_event_id (str): Matrix event ID being replied to; used to locate the Meshtastic mapping.
+        storage_enabled (bool): Whether message mappings/storage are enabled (affects created mapping behavior when sending).
+        local_meshnet_name (str): Local meshnet name used to determine formatting when replying across meshnets.
         config (dict): Relay configuration passed to formatting routines.
-        mesh_text_override (str | None): Optional override text to send to Meshtastic instead of derived text.
-        longname (str | None): Sender long display name used for prefixing in the Meshtastic message.
-        shortname (str | None): Sender short display name used for prefixing in the Meshtastic message.
-        meshnet_name (str | None): Remote meshnet name of the original Matrix/meshtastic mapping (if any).
+        mesh_text_override (str | None): Optional text to send instead of derived text.
+        longname (str | None): Sender long display name used for prefixing.
+        shortname (str | None): Sender short display name used for prefixing.
+        meshnet_name (str | None): Remote meshnet name associated with the original mapping, if any.
     
     Returns:
         bool: True if a mapping was found and the reply was queued to Meshtastic; False if no mapping existed and nothing was sent.
@@ -2546,7 +2546,7 @@ async def on_room_message(
 ) -> None:
     """
     Handle an incoming Matrix room event and, when applicable, relay it to Meshtastic.
-    
+
     Processes text, notice, emote, and reaction events (including replies and messages relayed from other meshnets) for configured rooms. Behavior highlights:
     - Ignores events from before the bot started and events sent by the bot itself.
     - Uses per-room configuration and global interaction settings to decide whether to process or ignore the event.
@@ -2554,12 +2554,12 @@ async def on_room_message(
     - Bridges Matrix replies to Meshtastic replies when a corresponding Meshtastic mapping is found and replies are enabled.
     - Relays regular Matrix messages to Meshtastic using configured prefix/truncation rules; handles special detection-sensor port forwarding.
     - Integrates with the plugin system; plugins may consume or modify messages. Messages identified as bot commands are not relayed to Meshtastic.
-    
+
     Side effects:
     - May enqueue Meshtastic send operations (text or data) via the internal queue.
     - May read/write persistent message mappings to support reaction/reply bridging.
     - May call Matrix APIs (e.g., to fetch display names).
-    
+
     Returns:
     - None
     """

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/meshtastic_utils.py

@@ -44,8 +44,17 @@ from mmrelay.constants.network import (
     CONNECTION_TYPE_TCP,
     DEFAULT_BACKOFF_TIME,
     ERRNO_BAD_FILE_DESCRIPTOR,
-INFINITE_RETRIES,
+    INFINITE_RETRIES,
 )
+from mmrelay.db_utils import (
+    get_longname,
+    get_message_map_by_meshtastic_id,
+    get_shortname,
+    save_longname,
+    save_shortname,
+)
+from mmrelay.log_utils import get_logger
+from mmrelay.runtime_utils import is_running_as_service
 
 # Maximum number of timeout retries when retries are configured as infinite.
 MAX_TIMEOUT_RETRIES_INFINITE = 5
@@ -62,16 +71,6 @@ except ImportError:
         pass
 
 
-from mmrelay.db_utils import (
-    get_longname,
-    get_message_map_by_meshtastic_id,
-    get_shortname,
-    save_longname,
-    save_shortname,
-)
-from mmrelay.log_utils import get_logger
-from mmrelay.runtime_utils import is_running_as_service
-
 # Global config variable that will be set from config.py
 config = None
 
@@ -153,15 +152,15 @@ def _submit_coro(coro, loop=None):
 def _resolve_plugin_timeout(cfg: dict | None, default: float = 5.0) -> float:
     """
     Resolve and return a positive plugin timeout value from the given configuration.
-    
+
     Attempts to read meshtastic.plugin_timeout from cfg and convert it to a positive float.
     If the value is missing, non-numeric, or not greater than 0, the provided default is returned.
     Invalid or non-positive values will cause a warning to be logged.
-    
+
     Parameters:
         cfg (dict | None): Configuration mapping that may contain a "meshtastic" section.
         default (float): Fallback timeout (seconds) used when cfg does not provide a valid value.
-    
+
     Returns:
         float: A positive timeout in seconds.
     """
@@ -270,13 +269,13 @@ def serial_port_exists(port_name):
 def connect_meshtastic(passed_config=None, force_connect=False):
     """
     Establish and return a Meshtastic client connection (serial, BLE, or TCP), with configurable retries, exponential backoff, and single-time event subscription.
-    
+
     Attempts to (re)connect using the module configuration and updates module-level state on success (meshtastic_client, matrix_rooms, and event subscriptions). Supports the legacy "network" alias for TCP, verifies serial port presence before connecting, and honors a retry limit (or infinite retries when unspecified). On successful connection the client's node info and firmware metadata are probed and message/connection-lost handlers are subscribed once for the process lifetime.
-    
+
     Parameters:
         passed_config (dict, optional): If provided, replaces the module-level configuration (and may update matrix_rooms).
         force_connect (bool, optional): When True, forces creating a new connection even if one already exists.
-    
+
     Returns:
         The connected Meshtastic client instance on success, or None if connection cannot be established or shutdown is in progress.
     """
@@ -464,7 +463,7 @@ def connect_meshtastic(passed_config=None, force_connect=False):
                     subscribed_to_connection_lost = True
                     logger.debug("Subscribed to meshtastic.connection.lost")
 
-        except (ConnectionRefusedError, MemoryError) as e:
+        except (ConnectionRefusedError, MemoryError):
             # Handle critical errors that should not be retried
             logger.exception("Critical connection error")
             return None
@@ -1142,17 +1141,17 @@ def sendTextReply(
 ):
     """
     Send a Meshtastic text reply that references a previous Meshtastic message.
-    
+
     Builds a Data payload containing `text` and `reply_id`, wraps it in a MeshPacket on `channelIndex`,
     and sends it using the provided Meshtastic interface.
-    
+
     Parameters:
         text (str): UTF-8 text to send.
         reply_id (int): ID of the Meshtastic message being replied to.
         destinationId (int | str, optional): Recipient address or node ID (defaults to broadcast).
         wantAck (bool, optional): If True, request an acknowledgement for the packet.
         channelIndex (int, optional): Channel index to send the packet on.
-    
+
     Returns:
         The result returned by the interface's _sendPacket call (typically the sent MeshPacket), or
         None if the interface is not available or sending fails.

{mmrelay-1.2.2 → mmrelay-1.2.3}/src/mmrelay/message_queue.py

@@ -473,11 +473,11 @@ class MessageQueue:
 
     def _should_send_message(self) -> bool:
         """
-        Return True if it is currently safe to send a message via Meshtastic.
+        Return True when it is safe to send a Meshtastic message; otherwise False.
         
-        Performs runtime checks: ensures the global reconnecting flag is not set, a Meshtastic client object is available, and — if the client exposes `is_connected` (callable or boolean) — that it reports connected. Returns False if any check fails.
+        Performs runtime checks: verifies the module-level `reconnecting` flag is False, a Meshtastic client object exists, and — if the client exposes `is_connected` (callable or boolean) — that it reports connected. If any check fails the method returns False.
         
-        If importing the Meshtastic utilities raises ImportError, the method will asynchronously stop this MessageQueue and return False.
+        If importing the Meshtastic utilities raises ImportError, the queue will be stopped asynchronously and the method returns False.
         """
         # Import here to avoid circular imports
         try:
@@ -517,18 +517,18 @@ class MessageQueue:
 
     def _handle_message_mapping(self, result, mapping_info):
         """
-        Persist a sent message mapping (mesh message id → Matrix event) and optionally prune old mappings.
+        Persist a sent mesh-to-Matrix message mapping and optionally prune old mappings.
         
-        If mapping_info contains 'matrix_event_id', 'room_id', and 'text', stores a mapping using result.id as the mesh message id. If 'msgs_to_keep' is present and > 0 it prunes older mappings to retain that many entries; otherwise DEFAULT_MSGS_TO_KEEP is used.
+        If mapping_info contains 'matrix_event_id', 'room_id', and 'text', this stores a mapping using result.id as the mesh message id. If 'msgs_to_keep' is present and > 0 it prunes older mappings to retain that many entries; otherwise DEFAULT_MSGS_TO_KEEP is used.
         
         Parameters:
-            result: Send function result object with an `id` attribute (the mesh message id).
+            result: An object returned by the send function with an `id` attribute (the mesh message id).
             mapping_info (dict): Mapping details. Relevant keys:
-                - matrix_event_id (str)
-                - room_id (str)
-                - text (str)
-                - meshnet (optional): passed to the store operation
-                - msgs_to_keep (optional, int): number of mappings to retain for pruning
+                - matrix_event_id (str): Matrix event ID to map to.
+                - room_id (str): Matrix room ID where the event was sent.
+                - text (str): Message text to associate with the mapping.
+                - meshnet (optional): Mesh network identifier passed through to storage.
+                - msgs_to_keep (optional, int): Number of mappings to retain when pruning.
         """
         try:
             # Import here to avoid circular imports