oscparser 1.1.0__py3-none-any.whl

oscparser/__init__.py

@@ -0,0 +1,70 @@
+"""oscparser - Open Sound Control (OSC) 1.0/1.1 parser library.
+
+This module provides encoding and decoding for OSC packets with support for:
+- OSC 1.0 (UDP and TCP with length-prefixed framing)
+- OSC 1.1 (TCP with SLIP framing)
+
+Basic usage:
+    >>> from oscparser import OSCEncoder, OSCDecoder, OSCMessage, OSCInt, OSCModes, OSCFraming
+    >>> encoder = OSCEncoder(OSCModes.UDP, OSCFraming.OSC10)
+    >>> decoder = OSCDecoder(OSCModes.UDP, OSCFraming.OSC10)
+    >>> msg = OSCMessage(address="/test", args=(OSCInt(42),))
+    >>> encoded = encoder.encode(msg)
+    >>> decoded = list(decoder.feed(encoded))[0]
+"""
+
+from oscparser.decode import OSCDecoder
+from oscparser.encode import OSCEncoder, OSCFraming, OSCModes
+from oscparser.types import (
+    OSC_IMPULSE,
+    OSCRGBA,
+    OSCArg,
+    OSCArray,
+    OSCAtomic,
+    OSCBlob,
+    OSCBundle,
+    OSCChar,
+    OSCDouble,
+    OSCFalse,
+    OSCFloat,
+    OSCImpulse,
+    OSCInt,
+    OSCInt64,
+    OSCMessage,
+    OSCMidi,
+    OSCNil,
+    OSCPacket,
+    OSCString,
+    OSCSymbol,
+    OSCTimeTag,
+    OSCTrue,
+)
+
+__all__ = [
+    "OSCRGBA",
+    "OSC_IMPULSE",
+    "OSCArg",
+    "OSCArray",
+    "OSCAtomic",
+    "OSCBlob",
+    "OSCBundle",
+    "OSCChar",
+    "OSCDecoder",
+    "OSCDouble",
+    "OSCEncoder",
+    "OSCFalse",
+    "OSCFloat",
+    "OSCFraming",
+    "OSCImpulse",
+    "OSCInt",
+    "OSCInt64",
+    "OSCMessage",
+    "OSCMidi",
+    "OSCModes",
+    "OSCNil",
+    "OSCPacket",
+    "OSCString",
+    "OSCSymbol",
+    "OSCTimeTag",
+    "OSCTrue",
+]

oscparser/ctx.py

@@ -0,0 +1,17 @@
+class DataBuffer:
+    def __init__(self, data: bytes):
+        self.data = data
+
+    def startswith(self, prefix: bytes) -> bool:
+        return self.data.startswith(prefix)
+
+    def read(self, n: int) -> bytes:
+        chunk = self.data[:n]
+        self.data = self.data[n:]
+        return chunk
+
+    def write(self, data: bytes) -> None:
+        self.data += data
+
+    def remaining(self) -> int:
+        return len(self.data)

oscparser/decode.py

@@ -0,0 +1,82 @@
+from typing import Iterator, cast
+
+from oscparser.ctx import DataBuffer
+from oscparser.encode import OSCFraming, OSCModes
+from oscparser.framing.framer import Framer
+from oscparser.framing.fullframer import FullFramer
+from oscparser.framing.osc10 import OSC10Framer
+from oscparser.framing.osc11 import OSC11Framer
+from oscparser.processing.osc.handlers import register_osc_handlers
+from oscparser.processing.osc.processing import OSCDispatcher
+from oscparser.types import OSCPacket
+
+
+class OSCDecoder:
+    """Decoder for OSC packets."""
+
+    def __init__(self, mode: OSCModes, framing: OSCFraming):
+        """Initialize the decoder.
+
+        Args:
+            mode: Transport mode, either 'udp' or 'tcp'
+            framing: Framing type, either 'osc10' or 'osc11'
+        """
+        self.framer = self.get_framer(mode, framing)
+        self.decoder = self.get_decoder()
+
+    @staticmethod
+    def get_decoder() -> OSCDispatcher:
+        """Get an OSCDispatcher configured with standard handlers.
+
+        Returns:
+            An OSCDispatcher instance with registered handlers
+        """
+        dispatcher = OSCDispatcher()
+        register_osc_handlers(dispatcher)
+        return dispatcher
+
+    @staticmethod
+    def get_framer(mode: OSCModes, framing: OSCFraming) -> Framer:
+        """Get the appropriate framer class based on mode and framing.
+
+        Args:
+            mode: Transport mode (UDP or TCP)
+            framing: Framing type (OSC10 or OSC11)
+
+        Returns:
+            The corresponding framer instance
+        """
+        if mode == OSCModes.UDP:
+            return FullFramer()
+        elif mode == OSCModes.TCP:
+            if framing == OSCFraming.OSC10:
+                return OSC10Framer()
+            elif framing == OSCFraming.OSC11:
+                return OSC11Framer()
+        raise ValueError("Unsupported mode or framing type")
+
+    def decode(self, data: bytes) -> Iterator[OSCPacket]:
+        """Feed data into the decoder and yield decoded OSC packets.
+
+        For streaming TCP connections where data arrives in chunks.
+
+        Args:
+            data: Raw bytes received from socket
+
+        Yields:
+            Decoded OSC packets
+        """
+        # Unframe the data to get complete OSC packets
+        for packet_data in self.framer.feed(data):
+            # Decode each complete packet
+            data_buffer = DataBuffer(packet_data)
+            handler = self.decoder.get_handler(data_buffer)
+            yield cast(OSCPacket, handler.decode(data_buffer))
+
+    def clear_buffer(self) -> None:
+        """Clear the internal framer buffer.
+
+        Useful when resetting the connection or recovering from errors.
+        """
+        if hasattr(self.framer, "clear_buffer"):
+            self.framer.clear_buffer()

oscparser/encode.py

@@ -0,0 +1,78 @@
+from enum import Enum
+
+from oscparser.ctx import DataBuffer
+from oscparser.framing.framer import Framer
+from oscparser.framing.fullframer import FullFramer
+from oscparser.framing.osc10 import OSC10Framer
+from oscparser.framing.osc11 import OSC11Framer
+from oscparser.processing.osc.handlers import register_osc_handlers
+from oscparser.processing.osc.processing import OSCDispatcher
+from oscparser.types import OSCPacket
+
+
+class OSCModes(Enum):
+    UDP = "udp"
+    TCP = "tcp"
+
+
+class OSCFraming(Enum):
+    OSC10 = "osc10"
+    OSC11 = "osc11"
+
+
+class OSCEncoder:
+    """Encoder for OSC packets."""
+
+    def __init__(self, mode: OSCModes, framing: OSCFraming):
+        """Initialize the framer.
+
+        Args:
+            mode: Transport mode, either 'udp' or 'tcp'
+        """
+        self.framer = self.get_framer(mode, framing)
+        self.encoder = self.get_encoder()
+
+    @staticmethod
+    def get_encoder() -> OSCDispatcher:
+        """Get an OSCDispatcher configured with standard handlers.
+
+        Returns:
+            An OSCDispatcher instance with registered handlers
+        """
+        dispatcher = OSCDispatcher()
+        register_osc_handlers(dispatcher)
+        return dispatcher
+
+    @staticmethod
+    def get_framer(mode: OSCModes, framing: OSCFraming) -> Framer:
+        """Get the appropriate framer class based on mode and framing.
+
+        Args:
+            mode: Transport mode (UDP or TCP)
+            framing: Framing type (OSC10 or OSC11)
+
+        Returns:
+            The corresponding framer class
+        """
+        if mode == OSCModes.UDP:
+            return FullFramer()
+        elif mode == OSCModes.TCP:
+            if framing == OSCFraming.OSC10:
+                return OSC10Framer()
+            elif framing == OSCFraming.OSC11:
+                return OSC11Framer()
+        raise ValueError("Unsupported mode or framing type")
+
+    def encode(self, packet: OSCPacket) -> bytes:
+        """Encode and frame an OSC packet.
+
+        Args:
+            packet: The OSC packet to encode
+        Returns:
+            Framed OSC packet bytes
+        """
+        data_buffer = DataBuffer(b"")
+        handler = self.encoder.get_object_handler(type(packet))
+        handler.encode(packet, data_buffer)
+        framed_packet = self.framer.frame(data_buffer.data)
+        return framed_packet

oscparser/framing/__init__.py

@@ -0,0 +1,6 @@
+"""OSC framing support for OSC 1.0 (UDP) and OSC 1.1 (TCP/SLIP)."""
+
+from oscparser.framing.osc10 import OSC10Framer
+from oscparser.framing.osc11 import OSC11Framer
+
+__all__ = ["OSC10Framer", "OSC11Framer"]

oscparser/framing/framer.py

@@ -0,0 +1,18 @@
+from typing import Iterator, Protocol
+
+
+class Framer(Protocol):
+    """Protocol for OSC framers."""
+
+    @staticmethod
+    def frame(packet: bytes) -> bytes:
+        """Frame an OSC packet for transport."""
+        ...
+
+    def feed(self, data: bytes) -> Iterator[bytes]:
+        """Feed data into the framer and yield complete packets."""
+        ...
+
+    def clear_buffer(self) -> None:
+        """Clear the internal receive buffer."""
+        ...

oscparser/framing/fullframer.py

@@ -0,0 +1,42 @@
+from typing import Iterator
+
+from oscparser.framing.framer import Framer
+
+
+class FullFramer(Framer):
+    """A framer that does not perform any framing.
+
+    This class is useful for protocols that do not require framing,
+    such as UDP transport of OSC packets.
+
+    Complies with the Framer protocol.
+    """
+
+    @staticmethod
+    def frame(packet: bytes) -> bytes:
+        """Return the packet as-is without any framing.
+
+        Args:
+            packet: Raw OSC packet bytes (message or bundle)
+
+        Returns:
+            The same packet bytes without any framing
+        """
+        return packet
+
+    def feed(self, data: bytes) -> Iterator[bytes]:
+        """Yield the incoming data as a complete packet.
+
+        Since there is no framing, each call to feed yields the entire data.
+
+        Args:
+            data: Raw bytes received from transport
+
+        Yields:
+            The entire data as a single OSC packet
+        """
+        yield data
+
+    def clear_buffer(self) -> None:
+        """No internal buffer to clear in this framer."""
+        pass

oscparser/framing/osc10.py

@@ -0,0 +1,70 @@
+"""OSC 1.0 framing for TCP transport.
+
+OSC 1.0 over TCP uses length-prefixed framing: a 4-byte big-endian
+integer indicating the packet size, followed by the packet data.
+"""
+
+import struct
+from typing import Iterator
+
+from oscparser.framing.framer import Framer
+
+
+class OSC10Framer(Framer):
+    """Framer for OSC 1.0 packets over TCP.
+
+    Each packet is prefixed with a 4-byte big-endian size header.
+    Complies with the Framer protocol.
+    """
+
+    def __init__(self):
+        """Initialize the framer with an empty receive buffer."""
+        self._buffer = bytearray()
+
+    @staticmethod
+    def frame(packet: bytes) -> bytes:
+        """Frame an OSC packet for TCP transport.
+
+        OSC 1.0 over TCP uses length-prefixed framing: a 4-byte big-endian
+        integer indicating the packet size, followed by the packet data.
+
+        Args:
+            packet: Raw OSC packet bytes (message or bundle)
+
+        Returns:
+            Length-prefixed packet (4 bytes size + packet data)
+        """
+        size = len(packet)
+        return struct.pack(">I", size) + packet
+
+    def feed(self, data: bytes) -> Iterator[bytes]:
+        """Feed data into the framer and yield complete packets.
+
+        Buffers partial packets and yields complete packets as they arrive.
+
+        Args:
+            data: Raw bytes received from TCP socket
+
+        Yields:
+            Complete OSC packets (without size prefix)
+        """
+        self._buffer.extend(data)
+
+        while len(self._buffer) >= 4:
+            # Read the size prefix
+            size = struct.unpack(">I", bytes(self._buffer[:4]))[0]
+
+            # Check if we have the complete packet
+            if len(self._buffer) < 4 + size:
+                # Not enough data yet
+                break
+
+            # Extract the packet
+            packet = bytes(self._buffer[4 : 4 + size])
+            self._buffer = self._buffer[4 + size :]
+
+            yield packet
+
+    def clear_buffer(self) -> None:
+        """Clear the internal receive buffer."""
+        self._buffer.clear()

oscparser/framing/osc11.py

@@ -0,0 +1,208 @@
+"""OSC 1.1 framing for TCP transport using SLIP encoding.
+
+OSC 1.1 adds support for stream-oriented transports like TCP. Since TCP is a
+byte stream without inherent message boundaries, SLIP (Serial Line Internet
+Protocol) encoding is used to frame OSC packets.
+
+SLIP uses special bytes to delimit packets:
+- END (0xC0): Packet boundary marker
+- ESC (0xDB): Escape byte
+- ESC_END (0xDC): Escaped END byte
+- ESC_ESC (0xDD): Escaped ESC byte
+
+Reference: RFC 1055, OSC 1.1 specification
+"""
+
+from typing import Iterator
+
+from oscparser.framing.framer import Framer
+
+# SLIP protocol constants
+END = b"\xc0"
+ESC = b"\xdb"
+ESC_END = b"\xdc"
+ESC_ESC = b"\xdd"
+
+
+class SLIPError(ValueError):
+    """Exception raised when SLIP protocol violations are detected."""
+
+    pass
+
+
+class OSC11Framer(Framer):
+    """Framer for OSC 1.1 packets over TCP using SLIP encoding.
+
+    This class handles:
+    - Encoding OSC packets with SLIP framing for transmission
+    - Decoding SLIP-framed packets from received byte streams
+    - Buffering partial packets in stream-based reception
+
+    Complies with the Framer protocol.
+    """
+
+    def __init__(self):
+        """Initialize the framer with an empty receive buffer."""
+        self._buffer = bytearray()
+
+    @staticmethod
+    def frame(packet: bytes) -> bytes:
+        """Frame an OSC packet for TCP transport using SLIP encoding.
+
+        The packet is escaped according to SLIP rules and wrapped with END bytes.
+
+        SLIP encoding rules:
+        - Replace ESC with ESC + ESC_ESC
+        - Replace END with ESC + ESC_END
+        - Wrap with END bytes (before and after)
+
+        Args:
+            packet: Raw OSC packet bytes (message or bundle)
+
+        Returns:
+            SLIP-encoded packet ready for transmission
+        """
+        if not packet:
+            packet = b""
+
+        # Escape special bytes
+        encoded = packet.replace(ESC, ESC + ESC_ESC)
+        encoded = encoded.replace(END, ESC + ESC_END)
+
+        # Wrap with END bytes
+        return END + encoded + END
+
+    @staticmethod
+    def _unframe(slip_packet: bytes) -> bytes:
+        """Unframe a single SLIP-encoded packet.
+
+        This decodes one complete SLIP packet. The packet must be a complete,
+        properly framed SLIP packet (starting and ending with END bytes).
+
+        Args:
+            slip_packet: SLIP-encoded packet bytes
+
+        Returns:
+            Decoded OSC packet bytes
+
+        Raises:
+            SLIPError: If the packet is malformed or contains invalid sequences
+        """
+        if not OSC11Framer._is_valid_slip(slip_packet):
+            raise SLIPError(f"Invalid SLIP packet: {slip_packet!r}")
+
+        # Strip END bytes
+        decoded = slip_packet.strip(END)
+
+        # Replace escaped sequences
+        decoded = decoded.replace(ESC + ESC_END, END)
+        decoded = decoded.replace(ESC + ESC_ESC, ESC)
+
+        return decoded
+
+    def feed(self, data: bytes) -> Iterator[bytes]:
+        """Feed data into the framer and yield complete packets.
+
+        This method maintains an internal buffer to handle partial packets.
+        As data arrives, it's buffered until complete SLIP-framed packets
+        can be extracted.
+
+        Args:
+            data: Raw bytes received from TCP socket
+
+        Yields:
+            Complete OSC packets (SLIP-decoded)
+
+        Raises:
+            SLIPError: If malformed SLIP sequences are detected
+        """
+        self._buffer.extend(data)
+
+        while True:
+            # If buffer doesn't start with END, find first END and discard garbage
+            try:
+                first_end = self._buffer.index(END[0])
+                # Discard everything before the first END as garbage/misalignment
+                self._buffer = self._buffer[first_end:]
+            except ValueError:
+                # No END byte found, clear buffer and wait for more data
+                break
+
+            # Now buffer starts with END, find the closing END
+            if len(self._buffer) < 2:
+                # Need at least 2 bytes to have a complete packet
+                break
+
+            try:
+                # Search for closing END (starting from position 1)
+                closing_end = self._buffer.index(END[0], 1)
+            except ValueError:
+                # No closing END found yet, wait for more data
+                break
+
+            # Extract the complete SLIP packet (including both END bytes)
+            slip_packet = bytes(self._buffer[: closing_end + 1])
+            self._buffer = self._buffer[closing_end + 1 :]
+
+            # Skip empty packets (double END bytes - these are packet separators)
+            if slip_packet == END + END:
+                # Add an END back to the buffer to maintain alignment
+                self._buffer.insert(0, END[0])
+                continue
+
+            # Decode and yield the packet
+            try:
+                packet = self._unframe(slip_packet)
+                if packet:  # Only yield non-empty packets
+                    yield packet
+            except SLIPError:
+                # Skip malformed packets and continue processing
+                continue
+
+    def clear_buffer(self) -> None:
+        """Clear the internal receive buffer.
+
+        Useful when resetting the connection or recovering from errors.
+        """
+        self._buffer.clear()
+
+    @staticmethod
+    def _is_valid_slip(packet: bytes) -> bool:
+        """Check if a packet is valid according to SLIP protocol.
+
+        A valid SLIP packet:
+        - Contains no unescaped END bytes except at boundaries
+        - Each ESC byte is followed by ESC_END or ESC_ESC
+        - Does not end with a trailing ESC byte
+
+        Args:
+            packet: SLIP packet to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        # Strip boundary END bytes
+        inner = packet.strip(END)
+
+        # Check for unescaped END bytes in the middle
+        if END[0] in inner:
+            return False
+
+        # Check for trailing ESC
+        if inner.endswith(ESC):
+            return False
+
+        # Check that all ESC bytes are properly followed
+        i = 0
+        while i < len(inner):
+            if inner[i : i + 1] == ESC:
+                if i + 1 >= len(inner):
+                    return False  # ESC at end
+                next_byte = inner[i + 1 : i + 2]
+                if next_byte not in (ESC_END, ESC_ESC):
+                    return False  # Invalid escape sequence
+                i += 2
+            else:
+                i += 1
+
+        return True