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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-osc
-Version: 1.10.2
+Version: 1.10.3
 Summary: Open Sound Control server and client implementations in pure Python
 Keywords: osc,sound,midi,music
 Author: attwad

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.2/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.2"
+version = "1.10.3"
 description = "Open Sound Control server and client implementations in pure Python"
 readme = "README.rst"
 requires-python = ">=3.10"

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

@@ -154,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(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)]:``
+            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]]: ...
+
+        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

{python_osc-1.10.2 → 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.2 → python_osc-1.10.3}/pythonosc/osc_message_builder.py

@@ -200,13 +200,16 @@ class OscMessageBuilder(object):
 
 
 def build_msg(
-    address: str, value: Union[ArgValue, Iterable[ArgValue]] = ""
+    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.2 → python_osc-1.10.3}/pythonosc/osc_server.py

@@ -59,6 +59,9 @@ 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],

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()

python_osc-1.10.3/pythonosc/parsing/framing.py

@@ -0,0 +1,166 @@
+"""OSC message codecs for different framing strategies."""
+
+from abc import ABCMeta, abstractmethod
+from struct import pack, unpack_from
+
+from pythonosc.parsing.slip import (
+    END,
+    decode as slip_decode,
+    encode as slip_encode,
+)
+
+
+class Framing(metaclass=ABCMeta):
+    """Base class for OSC stream framing strategies."""
+
+    @abstractmethod
+    def encode(self, dgram: bytes) -> bytes:
+        """Encode a single OSC datagram for transmission on a byte stream.
+
+        Args:
+            dgram: Raw OSC datagram bytes.
+
+        Returns:
+            The framed byte sequence to write to the stream.
+        """
+
+    @abstractmethod
+    def decode_stream(
+        self, buf: bytes | bytearray, start: int = 0
+    ) -> tuple[list[bytes], int]:
+        """Decode complete OSC datagrams from a byte buffer.
+
+        Args:
+            buf: Bytes received from a stream.
+            start: The index in ``buf`` to start decoding from.
+
+        Returns:
+            A tuple ``(messages, bytes consumed)``.
+        """
+
+
+class SLIPFraming(Framing):
+    """SLIP (RFC 1055) framing for OSC 1.1.
+
+    See the "OSC Delivery Specification 1.1" section from the 2009 NIME paper for details.
+    """
+
+    def encode(self, dgram: bytes) -> bytes:
+        return slip_encode(dgram)
+
+    def decode_stream(
+        self, buf: bytes | bytearray, start: int = 0
+    ) -> tuple[list[bytes], int]:
+        pos = start
+        messages = []
+
+        scan = start
+        while (end := buf.find(END, scan)) >= 0:
+            if end > scan:
+                messages.append(slip_decode(bytes(buf[scan:end])))
+                pos = end + len(END)
+            scan = end + len(END)
+
+        # Consume trailing delimiters, but retain an incomplete packet.
+        if scan == len(buf):
+            pos = scan
+
+        return messages, pos - start
+
+
+class BinaryLengthFraming(Framing):
+    """Length-prefixed framing for OSC 1.0.
+
+    See the "OSC Packets" section from OSC 1.0 Specification for details.
+    """
+
+    def encode(self, dgram: bytes) -> bytes:
+        if dgram:
+            return pack("!I", len(dgram)) + dgram
+        return b""
+
+    def decode_stream(
+        self, buf: bytes | bytearray, start: int = 0
+    ) -> tuple[list[bytes], int]:
+        messages = []
+        pos = start
+
+        while (data_pos := pos + 4) < len(buf):
+            (length,) = unpack_from("!I", buf, pos)
+            end = data_pos + length
+
+            if end > len(buf):
+                break
+
+            messages.append(bytes(buf[data_pos:end]))
+
+            pos = end
+
+        return messages, pos - start
+
+
+class FramingParser:
+    """Stateful stream decoder for (framed) OSC byte stream.
+
+    Not safe for concurrent use.
+
+    Args:
+        framing: Strategy used to decode buffered stream data.
+        max_buffer_size: Maximum size of the internal buffer.
+    """
+
+    __slots__ = ("buf", "start", "framing", "max_buffer_size")
+
+    def __init__(self, framing: Framing, max_buffer_size: int = 1048576) -> None:
+        self.buf = bytearray()
+        self.start = 0
+        self.framing = framing
+        self.max_buffer_size = max_buffer_size
+
+    def feed(self, chunk: bytes | bytearray | memoryview) -> list[bytes]:
+        """Append stream data to the internal buffer and return any complete OSC datagrams.
+
+        Args:
+            chunk: Newly received bytes from the stream.
+
+        Returns:
+            A list of complete, decoded OSC datagrams.
+        """
+
+        new_buf_len = len(self.buf) + len(chunk)
+
+        if (pending := new_buf_len - self.start) > self.max_buffer_size:
+            raise ValueError(f"Buffer is too large: {pending} > {self.max_buffer_size}")
+
+        if new_buf_len > self.max_buffer_size:
+            del self.buf[: self.start]
+            self.start = 0
+
+        self.buf.extend(chunk)
+
+        messages, consumed = self.framing.decode_stream(self.buf, self.start)
+        available = len(self.buf) - self.start
+
+        assert 0 <= consumed <= available, (
+            f"misbehaving framing decoder: {consumed=} {available=}"
+        )
+
+        self.start += consumed
+
+        return messages
+
+    @property
+    def remaining(self) -> bytes:
+        """Return any unparsed bytes."""
+
+        return bytes(self.buf[self.start :])
+
+    def reset(self) -> None:
+        """Clear the internal buffer (discard unparsed data)."""
+
+        del self.buf[:]
+        self.start = 0
+
+
+SLIP_FRAMING: Framing = SLIPFraming()
+BINARY_LENGTH_FRAMING: Framing = BinaryLengthFraming()

