better type annotations for sending messages. Closes #171

Author: attwad

pythonosc/osc_message_builder.py

@@ -5,7 +5,11 @@
 from pythonosc import osc_message
 from pythonosc.parsing import osc_types
 
-ArgValue = Union[str, bytes, bool, int, float, osc_types.MidiPacket, list, None]
+# Represents a single OSC argument value.
+# Can be a primitive type, a MIDI packet, or a list/tuple for nested OSC arrays.
+ArgValue = Union[
+    str, bytes, bool, int, float, osc_types.MidiPacket, List[Any], Tuple[Any, ...], None
+]
 
 
 class BuildError(Exception):
@@ -193,7 +197,9 @@ def build(self) -> osc_message.OscMessage:
             raise BuildError(f"Could not build the message: {be}")
 
 
-def build_msg(address: str, value: ArgValue = "") -> osc_message.OscMessage:
+def build_msg(
+    address: str, value: Union[ArgValue, Iterable[ArgValue]] = ""
+) -> osc_message.OscMessage:
     builder = OscMessageBuilder(address=address)
     values: Iterable[Any]
     if value == "":

pythonosc/tcp_client.py

@@ -3,7 +3,7 @@
 import asyncio
 import socket
 import struct
-from typing import AsyncGenerator, Generator, List, Union
+from typing import AsyncGenerator, Generator, Iterable, List, Union
 
 from pythonosc import slip
 from pythonosc.dispatcher import Dispatcher
@@ -104,7 +104,9 @@ class SimpleTCPClient(TCPClient):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
-    def send_message(self, address: str, value: ArgValue = "") -> None:
+    def send_message(
+        self, address: str, value: Union[ArgValue, Iterable[ArgValue]] = ""
+    ) -> None:
         """Build :class:`OscMessage` from arguments and send to server
 
         Args:
@@ -251,7 +253,9 @@ def __init__(
     ):
         super().__init__(address, port, family, mode)
 
-    async def send_message(self, address: str, value: ArgValue = "") -> None:
+    async def send_message(
+        self, address: str, value: Union[ArgValue, Iterable[ArgValue]] = ""
+    ) -> None:
         """Build :class:`OscMessage` from arguments and send to server
 
         Args:

pythonosc/udp_client.py

@@ -91,7 +91,9 @@ def receive(self, timeout: int = 30) -> bytes:
 class SimpleUDPClient(UDPClient):
     """Simple OSC client that automatically builds :class:`OscMessage` from arguments"""
 
-    def send_message(self, address: str, value: ArgValue) -> None:
+    def send_message(
+        self, address: str, value: Union[ArgValue, Iterable[ArgValue]]
+    ) -> None:
         """Build :class:`OscMessage` from arguments and send to server
 
         Args: