Reformat help texts (#90)

* Use asyncio.all_tasks() again to check if relay is active

* Add missing type hints

* Add Arguments class with typed properties

* Reformat help texts

* Unify punctuation

* Print help arg last

* Re-add print_help()

* Rearrange help args

* Update docs to v0.7.1

* Bump version

Author: quaxalber

README.md

@@ -151,7 +151,7 @@ Follow these steps to install and configure the project:
                 └─5869 python3.11 /home/user/bluetooth_2_usb/bluetooth_2_usb.py --auto_discover --grab_devices
 
     Dec 13 10:33:00 pi0w systemd[1]: Started bluetooth_2_usb.service - Bluetooth to USB HID relay.
-    Dec 13 10:33:06 pi0w bluetooth_2_usb[5869]: 23-12-13 10:33:06 [INFO] Launching Bluetooth 2 USB v0.7.0
+    Dec 13 10:33:06 pi0w bluetooth_2_usb[5869]: 23-12-13 10:33:06 [INFO] Launching Bluetooth 2 USB v0.7.1
     Dec 13 10:33:06 pi0w bluetooth_2_usb[5869]: 23-12-13 10:33:06 [INFO] Discovering input devices...
     Dec 13 10:33:09 pi0w bluetooth_2_usb[5869]: 23-12-13 10:33:09 [INFO] Activated relay for device /dev/input/event2, name "AceRK Mouse", phys "b8:27:eb:be:dc:81"
     Dec 13 10:33:09 pi0w bluetooth_2_usb[5869]: 23-12-13 10:33:09 [INFO] Activated relay for device /dev/input/event1, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81"
@@ -182,26 +182,29 @@ Currently you can provide the following CLI arguments:
 
 ```console
 user@pi0w:~ $ bluetooth_2_usb -h
-usage: bluetooth_2_usb.py [-h] [--device_ids DEVICE_IDS] [--auto_discover] [--debug] [--log_to_file] [--log_path LOG_PATH]
-                          [--version] [--list_devices] [--grab_devices]
+usage: bluetooth_2_usb.py [--device_ids DEVICE_IDS] [--auto_discover] [--grab_devices] [--list_devices] [--log_to_file] [--log_path LOG_PATH] [--debug] [--version] [--help]
 
-Bluetooth to USB HID relay. Handles Bluetooth keyboard and mouse events from multiple input devices and translates them to
-USB using Linux's gadget mode.
+Bluetooth to USB HID relay. Handles Bluetooth keyboard and mouse events from multiple input devices and translates them to USB using Linux's gadget mode.
 
 options:
-  -h, --help            show this help message and exit
   --device_ids DEVICE_IDS, -i DEVICE_IDS
-                        Comma-separated list of identifiers for input devices to be relayed. An identifier is either the
-                        input device path, the MAC address or any case-insensitive substring of the device name. Default is
-                        None. Example: --device_ids '/dev/input/event2,a1:b2:c3:d4:e5:f6,0A-1B-2C-3D-4E-5F,logi'
+                        Comma-separated list of identifiers for input devices to be relayed.
+                        An identifier is either the input device path, the MAC address or any case-insensitive substring of the device name.
+                        Example: --device_ids '/dev/input/event2,a1:b2:c3:d4:e5:f6,0A-1B-2C-3D-4E-5F,logi'
+                        Default: None
   --auto_discover, -a   Enable auto-discovery mode. All readable input devices will be relayed automatically.
-  --debug, -d           Enable debug mode. Increases log verbosity
-  --log_to_file, -f     Add a handler that logs to file additionally to stdout.
+                        Default: disabled
+  --grab_devices, -g    Grab the input devices, i.e., suppress any events on your relay device.
+                        Devices are not grabbed by default.
+  --list_devices, -l    List all available input devices and exit.
+  --log_to_file, -f     Add a handler that logs to file, additionally to stdout.
   --log_path LOG_PATH, -p LOG_PATH
-                        The path of the log file. Default is /var/log/bluetooth_2_usb/bluetooth_2_usb.log.
+                        The path of the log file
+                        Default: /var/log/bluetooth_2_usb/bluetooth_2_usb.log
+  --debug, -d           Enable debug mode (Increases log verbosity)
+                        Default: disabled
   --version, -v         Display the version number of this software and exit.
-  --list_devices, -l    List all available input devices and exit.
-  --grab_devices, -g    Grab the input devices, i.e., suppress any events on your relay device (RPi).
+  --help, -h            Show this help message and exit.
 ```
 
 ### 5.3. Consuming the API from your Python code
@@ -373,7 +376,7 @@ Here's a few things you could try:
   user@pi0w:~ $ sudo service bluetooth_2_usb stop && sudo bluetooth_2_usb -ad ; sudo service bluetooth_2_usb start
   23-12-12 13:03:28 [DEBUG] CLI args: Namespace(device_ids=None, auto_discover=True, debug=True, log_to_file=False, log_path='/var/log/bluetooth_2_usb/bluetooth_2_usb.log', version=False, list_devices=False)
   23-12-12 13:03:28 [DEBUG] Logging to stdout
-  23-12-12 13:03:28 [INFO] Launching Bluetooth 2 USB v0.7.0
+  23-12-12 13:03:28 [INFO] Launching Bluetooth 2 USB v0.7.1
   23-12-12 13:03:28 [INFO] Discovering input devices...
   23-12-12 13:03:28 [DEBUG] Auto-discovery enabled. Relaying all input devices.
   23-12-12 13:03:28 [DEBUG] Initializing USB gadgets...

bluetooth_2_usb.py

@@ -13,7 +13,7 @@
 
 
 _logger = get_logger()
-_VERSION = "0.7.0"
+_VERSION = "0.7.1"
 _VERSIONED_NAME = f"Bluetooth 2 USB v{_VERSION}"
 
 

src/bluetooth_2_usb/args.py

@@ -1,12 +1,84 @@
-from argparse import Namespace
 import argparse
 import atexit
 import sys
+from typing import Optional, List
 
 from usb_hid import disable
 
 
 class CustomArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, add_help=False, **kwargs)