{python_osc-1.10.2 → python_osc-1.10.3}/pythonosc/parsing/osc_types.py

@@ -86,6 +86,8 @@ def get_string(dgram: bytes, start_index: int) -> Tuple[str, int]:
 
         data_str = dgram[start_index : start_index + offset]
         return data_str.decode("utf-8"), start_index + total_len
+    except UnicodeDecodeError as error:
+        raise ParseError(f"Could not decode OSC string: {error}") from error
     except IndexError as ie:
         raise ParseError(f"Could not parse datagram {ie}")
     except TypeError as te:
@@ -307,7 +309,7 @@ def get_blob(dgram: bytes, start_index: int) -> Tuple[bytes, int]:
 
     Args:
       dgram: A datagram packet.
-      start_index: An index where the float starts in the datagram.
+      start_index: An index where the blob starts in the datagram.
 
     Returns:
       A tuple containing the blob and the new end index.
@@ -315,13 +317,17 @@ def get_blob(dgram: bytes, start_index: int) -> Tuple[bytes, int]:
     Raises:
       ParseError if the datagram could not be parsed.
     """
-    size, int_offset = get_int(dgram, start_index)
-    # Make the size a multiple of 32 bits.
-    total_size = size + (-size % _BLOB_DGRAM_PAD)
-    end_index = int_offset + size
-    if end_index - start_index > len(dgram[start_index:]):
+    if start_index < 0:
+        raise ParseError("start_index < 0")
+    size, payload_start = get_int(dgram, start_index)
+    if size < 0:
+        raise ParseError("Blob length cannot be negative")
+
+    payload_end = payload_start + size
+    next_index = payload_end + (-size % _BLOB_DGRAM_PAD)
+    if next_index > len(dgram):
         raise ParseError("Datagram is too short.")
-    return dgram[int_offset : int_offset + size], int_offset + total_size
+    return dgram[payload_start:payload_end], next_index
 
 
 def write_blob(val: bytes) -> bytes: