oscparser 1.1.0__py3-none-any.whl

oscparser/processing/osc/handlers.py

@@ -0,0 +1,165 @@
+import struct
+from typing import Any, cast
+
+from oscparser.ctx import DataBuffer
+from oscparser.processing.args.args import (
+    ArgDispatcher,
+    _decode_string,
+    _encode_string,
+    create_arg_dispatcher,
+)
+from oscparser.processing.osc.processing import OSCDispatcher, OSCPacketHandler
+from oscparser.types import OSCArg, OSCBundle, OSCMessage
+
+_BUNDLE_PREFIX = b"#bundle\x00"
+
+
+class OSCBundleHandler(OSCPacketHandler[OSCBundle]):
+    """Handler for OSC bundles - timetag + nested elements."""
+
+    def __init__(self, dispatcher: OSCDispatcher):
+        self.dispatcher = dispatcher
+
+    @classmethod
+    def from_dispatcher(cls, dispatcher: OSCDispatcher, arg_dispatcher: ArgDispatcher) -> "OSCBundleHandler":
+        return cls(dispatcher)
+
+    def decode(self, ctx: DataBuffer) -> OSCBundle:
+        """Decode an OSC bundle from data buffer.
+
+        Format:
+        - Bundle prefix "#bundle\\x00"
+        - Timetag (64-bit NTP timestamp)
+        - Elements (size + content pairs)
+        """
+        # Read and verify bundle prefix
+        prefix = ctx.read(len(_BUNDLE_PREFIX))
+        if prefix != _BUNDLE_PREFIX:
+            raise ValueError(f"Invalid bundle prefix: {prefix!r}")
+
+        # Read timetag (64-bit big-endian integer)
+        timetag = struct.unpack(">Q", ctx.read(8))[0]
+
+        # Parse bundle elements
+        elements: list[Any] = []
+
+        while ctx.remaining() > 0:
+            # Read element size (32-bit big-endian integer)
+            element_size = struct.unpack(">I", ctx.read(4))[0]
+
+            # Read element data
+            element_data = DataBuffer(ctx.read(element_size))
+
+            # Recursively decode the element using dispatcher
+            handler = self.dispatcher.get_handler(element_data)
+            element = handler.decode(element_data)
+
+            elements.append(element)
+
+        return OSCBundle(timetag=timetag, elements=tuple(elements))
+
+    def encode(self, packet: OSCBundle, buf: DataBuffer):
+        """Encode an OSC bundle to bytes."""
+        if not isinstance(packet, OSCBundle):
+            raise TypeError(f"Expected OSCBundle, got {type(packet)}")
+
+        # Write bundle prefix
+        buf.write(_BUNDLE_PREFIX)
+
+        # Write timetag
+        buf.write(struct.pack(">Q", packet.timetag))
+
+        # Encode each element
+        for element in packet.elements:
+            # Recursively encode element
+            result = DataBuffer(b"")
+            element_handler = self.dispatcher.get_object_handler(type(element))
+            element_handler.encode(element, result)
+            # Write element size
+            buf.write(struct.pack(">I", len(result.data)))
+
+            # Write element data
+            buf.write(result.data)
+
+
+class OSCMessageHandler(OSCPacketHandler[OSCMessage]):
+    """Handler for OSC messages - address pattern + typed arguments."""
+
+    def __init__(self, dispatcher: OSCDispatcher, arg_dispatcher: ArgDispatcher):
+        self.dispatcher = dispatcher
+        # Use the arg dispatcher for handling individual arguments
+        self.arg_dispatcher = arg_dispatcher if arg_dispatcher is not None else create_arg_dispatcher()
+
+    @classmethod
+    def from_dispatcher(cls, dispatcher: OSCDispatcher, arg_dispatcher: ArgDispatcher) -> "OSCMessageHandler":
+        return cls(dispatcher, arg_dispatcher)
+
+    def decode(self, ctx: DataBuffer) -> OSCMessage:
+        """Decode an OSC message from data buffer.
+
+        Format:
+        - Address pattern (string)
+        - Type tag string (string starting with ',')
+        - Arguments (based on type tags)
+        """
+        # Parse address pattern
+        address = _decode_string(ctx)
+
+        # Check if there are any bytes remaining
+        if ctx.remaining() == 0:
+            # No arguments
+            return OSCMessage(address=address, args=())
+
+        # Parse type tag string
+        type_tag_string = _decode_string(ctx)
+
+        if not type_tag_string.startswith(","):
+            raise ValueError(f"Type tag string must start with ',': {type_tag_string!r}")
+
+        # Remove the leading comma
+        type_tags = type_tag_string[1:]
+
+        # Parse arguments based on type tags
+        args: list[OSCArg] = []
+
+        typetag_ctx = DataBuffer(type_tags.encode("utf-8"))
+
+        while typetag_ctx.remaining() > 0:
+            tag = typetag_ctx.read(1)
+
+            handler = self.arg_dispatcher.get_handler_by_tag(tag)
+            arg = cast(OSCArg, handler.decode(ctx, typetag_ctx))
+            args.append(arg)
+
+        return OSCMessage(address=address, args=tuple(args))
+
+    def encode(self, packet: OSCMessage, buf: DataBuffer):
+        """Encode an OSC message to bytes."""
+        if not isinstance(packet, OSCMessage):
+            raise TypeError(f"Expected OSCMessage, got {type(packet)}")
+
+        # Encode address pattern
+        buf.write(_encode_string(packet.address))
+
+        # Build type tag string and argument data
+        typetag_ctx = DataBuffer(b"")
+        args_ctx = DataBuffer(b"")
+
+        # Start type tag string with comma
+        typetag_ctx.write(b",")
+
+        for arg in packet.args:
+            handler = self.arg_dispatcher.get_handler_by_object(type(arg))
+            handler.encode(arg, args_ctx, typetag_ctx)
+
+        # Write type tag string
+        buf.write(_encode_string(typetag_ctx.data.decode("utf-8")))
+
+        # Write argument data
+        buf.write(args_ctx.data)
+
+
+def register_osc_handlers(dispatcher: OSCDispatcher) -> None:
+    """Register OSC message and bundle handlers."""
+    dispatcher.register_handler(OSCMessage, b"/", OSCMessageHandler)
+    dispatcher.register_handler(OSCBundle, b"#bundle\x00", OSCBundleHandler)

oscparser/processing/osc/processing.py

@@ -0,0 +1,46 @@
+from typing import Any, Protocol
+
+from oscparser.ctx import DataBuffer
+from oscparser.processing.args.args import create_arg_dispatcher
+from oscparser.processing.args.proccessing import ArgDispatcher
+
+
+class OSCPacketHandler[T: object = object](Protocol):
+    """Protocol for OSC packet handlers (messages and bundles)."""
+
+    @classmethod
+    def from_dispatcher(cls, dispatcher: "OSCDispatcher", arg_dispatcher: ArgDispatcher) -> "OSCPacketHandler[T]": ...
+
+    def decode(self, ctx: DataBuffer) -> T:
+        """Decode OSC packet from data buffer."""
+        ...
+
+    def encode(self, packet: T, buf: DataBuffer):
+        """Encode OSC packet to bytes."""
+        ...
+
+
+class OSCDispatcher:
+    """Dispatcher for OSC packet types (messages and bundles)."""
+
+    def __init__(self, arg_dispatcher: ArgDispatcher | None = None):
+        self._handlers: dict[bytes, OSCPacketHandler[Any]] = {}
+        self._object_handlers: dict[type, OSCPacketHandler[Any]] = {}
+        self._arg_dispatcher = arg_dispatcher if arg_dispatcher is not None else create_arg_dispatcher()
+
+    def register_handler[T: object](self, obj: type[T], handler_tag: bytes, handler: type[OSCPacketHandler[T]]) -> None:
+        """Register a packet handler."""
+        handler_inst = handler.from_dispatcher(self, self._arg_dispatcher)
+        self._handlers[handler_tag] = handler_inst
+        self._object_handlers[obj] = handler_inst
+
+    def get_handler(self, data: DataBuffer) -> OSCPacketHandler:
+        """Get appropriate handler for the given data."""
+        for handler_tag, handler in self._handlers.items():
+            if data.startswith(handler_tag):
+                return handler
+        raise ValueError("No handler found")
+
+    def get_object_handler[T](self, obj: type[T]) -> OSCPacketHandler[T]:
+        """Get handler for the given object type."""
+        return self._object_handlers[obj]