+        self.register("action", "help", _HelpAction)  # Register the help action
+
+    def add_arguments(self):
+        self.add_argument(
+            "--device_ids",
+            "-i",
+            type=lambda input: [item.strip() for item in input.split(",")],
+            default=None,
+            help="Comma-separated list of identifiers for input devices to be relayed.\nAn identifier is either the input device path, the MAC address or any case-insensitive substring of the device name.\nExample: --device_ids '/dev/input/event2,a1:b2:c3:d4:e5:f6,0A-1B-2C-3D-4E-5F,logi'\nDefault: None",
+        )
+        self.add_argument(
+            "--auto_discover",
+            "-a",
+            action="store_true",
+            default=False,
+            help="Enable auto-discovery mode. All readable input devices will be relayed automatically.\nDefault: disabled",
+        )
+        self.add_argument(
+            "--grab_devices",
+            "-g",
+            action="store_true",
+            default=False,
+            help="Grab the input devices, i.e., suppress any events on your relay device.\nDevices are not grabbed by default.",
+        )
+        self.add_argument(
+            "--list_devices",
+            "-l",
+            action="store_true",
+            default=False,
+            help="List all available input devices and exit.",
+        )
+        self.add_argument(
+            "--log_to_file",
+            "-f",
+            action="store_true",
+            default=False,
+            help="Add a handler that logs to file, additionally to stdout.",
+        )
+        self.add_argument(
+            "--log_path",
+            "-p",
+            type=str,
+            default="/var/log/bluetooth_2_usb/bluetooth_2_usb.log",
+            help="The path of the log file\nDefault: /var/log/bluetooth_2_usb/bluetooth_2_usb.log",
+        )
+        self.add_argument(
+            "--debug",
+            "-d",
+            action="store_true",
+            default=False,
+            help="Enable debug mode (Increases log verbosity)\nDefault: disabled",
+        )
+        self.add_argument(
+            "--version",
+            "-v",
+            action="store_true",
+            default=False,
+            help="Display the version number of this software and exit.",
+        )
+
+    def add_help_argument(self):
+        # Add the help argument last
+        self.add_argument(
+            "--help",
+            "-h",
+            action="help",
+            default=argparse.SUPPRESS,
+            help="Show this help message and exit.",
+        )
+
     def print_help(self) -> None:
         """
         When the script is run with help or version flag, we need to unregister usb_hid.disable() from atexit
@@ -16,76 +88,99 @@ def print_help(self) -> None:
         super().print_help()
 
 
-def parse_args() -> Namespace:
+class _HelpAction(argparse._HelpAction):
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser.print_help()
+        parser.exit()
+
+
+class Arguments:
+    __slots__ = [
+        "_device_ids",
+        "_auto_discover",
+        "_grab_devices",
+        "_list_devices",
+        "_log_to_file",
+        "_log_path",
+        "_debug",
+        "_version",
+    ]
+
+    def __init__(
+        self,
+        device_ids: Optional[List[str]],
+        auto_discover: bool,
+        grab_devices: bool,
+        list_devices: bool,
+        log_to_file: bool,
+        log_path: str,
+        debug: bool,
+        version: bool,
+    ):
+        self._device_ids = device_ids
+        self._auto_discover = auto_discover
+        self._grab_devices = grab_devices
+        self._list_devices = list_devices
+        self._log_to_file = log_to_file
+        self._log_path = log_path
+        self._debug = debug
+        self._version = version
+
+    @property
+    def device_ids(self) -> Optional[List[str]]:
+        return self._device_ids
+
+    @property
+    def auto_discover(self) -> bool:
+        return self._auto_discover
+
+    @property
+    def grab_devices(self) -> bool:
+        return self._grab_devices
+
+    @property
+    def list_devices(self) -> bool:
+        return self._list_devices
+
+    @property
+    def log_to_file(self) -> bool:
+        return self._log_to_file
+
+    @property
+    def log_path(self) -> str:
+        return self._log_path
+
+    @property
+    def debug(self) -> bool:
+        return self._debug
+
+    @property
+    def version(self) -> bool:
+        return self._version
+
+
+def parse_args() -> Arguments:
     parser = CustomArgumentParser(
         description="Bluetooth to USB HID relay. Handles Bluetooth keyboard and mouse events from multiple input devices and translates them to USB using Linux's gadget mode.",
+        formatter_class=argparse.RawTextHelpFormatter,
     )
 
-    parser.add_argument(
-        "--device_ids",
-        "-i",
-        type=lambda input: [item.strip() for item in input.split(",")],
-        default=None,
-        help="Comma-separated list of identifiers for input devices to be relayed.\n\n \
-          An identifier is either the input device path, the MAC address or any case-insensitive substring of the device name.\n\n \
-          Default is None.\n\n \
-          Example: --device_ids '/dev/input/event2,a1:b2:c3:d4:e5:f6,0A-1B-2C-3D-4E-5F,logi'",
-    )
-    parser.add_argument(
-        "--auto_discover",
-        "-a",
-        action="store_true",
-        default=False,
-        help="Enable auto-discovery mode. All readable input devices will be relayed automatically.",
-    )
-    parser.add_argument(
-        "--debug",
-        "-d",
-        action="store_true",
-        default=False,
-        help="Enable debug mode. Increases log verbosity",
-    )
-    parser.add_argument(
-        "--log_to_file",
-        "-f",
-        action="store_true",
-        default=False,
-        help="Add a handler that logs to file additionally to stdout. ",
-    )
-    parser.add_argument(
-        "--log_path",
-        "-p",
-        type=str,
-        default="/var/log/bluetooth_2_usb/bluetooth_2_usb.log",
-        help="The path of the log file. Default is /var/log/bluetooth_2_usb/bluetooth_2_usb.log.",
-    )
-    parser.add_argument(
-        "--version",
-        "-v",
-        action="store_true",
-        default=False,
-        help="Display the version number of this software and exit.",
-    )
-    parser.add_argument(
-        "--list_devices",
-        "-l",
-        action="store_true",
-        default=False,
-        help="List all available input devices and exit.",
-    )
-    parser.add_argument(
-        "--grab_devices",
-        "-g",
-        action="store_true",
-        default=False,
-        help="Grab the input devices, i.e., suppress any events on your relay device (RPi).",
-    )
-
+    parser.add_arguments()
+    parser.add_help_argument()
     args = parser.parse_args()
 
     # Check if no arguments were provided
     if len(sys.argv) == 1:
         parser.print_help()
         sys.exit(1)
 
-    return args
+    return Arguments(
+        device_ids=args.device_ids,
+        auto_discover=args.auto_discover,
+        grab_devices=args.grab_devices,
+        list_devices=args.list_devices,
+        log_to_file=args.log_to_file,
+        log_path=args.log_path,
+        debug=args.debug,
+        version=args.version,
+    )

src/bluetooth_2_usb/relay.py

@@ -11,10 +11,10 @@
 from usb_hid import Device
 
 from .evdev import (
+    evdev_to_usb_hid,
     get_mouse_movement,
     is_consumer_key,
     is_mouse_button,
-    evdev_to_usb_hid,
 )
 from .logging import get_logger
 
@@ -49,7 +49,7 @@ def init_usb_gadgets() -> None:
     _logger.debug(f"Enabled USB gadgets: {usb_hid.devices}")
 
 
-def all_gadgets_ready():
+def all_gadgets_ready() -> bool:
     return all(
         dev is not None for dev in (_keyboard_gadget, _mouse_gadget, _consumer_gadget)
     )
@@ -73,10 +73,10 @@ def normalized_value(self) -> str:
     def type(self) -> str:
         return self._type
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.value
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'{self.type} "{self.value}"'
 
     def _determine_identifier_type(self) -> str:
@@ -106,7 +106,7 @@ def matches(self, device: InputDevice) -> bool:
 
 
 class DeviceRelay:
-    def __init__(self, input_device: InputDevice, grab_device: bool = False):
+    def __init__(self, input_device: InputDevice, grab_device: bool = False)->None:
         self._input_device = input_device
         if grab_device:
             self._input_device.grab()
@@ -117,10 +117,10 @@ def __init__(self, input_device: InputDevice, grab_device: bool = False):
     def input_device(self) -> InputDevice:
         return self._input_device
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"relay for {self.input_device.name}"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"relay for {self.input_device}"
 
     async def async_relay_events_loop(self) -> NoReturn:
@@ -236,13 +236,13 @@ def _create_task(self, device: InputDevice, task_group: TaskGroup) -> None:
     async def _async_relay_events(self, device: InputDevice) -> NoReturn:
         try:
             relay = DeviceRelay(device, self._grab_devices)
-            _logger.info(f"Activated {repr(relay)}")
+            _logger.info(f"Activated {relay!r}")
             await relay.async_relay_events_loop()
         except CancelledError:
             self._cancelled = True
             _logger.critical(f"{device.name} was cancelled")
         except (OSError, FileNotFoundError) as ex:
-            _logger.critical(f"Connection to {device.name} lost [{repr(ex)}]")
+            _logger.critical(f"Connection to {device.name} lost [{ex!r}]")
         except Exception:
             _logger.exception(f"{device.name} failed!")
             await asyncio.sleep(1)