python-osc 1.10.0__tar.gz → 1.10.3__tar.gz

{python_osc-1.10.0 → python_osc-1.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-osc
-Version: 1.10.0
+Version: 1.10.3
 Summary: Open Sound Control server and client implementations in pure Python
 Keywords: osc,sound,midi,music
 Author: attwad
@@ -114,7 +114,7 @@ Simple client
         help="The port the OSC server is listening on")
     args = parser.parse_args()
 
-    client = udp_client.SimpleUDPClient(args.ip, args.port)
+    client = udp_client.SimpleUDPClient(args.ip, args.port, timeout=10)
 
     for x in range(10):
       client.send_message("/filter", random.random())
@@ -158,7 +158,7 @@ Simple server
     dispatcher.map("/logvolume", print_compute_handler, "Log volume", math.log)
 
     server = osc_server.ThreadingOSCUDPServer(
-        (args.ip, args.port), dispatcher)
+        (args.ip, args.port), dispatcher, timeout=10)
     print("Serving on {}".format(server.server_address))
     server.serve_forever()
 

{python_osc-1.10.0 → python_osc-1.10.3}/README.rst

@@ -73,7 +73,7 @@ Simple client
         help="The port the OSC server is listening on")
     args = parser.parse_args()
 
-    client = udp_client.SimpleUDPClient(args.ip, args.port)
+    client = udp_client.SimpleUDPClient(args.ip, args.port, timeout=10)
 
     for x in range(10):
       client.send_message("/filter", random.random())
@@ -117,7 +117,7 @@ Simple server
     dispatcher.map("/logvolume", print_compute_handler, "Log volume", math.log)
 
     server = osc_server.ThreadingOSCUDPServer(
-        (args.ip, args.port), dispatcher)
+        (args.ip, args.port), dispatcher, timeout=10)
     print("Serving on {}".format(server.server_address))
     server.serve_forever()
 

python_osc-1.10.3/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["uv-build"]
+build-backend = "uv_build"
+
+[project]
+name = "python-osc"
+version = "1.10.3"
+description = "Open Sound Control server and client implementations in pure Python"
+readme = "README.rst"
+requires-python = ">=3.10"
+keywords = [
+    "osc",
+    "sound",
+    "midi",
+    "music",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: Freely Distributable",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: System :: Networking",
+]
+dependencies = []
+
+[project.license]
+file = "LICENSE.txt"
+
+[[project.authors]]
+name = "attwad"
+email = "tmusoft@gmail.com"
+
+[project.urls]
+Repository = "https://github.com/attwad/python-osc"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "mypy",
+    "ruff",
+    "pytest-cov",
+    "pre-commit",
+]
+
+[tool.uv.build-backend]
+module-name = "pythonosc"
+module-root = "."
+
+[tool.mypy]
+disallow_subclassing_any = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+scripts_are_modules = true
+warn_unused_configs = true
+enable_error_code = "ignore-without-code"

python_osc-1.10.0/pyproject.toml → python_osc-1.10.3/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "python-osc"
-version = "1.10.0"
+version = "1.10.3"
 description = "Open Sound Control server and client implementations in pure Python"
 readme = "README.rst"
 requires-python = ">=3.10"
@@ -32,6 +32,7 @@ dev = [
     "mypy",
     "ruff",
     "pytest-cov",
+    "pre-commit",
 ]
 
 [tool.uv.build-backend]

{python_osc-1.10.0 → python_osc-1.10.3}/pythonosc/dispatcher.py

@@ -1,5 +1,6 @@
 """Maps OSC addresses to handler functions"""
 
+import asyncio
 import collections
 import inspect
 import logging
@@ -80,6 +81,46 @@ class Handler(object):
             else:
                 return self.callback(message.address, *message)
 
+    async def async_invoke(
+        self, client_address: Tuple[str, int], message: OscMessage
+    ) -> Union[None, AnyStr, Tuple[AnyStr, ArgValue]]:
+        """Invokes the associated callback function (asynchronously)
+
+        Args:
+            client_address: Address match that causes the invocation
+            message: Message causing invocation
+        Returns:
+            The result of the handler function can be None, a string OSC address, or a tuple of the OSC address
+            and arguments.
+        """
+        cb = self.callback
+        is_async = inspect.iscoroutinefunction(cb)
+
+        if self.needs_reply_address:
+            if self.args:
+                if is_async:
+                    return await cb(
+                        client_address, message.address, self.args, *message
+                    )
+                else:
+                    return cb(client_address, message.address, self.args, *message)
+            else:
+                if is_async:
+                    return await cb(client_address, message.address, *message)
+                else:
+                    return cb(client_address, message.address, *message)
+        else:
+            if self.args:
+                if is_async:
+                    return await cb(message.address, self.args, *message)
+                else:
+                    return cb(message.address, self.args, *message)
+            else:
+                if is_async:
+                    return await cb(message.address, *message)
+                else:
+                    return cb(message.address, *message)
+
 
 class Dispatcher(object):
     """Maps Handlers to OSC addresses and dispatches messages to the handler on matched addresses
@@ -87,9 +128,20 @@ class Dispatcher(object):
     Maps OSC addresses to handler functions and invokes the correct handler when a message comes in.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, strict_timing: bool = True) -> None:
+        """Initialize the dispatcher.
+
+        Args:
+            strict_timing: Whether to automatically schedule messages with future timetags.
+                If True (default), the dispatcher will wait (using sleep) until the specified
+                timetag before invoking handlers.
+                If False, messages are dispatched immediately regardless of their timetag.
+                Disabling this can prevent memory/thread accumulation issues when receiving
+                many future-dated messages.
+        """
         self._map: DefaultDict[str, List[Handler]] = collections.defaultdict(list)
         self._default_handler: Optional[Handler] = None
+        self._strict_timing = strict_timing
 
     def map(
         self,
@@ -102,13 +154,15 @@ class Dispatcher(object):
 
         The callback function must have one of the following signatures:
 
-        ``def some_cb(address: str, *osc_args: List[Any]) -> Union[None, AnyStr, Tuple(str, ArgValue)]:``
-        ``def some_cb(address: str, fixed_args: List[Any], *osc_args: List[Any]) -> Union[None, AnyStr,
-                                                                                          Tuple(str, ArgValue)]:``
+        .. code-block:: python
+
+            def some_cb(address: str, *osc_args: ArgValue) -> Union[None, str, Tuple[str, ArgValue]]: ...
+            def some_cb(address: str, fixed_args: List[Any], *osc_args: ArgValue) -> Union[None, str, Tuple[str, ArgValue]]: ...
+            def some_cb(client_address: Tuple[str, int], address: str, *osc_args: ArgValue) -> Union[None, str, Tuple[str, ArgValue]]: ...
+            def some_cb(client_address: Tuple[str, int], address: str, fixed_args: List[Any], *osc_args: ArgValue) -> Union[None, str, Tuple[str, ArgValue]]: ...
 
-        ``def some_cb(client_address: Tuple[str, int], address: str, *osc_args: List[Any]) -> Union[None, AnyStr,
-                                                                                                    Tuple(str, ArgValue)]:``
-        ``def some_cb(client_address: Tuple[str, int], address: str, fixed_args: List[Any], *osc_args: List[Any]) -> Union[None, AnyStr, Tuple(str, ArgValue)]:``
+        Each variadic OSC argument is a single ArgValue, not a list of all arguments.
+        Any fixed arguments passed to map() are collected into the separate fixed_args list.
 
         The callback function can return None, or a string representing an OSC address to be returned to the client,
         or a tuple that includes the address and ArgValue which will be converted to an OSC message and returned to
@@ -240,8 +294,8 @@ class Dispatcher(object):
         matched = False
         for addr, handlers in self._map.items():
             if patterncompiled.match(addr) or (
-                ("*" in addr)
-                and re.match(addr.replace("*", "[^/]*?/*"), address_pattern)
+                "*" in addr
+                and re.match(addr.replace("*", ".*?") + "$", address_pattern)
             ):
                 yield from handlers
                 matched = True
@@ -272,7 +326,7 @@ class Dispatcher(object):
                 if not handlers:
                     continue
                 # If the message is to be handled later, then so be it.
-                if timed_msg.time > now:
+                if self._strict_timing and timed_msg.time > now:
                     time.sleep(timed_msg.time - now)
                 for handler in handlers:
                     result = handler.invoke(client_address, timed_msg.message)
@@ -309,46 +363,13 @@ class Dispatcher(object):
                 if not handlers:
                     continue
                 # If the message is to be handled later, then so be it.
-                if timed_msg.time > now:
-                    time.sleep(timed_msg.time - now)
+                if self._strict_timing and timed_msg.time > now:
+                    await asyncio.sleep(timed_msg.time - now)
                 for handler in handlers:
-                    if inspect.iscoroutinefunction(handler.callback):
-                        if handler.needs_reply_address:
-                            result = await handler.callback(
-                                client_address,
-                                timed_msg.message.address,
-                                handler.args,
-                                *timed_msg.message,
-                            )
-                        elif handler.args:
-                            result = await handler.callback(
-                                timed_msg.message.address,
-                                handler.args,
-                                *timed_msg.message,
-                            )
-                        else:
-                            result = await handler.callback(
-                                timed_msg.message.address, *timed_msg.message
-                            )
-                    else:
-                        if handler.needs_reply_address:
-                            result = handler.callback(
-                                client_address,
-                                timed_msg.message.address,
-                                handler.args,
-                                *timed_msg.message,
-                            )
-                        elif handler.args:
-                            result = handler.callback(
-                                timed_msg.message.address,
-                                handler.args,
-                                *timed_msg.message,
-                            )
-                        else:
-                            result = handler.callback(
-                                timed_msg.message.address, *timed_msg.message
-                            )
-                    if result:
+                    result = await handler.async_invoke(
+                        client_address, timed_msg.message
+                    )
+                    if result is not None:
                         results.append(result)
         except osc_packet.ParseError:
             pass

{python_osc-1.10.0 → python_osc-1.10.3}/pythonosc/osc_bundle.py

@@ -50,6 +50,12 @@ class OscBundle(object):
             while self._dgram[index:]:
                 # Get the sub content size.
                 content_size, index = osc_types.get_int(self._dgram, index)
+                if content_size <= 0 or content_size % 4:
+                    raise ParseError(
+                        "Invalid bundle element size: {}".format(content_size)
+                    )
+                if content_size > len(self._dgram) - index:
+                    raise ParseError("Bundle element exceeds the datagram length")
                 # Get the datagram for the sub content.
                 content_dgram = self._dgram[index : index + content_size]
                 # Increment our position index up to the next possible content.

{python_osc-1.10.0 → python_osc-1.10.3}/pythonosc/osc_message_builder.py

@@ -5,7 +5,11 @@ from typing import Any, Iterable, List, Optional, Tuple, Union
 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):
@@ -68,9 +72,9 @@ class OscMessageBuilder(object):
         """Returns the (type, value) arguments list of this message."""
         return self._args
 
-    def _valid_type(self, arg_type: str) -> bool:
-        if arg_type in self._SUPPORTED_ARG_TYPES:
-            return True
+    def _valid_type(self, arg_type: Union[str, List[Any]]) -> bool:
+        if isinstance(arg_type, str):
+            return arg_type in self._SUPPORTED_ARG_TYPES
         elif isinstance(arg_type, list):
             for sub_type in arg_type:
                 if not self._valid_type(sub_type):
@@ -78,7 +82,9 @@ class OscMessageBuilder(object):
             return True
         return False
 
-    def add_arg(self, arg_value: ArgValue, arg_type: Optional[str] = None) -> None:
+    def add_arg(
+        self, arg_value: ArgValue, arg_type: Optional[Union[str, List[Any]]] = None
+    ) -> None:
         """Add a typed argument to this message.
 
         Args:
@@ -193,12 +199,17 @@ class OscMessageBuilder(object):
             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:
+    """Build a message from a scalar value or an iterable of arguments.
+
+    Omit the value or pass an empty iterable for a message with no arguments.
+    An explicitly supplied empty string is retained as a string argument.
+    """
     builder = OscMessageBuilder(address=address)
     values: Iterable[Any]
-    if value == "":
-        values = []
-    elif not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
+    if not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
         values = [value]
     else:
         values = value

{python_osc-1.10.0 → python_osc-1.10.3}/pythonosc/osc_server.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import os
+import socket
 import socketserver
 from socket import socket as _socket
 from typing import Any, Coroutine, Tuple, Union, cast
@@ -58,11 +59,16 @@ def _is_valid_request(request: _RequestType) -> bool:
 class OSCUDPServer(socketserver.UDPServer):
     """Superclass for different flavors of OSC UDP servers"""
 
+    # Receive complete UDP datagrams instead of socketserver's 8192-byte default.
+    max_packet_size = 65535
+
     def __init__(
         self,
         server_address: Tuple[str, int],
         dispatcher: Dispatcher,
         bind_and_activate: bool = True,
+        timeout: float | None = None,
+        family: socket.AddressFamily | None = None,
     ) -> None:
         """Initialize
 
@@ -70,9 +76,29 @@ class OSCUDPServer(socketserver.UDPServer):
             server_address: IP and port of server
             dispatcher: Dispatcher this server will use
             (optional) bind_and_activate: default=True defines if the server has to start on call of constructor
+            (optional) timeout: Default timeout in seconds for socket operations
+            (optional) family: socket.AF_INET or socket.AF_INET6. If None, it will be inferred from server_address.
         """
+        if family is not None:
+            self.address_family = family
+        else:
+            # Try to infer address family from server_address
+            try:
+                infos = socket.getaddrinfo(
+                    server_address[0],
+                    server_address[1],
+                    type=socket.SOCK_DGRAM,
+                    family=socket.AF_UNSPEC,
+                )
+                if infos:
+                    self.address_family = infos[0][0]
+            except (socket.gaierror, IndexError):
+                # Fallback to default if resolution fails
+                pass
+
         super().__init__(server_address, _UDPHandler, bind_and_activate)
         self._dispatcher = dispatcher
+        self.timeout = timeout
 
     def verify_request(
         self, request: _RequestType, client_address: _AddressType

python_osc-1.10.3/pythonosc/osc_tcp_server.py

@@ -0,0 +1,230 @@
+"""OSC Servers that receive TCP packets and invoke handlers accordingly.
+
+Use like this:
+
+dispatcher = dispatcher.Dispatcher()
+# This will print all parameters to stdout.
+dispatcher.map("/bpm", print)
+server = ForkingOSCTCPServer((ip, port), dispatcher)
+server.serve_forever()
+
+or run the server on its own thread:
+server = ForkingOSCTCPServer((ip, port), dispatcher)
+server_thread = threading.Thread(target=server.serve_forever)
+server_thread.start()
+...
+server.shutdown()
+
+
+Those servers are using the standard socketserver from the standard library:
+http://docs.python.org/library/socketserver.html
+
+
+Alternatively, the AsyncIOOSCTCPServer server can be integrated with an
+asyncio event loop:
+
+loop = asyncio.get_event_loop()
+server = AsyncIOOSCTCPServer(server_address, dispatcher)
+server.serve()
+loop.run_forever()
+
+"""
+
+# mypy: disable-error-code="attr-defined"
+
+import asyncio
+import os
+import socket
+import socketserver
+from typing import Tuple
+
+from pythonosc import osc_message_builder
+from pythonosc.dispatcher import Dispatcher
+from pythonosc.parsing.framing import (
+    BINARY_LENGTH_FRAMING,
+    SLIP_FRAMING,
+    Framing,
+    FramingParser,
+)
+
+MODE_1_0 = "1.0"
+MODE_1_1 = "1.1"
+FRAMING_BY_MODE: dict[str, Framing] = {
+    MODE_1_0: BINARY_LENGTH_FRAMING,
+    MODE_1_1: SLIP_FRAMING,
+}
+
+
+def get_framing(mode: str) -> Framing:
+    try:
+        return FRAMING_BY_MODE[mode]
+    except KeyError:
+        raise ValueError(f"Unsupported OSC mode: {mode}") from None
+
+
+class TCPHandler(socketserver.BaseRequestHandler):
+    """Handles correct OSC messages.
+
+    Whether this will be run on its own thread, the server's or a whole new
+    process depends on the server you instantiated, look at their documentation.
+
+    This method is called after a basic sanity check was done on the datagram,
+    basically whether this datagram looks like an osc message or bundle,
+    if not the server won't even bother to call it and so no new
+    threads/processes will be spawned.
+    """
+
+    def handle(self) -> None:
+        assert isinstance(self.server, OSCTCPServer)
+
+        parser = FramingParser(self.server.framing)
+
+        while chunk := self.request.recv(16384):
+            for p in parser.feed(chunk):
+                resp = self.server.dispatcher.call_handlers_for_packet(
+                    p, self.client_address
+                )
+                for r in resp:
+                    if not isinstance(r, tuple):
+                        r = [r]
+                    msg = osc_message_builder.build_msg(r[0], r[1:])
+                    self.request.sendall(self.server.framing.encode(msg.dgram))
+
+
+class OSCTCPServer(socketserver.TCPServer):
+    """Superclass for different flavors of OSCTCPServer"""
+
+    dispatcher: Dispatcher
+    framing: Framing
+
+    def __init__(
+        self,
+        server_address: Tuple[str | bytes | bytearray, int],
+        dispatcher: Dispatcher,
+        mode: str = MODE_1_1,
+        family: socket.AddressFamily | None = None,
+    ):
+        self.request_queue_size = 300
+        self.dispatcher = dispatcher
+        self.framing = get_framing(mode)
+
+        if family is not None:
+            self.address_family = family
+        elif isinstance(server_address[0], str):
+            # Try to infer address family from server_address
+            try:
+                infos = socket.getaddrinfo(
+                    server_address[0],
+                    server_address[1],
+                    type=socket.SOCK_STREAM,
+                    family=socket.AF_UNSPEC,
+                )
+                if infos:
+                    self.address_family = infos[0][0]
+            except (socket.gaierror, IndexError):
+                # Fallback to default if resolution fails
+                pass
+
+        super().__init__(server_address, TCPHandler)
+
+
+class BlockingOSCTCPServer(OSCTCPServer):
+    """Blocking version of the TCP server.
+
+    Each message will be handled sequentially on the same thread.
+    Use this is you don't care about latency in your message handling or don't
+    have a multiprocess/multithread environment (really?).
+    """
+
+
+class ThreadingOSCTCPServer(socketserver.ThreadingMixIn, OSCTCPServer):
+    """Threading version of the OSC TCP server.
+
+    Each message will be handled in its own new thread.
+    Use this when lightweight operations are done by each message handlers.
+    """
+
+
+if hasattr(os, "fork"):
+
+    class ForkingOSCTCPServer(socketserver.ForkingMixIn, OSCTCPServer):
+        """Forking version of the OSC TCP server.
+
+        Each message will be handled in its own new process.
+        Use this when heavyweight operations are done by each message handlers
+        and forking a whole new process for each of them is worth it.
+        """
+
+
+class AsyncOSCTCPServer:
+    """Asyncio version of the OSC TCP Server.
+    Each TCP message is handled by _call_handlers_for_packet, the same method as in the
+    OSCTCPServer family of blocking, threading, and forking servers
+    """
+
+    def __init__(
+        self,
+        server_address: str,
+        port: int,
+        dispatcher: Dispatcher,
+        mode: str = MODE_1_1,
+    ):
+        """
+        :param server_address: tuple of (IP address to bind to, port)
+        :param dispatcher: a pythonosc.dispatcher.Dispatcher
+        """
+        self._port = port
+        self._server_address = server_address
+        self.dispatcher = dispatcher
+        self.framing = get_framing(mode)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.stop()
+
+    async def start(self) -> None:
+        """creates a socket endpoint and registers it with our event loop"""
+        self._server = await asyncio.start_server(
+            self.handle, self._server_address, self._port
+        )
+
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        self._server.close()
+        await self._server.wait_closed()
+
+    async def handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            await self._handle(reader, writer)
+        finally:
+            if writer.can_write_eof():
+                writer.write_eof()
+            writer.close()
+            await writer.wait_closed()
+
+    async def _handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        parser = FramingParser(self.framing)
+        client_address = ("", 0)
+        sock = writer.transport.get_extra_info("socket")
+        if sock is not None:
+            client_address = sock.getpeername()
+
+        while chunk := await reader.read(16384):
+            for p in parser.feed(chunk):
+                result = await self.dispatcher.async_call_handlers_for_packet(
+                    p, client_address
+                )
+                for r in result:
+                    if not isinstance(r, tuple):
+                        r = [r]
+                    msg = osc_message_builder.build_msg(r[0], r[1:])
+                    writer.write(self.framing.encode(msg.dgram))
+                    await writer.drain()