oscparser/types.py

@@ -0,0 +1,263 @@
+"""OSC 1.0 / 1.1 data types.
+
+This module defines Python classes and type aliases that model the
+Open Sound Control 1.0 atomic types, composite types (messages and
+bundles), and the additional recommended argument tags listed in the
+specification (often referred to as "OSC 1.1").
+
+It does **not** implement parsing or encoding; it is purely types.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import ClassVar, Tuple, Union
+
+from pydantic import BaseModel
+
+
+class _FrozenModel(BaseModel):
+    """Base class for immutable OSC value types."""
+
+    class Config:
+        frozen = True
+
+
+class OSCInt(_FrozenModel):
+    """32-bit signed integer argument (tag 'i')."""
+
+    TAG: ClassVar[str] = "i"
+    value: int
+
+    def __init__(self, value: int) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCFloat(_FrozenModel):
+    """32-bit IEEE 754 floating point argument (tag 'f')."""
+
+    TAG: ClassVar[str] = "f"
+    value: float
+
+    def __init__(self, value: float) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCString(_FrozenModel):
+    """OSC string argument (tag 's')."""
+
+    TAG: ClassVar[str] = "s"
+    value: str
+
+    def __init__(self, value: str) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCBlob(_FrozenModel):
+    """OSC blob argument (tag 'b')."""
+
+    TAG: ClassVar[str] = "b"
+    value: bytes
+
+    def __init__(self, value: bytes) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCTrue(_FrozenModel):
+    """Boolean true argument (tag 'T')."""
+
+    TAG: ClassVar[str] = "T"
+
+
+class OSCFalse(_FrozenModel):
+    """Boolean false argument (tag 'F')."""
+
+    TAG: ClassVar[str] = "F"
+
+
+class OSCNil(_FrozenModel):
+    """Nil / null argument (tag 'N')."""
+
+    TAG: ClassVar[str] = "N"
+
+
+class OSCInt64(_FrozenModel):
+    """64-bit signed integer argument (tag 'h')."""
+
+    TAG: ClassVar[str] = "h"
+    value: int
+
+    def __init__(self, value: int) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCDouble(_FrozenModel):
+    """64-bit IEEE 754 floating point argument (tag 'd')."""
+
+    TAG: ClassVar[str] = "d"
+    value: float
+
+    def __init__(self, value: float) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCTimeTag(_FrozenModel):
+    """OSC timetag argument (tag 't'), represented as a datetime."""
+
+    TAG: ClassVar[str] = "t"
+    value: datetime
+
+    def __init__(self, value: datetime) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCChar(_FrozenModel):
+    """Single ASCII / UTF-8 character argument (tag 'c')."""
+
+    TAG: ClassVar[str] = "c"
+    value: str  # usually length 1
+
+    def __init__(self, value: str) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCSymbol(_FrozenModel):
+    """Symbol argument (tag 'S'), semantically distinct from a string."""
+
+    TAG: ClassVar[str] = "S"
+    value: str
+
+    def __init__(self, value: str) -> None:
+        super().__init__(value=value)  # type: ignore
+
+
+class OSCRGBA(_FrozenModel):
+    """RGBA color argument (tag 'r')."""
+
+    TAG: ClassVar[str] = "r"
+    r: int
+    g: int
+    b: int
+    a: int
+
+
+class OSCMidi(_FrozenModel):
+    """MIDI message argument (tag 'm').
+
+    Bytes from MSB to LSB are:
+    - port_id
+    - status
+    - data1
+    - data2
+    """
+
+    TAG: ClassVar[str] = "m"
+
+    port_id: int
+    status: int
+    data1: int
+    data2: int
+
+
+class OSCImpulse(_FrozenModel):
+    """Impulse / infinitum / bang argument (tag 'I').
+
+    There is no payload; the presence of this value is the data.
+    """
+
+    TAG: ClassVar[str] = "I"
+
+    # No fields
+    pass
+
+
+# Singleton instance that can be reused for all impulse arguments.
+OSC_IMPULSE = OSCImpulse()
+
+
+class OSCArray(_FrozenModel):
+    """Array argument (tags '[' ... ']').
+
+    Contains a sequence of other OSC arguments, which may themselves be
+    arrays (nested arrays are allowed by the 1.0 spec).
+    """
+
+    OPEN_TAG: ClassVar[str] = "["
+    CLOSE_TAG: ClassVar[str] = "]"
+    items: tuple["OSCArg", ...]
+
+    def __init__(self, items: tuple["OSCArg", ...]) -> None:
+        super().__init__(items=items)  # type: ignore
+
+
+# === Composite packet types (messages and bundles) ===
+
+
+OSCAtomic = Union[
+    OSCInt,
+    OSCFloat,
+    OSCString,
+    OSCBlob,
+    OSCTrue,
+    OSCFalse,
+    OSCNil,
+    OSCInt64,
+    OSCDouble,
+    OSCTimeTag,
+    OSCChar,
+    OSCSymbol,
+    OSCRGBA,
+    OSCMidi,
+    OSCImpulse,
+]
+
+OSCArg = Union[OSCAtomic, OSCArray]
+
+
+class OSCMessage(_FrozenModel):
+    """OSC message: address pattern + typed argument list.
+
+    - ``address`` is an OSC Address Pattern beginning with '/'.
+    - ``args`` is a sequence of OSCArg values.
+    """
+
+    address: str
+    args: Tuple[OSCArg, ...]
+
+
+class OSCBundle(_FrozenModel):
+    """OSC bundle containing messages and/or sub-bundles.
+
+    - ``timetag`` is a 64-bit OSC timetag (NTP). 0 means "immediately".
+    - ``elements`` is a sequence of OSCMessage or nested OSCBundle.
+    """
+
+    timetag: int
+    elements: Tuple[OSCPacket, ...]
+
+
+OSCPacket = Union["OSCMessage", "OSCBundle"]
+
+__all__ = [
+    "OSCRGBA",
+    "OSC_IMPULSE",
+    "OSCArg",
+    "OSCArray",
+    "OSCAtomic",
+    "OSCBlob",
+    "OSCBundle",
+    "OSCChar",
+    "OSCDouble",
+    "OSCFalse",
+    "OSCImpulse",
+    "OSCInt",
+    "OSCInt64",
+    "OSCMessage",
+    "OSCMidi",
+    "OSCNil",
+    "OSCPacket",
+    "OSCString",
+    "OSCSymbol",
+    "OSCTimeTag",
+    "OSCTrue",
+]

oscparser-1.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: oscparser
+Version: 1.1.0
+Summary: Library for parsing and building Open Sound Control (OSC) messages and bundles.
+Author-email: Morph Tollon <code@morphtollon.co.uk>, Ripple <github@ripple.contact>
+Maintainer-email: Morph Tollon <code@morphtollon.co.uk>, Ripple <github@ripple.contact>
+License: MIT License
+        
+        Copyright (c) 2025 Morph Tollon
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://gitlab.com/Theatre-Tools/python-osc-parser
+Project-URL: Homepage, https://gitlab.com/Theatre-Tools/python-osc-parser
+Project-URL: Issues, https://gitlab.com/Theatre-Tools/python-osc-parser/-/issues
+Keywords: osc,sound,midi,music
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: Freely Distributable
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: System :: Networking
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Python OSC Parser
+
+Open Sound Control (OSC) protocol implementation in Python.
+## Current status
+
+This library was developed following the
+[OpenSoundControl Specification 1.0](https://opensoundcontrol.stanford.edu/spec-1_0.html)
+and is currently in a stable state.
+
+## Features
+
+- Parsing and constructing OSC messages and bundles.
+- Support for various OSC data types including integers, floats, strings, blobs, and more.
+
+## License
+
+This software is licensed under the MIT License. See the LICENSE file for details.

oscparser-1.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+oscparser/__init__.py,sha256=f9TDvJEJTxoZCtOGzTA8B1dccER7nAfiiEr3ra_wAGM,1501
+oscparser/ctx.py,sha256=uAt3DkXVM39xXlJFo7HVfolj9-MM9zdbEDQH6Ar5I-8,429
+oscparser/decode.py,sha256=W9B9jcwz9-dKvjjA-gU-1Jt4wLp6QfVzX5_S0X6AIao,2765
+oscparser/encode.py,sha256=jUsXyYP5L4mfGJiaihzhdtC4UWK39QpA0RU2D0epKhw,2316
+oscparser/types.py,sha256=t04imRO6AjtKWzdzR8UrXKtkpSFOC6CyZq396LYdQiQ,5495
+oscparser/framing/__init__.py,sha256=yjrteSCY0j9mBTbpp6sEoD5ns-sMvvsXgQz9lGs9MT8,207
+oscparser/framing/framer.py,sha256=nG9yldYQenKijmqjjQRolRlYr1ZeQ3bD5AczISrkcKc,450
+oscparser/framing/fullframer.py,sha256=QsNUeItdxDHEJU4fyBfGN0ghn4U75u2T0ctX71q7XF0,1069
+oscparser/framing/osc10.py,sha256=gY5wOGL40v0IPuy9HjQY7j0uf3xp7ZYCOAcFmpAp0wU,2039
+oscparser/framing/osc11.py,sha256=6MiM5Z1H2vcc6fsSRshbNYylTTKFx2GDlGa-Wyt__AI,6527
+oscparser/processing/args/args.py,sha256=zOKMgjLixFK7n_jS3kpK-37ip9Gkzyp9ZpLGx38A_Ho,17955
+oscparser/processing/args/proccessing.py,sha256=ZxjghxPHgAfBMS5QoJ16vrnMTAyCTweTP5ykrctxglY,1045
+oscparser/processing/osc/handlers.py,sha256=_ExoQEM5XdLP6r2L0W7z-qfE1SzvAKDgWUCZdQO5xJ8,5645
+oscparser/processing/osc/processing.py,sha256=3-LOXVteJLf8TYlHX-FyG2McZLVSQdyiWBbJoAEEDwY,1884
+oscparser-1.1.0.dist-info/licenses/LICENSE,sha256=bhC-qZPLBnE1KaT__cf0Zw7qXl1xyU9qdhvVHkIeEhg,1069
+oscparser-1.1.0.dist-info/METADATA,sha256=zMFTQ-AiQa67z63Mpsvi7RP7dZgv_HX5Inw1FE5JbGo,2740
+oscparser-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+oscparser-1.1.0.dist-info/top_level.txt,sha256=3bs-r_OX2twJ4h00vGo3elKFzAhJeQ8UIN1TT73AR0E,10
+oscparser-1.1.0.dist-info/RECORD,,

oscparser-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oscparser-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Morph Tollon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oscparser-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oscparser