python-osc 1.8.3__tar.gz → 1.9.0__tar.gz

{python-osc-1.8.3/python_osc.egg-info → python_osc-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-osc
-Version: 1.8.3
+Version: 1.9.0
 Summary: Open Sound Control server and client implementations in pure Python
 Author-email: attwad <tmusoft@gmail.com>
 License: This is free and unencumbered software released into the public domain.
@@ -36,7 +36,7 @@ Classifier: License :: Freely Distributable
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: System :: Networking
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 

{python-osc-1.8.3 → python_osc-1.9.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "python-osc"
-version="1.8.3"
+version="1.9.0"
 description="Open Sound Control server and client implementations in pure Python"
 readme="README.rst"
-requires-python=">=3.7"
+requires-python=">=3.10"
 license = {file = "LICENSE.txt"}
 authors = [
   {name = "attwad", email = "tmusoft@gmail.com"},

{python-osc-1.8.3 → python_osc-1.9.0/python_osc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-osc
-Version: 1.8.3
+Version: 1.9.0
 Summary: Open Sound Control server and client implementations in pure Python
 Author-email: attwad <tmusoft@gmail.com>
 License: This is free and unencumbered software released into the public domain.
@@ -36,7 +36,7 @@ Classifier: License :: Freely Distributable
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: System :: Networking
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 

{python-osc-1.8.3 → python_osc-1.9.0}/python_osc.egg-info/SOURCES.txt

@@ -15,7 +15,9 @@ pythonosc/osc_message.py
 pythonosc/osc_message_builder.py
 pythonosc/osc_packet.py
 pythonosc/osc_server.py
-pythonosc/py.typed
+pythonosc/osc_tcp_server.py
+pythonosc/slip.py
+pythonosc/tcp_client.py
 pythonosc/udp_client.py
 pythonosc/parsing/__init__.py
 pythonosc/parsing/ntp.py
@@ -28,6 +30,8 @@ pythonosc/test/test_osc_message.py
 pythonosc/test/test_osc_message_builder.py
 pythonosc/test/test_osc_packet.py
 pythonosc/test/test_osc_server.py
+pythonosc/test/test_osc_tcp_server.py
+pythonosc/test/test_tcp_client.py
 pythonosc/test/test_udp_client.py
 pythonosc/test/parsing/__init__.py
 pythonosc/test/parsing/test_ntp.py

python_osc-1.9.0/pythonosc/dispatcher.py

@@ -0,0 +1,338 @@
+"""Maps OSC addresses to handler functions
+"""
+
+import collections
+import inspect
+import logging
+import re
+import time
+from pythonosc import osc_packet
+from typing import (
+    overload,
+    List,
+    Union,
+    Any,
+    AnyStr,
+    Generator,
+    Tuple,
+    Callable,
+    Optional,
+    DefaultDict,
+)
+from pythonosc.osc_message import OscMessage
+from pythonosc.osc_message_builder import ArgValue
+
+
+class Handler(object):
+    """Wrapper for a callback function that will be called when an OSC message is sent to the right address.
+
+    Represents a handler callback function that will be called whenever an OSC message is sent to the address this
+    handler is mapped to. It passes the address, the fixed arguments (if any) as well as all osc arguments from the
+    message if any were passed.
+    """
+
+    def __init__(
+        self,
+        _callback: Callable,
+        _args: Union[Any, List[Any]],
+        _needs_reply_address: bool = False,
+    ) -> None:
+        """
+        Args:
+            _callback Function that is called when handler is invoked
+            _args: Message causing invocation
+            _needs_reply_address Whether the client's ip address shall be passed as an argument or not
+        """
+        self.callback = _callback
+        self.args = _args
+        self.needs_reply_address = _needs_reply_address
+
+    # needed for test module
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(self, type(other))
+            and self.callback == other.callback
+            and self.args == other.args
+            and self.needs_reply_address == other.needs_reply_address
+        )
+
+    def invoke(
+        self, client_address: Tuple[str, int], message: OscMessage
+    ) -> Union[None, AnyStr, Tuple[AnyStr, ArgValue]]:
+        """Invokes the associated callback function
+
+        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.
+        """
+        if self.needs_reply_address:
+            if self.args:
+                return self.callback(
+                    client_address, message.address, self.args, *message
+                )
+            else:
+                return self.callback(client_address, message.address, *message)
+        else:
+            if self.args:
+                return self.callback(message.address, self.args, *message)
+            else:
+                return self.callback(message.address, *message)
+
+
+class Dispatcher(object):
+    """Maps Handlers to OSC addresses and dispatches messages to the handler on matched addresses
+
+    Maps OSC addresses to handler functions and invokes the correct handler when a message comes in.
+    """
+
+    def __init__(self) -> None:
+        self._map: DefaultDict[str, List[Handler]] = collections.defaultdict(list)
+        self._default_handler: Optional[Handler] = None
+
+    def map(
+        self,
+        address: str,
+        handler: Callable,
+        *args: Union[Any, List[Any]],
+        needs_reply_address: bool = False,
+    ) -> Handler:
+        """Map an address to a handler
+
+        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)]:``
+
+        ``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)]:``
+
+        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
+        the client.
+
+        Args:
+            address: Address to be mapped
+            handler: Callback function that will be called as the handler for the given address
+            *args: Fixed arguements that will be passed to the callback function
+            needs_reply_address: Whether the IP address from which the message originated from shall be passed as
+                an argument to the handler callback
+
+        Returns:
+            The handler object that will be invoked should the given address match
+
+        """
+        # TODO: Check the spec:
+        # http://opensoundcontrol.org/spec-1_0
+        # regarding multiple mappings
+        handlerobj = Handler(handler, list(args), needs_reply_address)
+        self._map[address].append(handlerobj)
+        return handlerobj
+
+    @overload
+    def unmap(self, address: str, handler: Handler) -> None:
+        """Remove an already mapped handler from an address
+
+        Args:
+            address (str): Address to be unmapped
+            handler (Handler): A Handler object as returned from map().
+        """
+        pass
+
+    @overload
+    def unmap(
+        self,
+        address: str,
+        handler: Callable,
+        *args: Union[Any, List[Any]],
+        needs_reply_address: bool = False,
+    ) -> None:
+        """Remove an already mapped handler from an address
+
+        Args:
+            address: Address to be unmapped
+            handler: A function that will be run when the address matches with
+                the OscMessage passed as parameter.
+            args: Any additional arguments that will be always passed to the
+                handlers after the osc messages arguments if any.
+            needs_reply_address: True if the handler function needs the
+                originating client address passed (as the first argument).
+        """
+        pass
+
+    def unmap(self, address, handler, *args, needs_reply_address=False):
+        try:
+            if isinstance(handler, Handler):
+                self._map[address].remove(handler)
+            else:
+                self._map[address].remove(
+                    Handler(handler, list(args), needs_reply_address)
+                )
+        except ValueError as e:
+            if str(e) == "list.remove(x): x not in list":
+                raise ValueError(
+                    "Address '%s' doesn't have handler '%s' mapped to it"
+                    % (address, handler)
+                ) from e
+
+    def handlers_for_address(
+        self, address_pattern: str
+    ) -> Generator[Handler, None, None]:
+        """Yields handlers matching an address
+
+
+        Args:
+            address_pattern: Address to match
+
+        Returns:
+            Generator yielding Handlers matching address_pattern
+        """
+        # First convert the address_pattern into a matchable regexp.
+        # '?' in the OSC Address Pattern matches any single character.
+        # Let's consider numbers and _ "characters" too here, it's not said
+        # explicitly in the specification but it sounds good.
+        escaped_address_pattern = re.escape(address_pattern)
+        pattern = escaped_address_pattern.replace("\\?", "\\w?")
+        # '*' in the OSC Address Pattern matches any sequence of zero or more
+        # characters.
+        pattern = pattern.replace("\\*", "[\\w|\\+]*")
+        # The rest of the syntax in the specification is like the re module so
+        # we're fine.
+        pattern = pattern + "$"
+        patterncompiled = re.compile(pattern)
+        matched = False
+
+        for addr, handlers in self._map.items():
+            if patterncompiled.match(addr) or (
+                ("*" in addr)
+                and re.match(addr.replace("*", "[^/]*?/*"), address_pattern)
+            ):
+                yield from handlers
+                matched = True
+
+        if not matched and self._default_handler:
+            logging.debug("No handler matched but default handler present, added it.")
+            yield self._default_handler
+
+    def call_handlers_for_packet(
+        self, data: bytes, client_address: Tuple[str, int]
+    ) -> List:
+        """Invoke handlers for all messages in OSC packet
+
+        The incoming OSC Packet is decoded and the handlers for each included message is found and invoked.
+
+        Args:
+            data: Data of packet
+            client_address: Address of client this packet originated from
+        Returns: A list of strings or tuples to be converted to OSC messages and returned to the client
+        """
+        results = list()
+        # Get OSC messages from all bundles or standalone message.
+        try:
+            packet = osc_packet.OscPacket(data)
+            for timed_msg in packet.messages:
+                now = time.time()
+                handlers = self.handlers_for_address(timed_msg.message.address)
+                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)
+                for handler in handlers:
+                    result = handler.invoke(client_address, timed_msg.message)
+                    if result is not None:
+                        results.append(result)
+        except osc_packet.ParseError:
+            pass
+        return results
+
+    async def async_call_handlers_for_packet(
+        self, data: bytes, client_address: Tuple[str, int]
+    ) -> List:
+        """
+        This function calls the handlers registered to the dispatcher for
+        every message it found in the packet.
+        The process/thread granularity is thus the OSC packet, not the handler.
+
+        If parameters were registered with the dispatcher, then the handlers are
+        called this way:
+          handler('/address that triggered the message',
+                  registered_param_list, osc_msg_arg1, osc_msg_arg2, ...)
+        if no parameters were registered, then it is just called like this:
+          handler('/address that triggered the message',
+                  osc_msg_arg1, osc_msg_arg2, osc_msg_param3, ...)
+        """
+
+        # Get OSC messages from all bundles or standalone message.
+        results = []
+        try:
+            packet = osc_packet.OscPacket(data)
+            for timed_msg in packet.messages:
+                now = time.time()
+                handlers = self.handlers_for_address(timed_msg.message.address)
+                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)
+                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:
+                        results.append(result)
+        except osc_packet.ParseError as e:
+            pass
+        return results
+
+    def set_default_handler(
+        self, handler: Callable, needs_reply_address: bool = False
+    ) -> None:
+        """Sets the default handler
+
+        The default handler is invoked every time no other handler is mapped to an address.
+
+        Args:
+            handler: Callback function to handle unmapped requests
+            needs_reply_address: Whether the callback shall be passed the client address
+        """
+        self._default_handler = (
+            None if (handler is None) else Handler(handler, [], needs_reply_address)
+        )

{python-osc-1.8.3 → python_osc-1.9.0}/pythonosc/osc_bundle.py

@@ -37,7 +37,9 @@ class OscBundle(object):
         # Get the contents as a list of OscBundle and OscMessage.
         self._contents = self._parse_contents(index)
 
-    def _parse_contents(self, index: int) -> List[Union['OscBundle', osc_message.OscMessage]]:
+    def _parse_contents(
+        self, index: int
+    ) -> List[Union["OscBundle", osc_message.OscMessage]]:
         contents = []  # type: List[Union[OscBundle, osc_message.OscMessage]]
 
         try:
@@ -49,7 +51,7 @@ class OscBundle(object):
                 # Get the sub content size.
                 content_size, index = osc_types.get_int(self._dgram, index)
                 # Get the datagram for the sub content.
-                content_dgram = self._dgram[index:index + content_size]
+                content_dgram = self._dgram[index : index + content_size]
                 # Increment our position index up to the next possible content.
                 index += content_size
                 # Parse the content into an OSC message or bundle.
@@ -59,7 +61,8 @@ class OscBundle(object):
                     contents.append(osc_message.OscMessage(content_dgram))
                 else:
                     logging.warning(
-                        "Could not identify content type of dgram %r" % content_dgram)
+                        "Could not identify content type of dgram %r" % content_dgram
+                    )
         except (osc_types.ParseError, osc_message.ParseError, IndexError) as e:
             raise ParseError("Could not parse a content datagram: %s" % e)
 

{python-osc-1.8.3 → python_osc-1.9.0}/pythonosc/osc_bundle_builder.py

@@ -25,7 +25,7 @@ class OscBundleBuilder(object):
                        seconds since the epoch in UTC or IMMEDIATELY.
         """
         self._timestamp = timestamp
-        self._contents = []  # type: List[osc_bundle.OscBundle]
+        self._contents: List[osc_bundle.OscBundle] = []
 
     def add_content(self, content: osc_bundle.OscBundle) -> None:
         """Add a new content to this bundle.
@@ -41,19 +41,21 @@ class OscBundleBuilder(object):
         Raises:
           - BuildError: if we could not build the bundle.
         """
-        dgram = b'#bundle\x00'
+        dgram = b"#bundle\x00"
         try:
             dgram += osc_types.write_date(self._timestamp)
             for content in self._contents:
-                if (type(content) == osc_message.OscMessage
-                        or type(content) == osc_bundle.OscBundle):
+                if isinstance(content, osc_message.OscMessage) or isinstance(
+                    content, osc_bundle.OscBundle
+                ):
                     size = content.size
                     dgram += osc_types.write_int(size)
                     dgram += content.dgram
                 else:
                     raise BuildError(
                         "Content must be either OscBundle or OscMessage"
-                        "found {}".format(type(content)))
+                        "found {}".format(type(content))
+                    )
             return osc_bundle.OscBundle(dgram)
         except osc_types.BuildError as be:
-            raise BuildError('Could not build the bundle {}'.format(be))
+            raise BuildError("Could not build the bundle {}".format(be))

{python-osc-1.8.3 → python_osc-1.9.0}/pythonosc/osc_message.py

@@ -22,6 +22,9 @@ class OscMessage(object):
         self._parameters = []  # type: List[Any]
         self._parse_datagram()
 
+    def __str__(self):
+        return f"{self.address} {' '.join(str(p) for p in self.params)}"
+
     def _parse_datagram(self) -> None:
         try:
             self._address_regexp, index = osc_types.get_string(self._dgram, 0)
@@ -31,7 +34,7 @@ class OscMessage(object):
 
             # Get the parameters types.
             type_tag, index = osc_types.get_string(self._dgram, index)
-            if type_tag.startswith(','):
+            if type_tag.startswith(","):
                 type_tag = type_tag[1:]
 
             params = []  # type: List[Any]
@@ -69,19 +72,25 @@ class OscMessage(object):
                     param_stack.append(array)
                 elif param == "]":  # Array stop.
                     if len(param_stack) < 2:
-                        raise ParseError('Unexpected closing bracket in type tag: {0}'.format(type_tag))
+                        raise ParseError(
+                            "Unexpected closing bracket in type tag: {0}".format(
+                                type_tag
+                            )
+                        )
                     param_stack.pop()
                 # TODO: Support more exotic types as described in the specification.
                 else:
-                    logging.warning('Unhandled parameter type: {0}'.format(param))
+                    logging.warning("Unhandled parameter type: {0}".format(param))
                     continue
                 if param not in "[]":
                     param_stack[-1].append(val)
             if len(param_stack) != 1:
-                raise ParseError('Missing closing bracket in type tag: {0}'.format(type_tag))
+                raise ParseError(
+                    "Missing closing bracket in type tag: {0}".format(type_tag)
+                )
             self._parameters = params
         except osc_types.ParseError as pe:
-            raise ParseError('Found incorrect datagram, ignoring it', pe)
+            raise ParseError("Found incorrect datagram, ignoring it", pe)
 
     @property
     def address(self) -> str:
@@ -91,7 +100,7 @@ class OscMessage(object):
     @staticmethod
     def dgram_is_message(dgram: bytes) -> bool:
         """Returns whether this datagram starts as an OSC message."""
-        return dgram.startswith(b'/')
+        return dgram.startswith(b"/")
 
     @property
     def size(self) -> int:

{python-osc-1.8.3 → python_osc-1.9.0}/pythonosc/osc_message_builder.py

@@ -1,15 +1,17 @@
 """Build OSC messages for client applications."""
 
+from typing import Any, Iterable, List, Optional, Tuple, Union
+
 from pythonosc import osc_message
 from pythonosc.parsing import osc_types
 
-from typing import List, Tuple, Union, Any, Optional
-
 ArgValue = Union[str, bytes, bool, int, float, osc_types.MidiPacket, list]
 
+
 class BuildError(Exception):
     """Error raised when an incomplete message is trying to be built."""
 
+
 class OscMessageBuilder(object):
     """Builds arbitrary OscMessage instances."""
 
@@ -29,8 +31,18 @@ class OscMessageBuilder(object):
     ARG_TYPE_ARRAY_STOP = "]"
 
     _SUPPORTED_ARG_TYPES = (
-        ARG_TYPE_FLOAT, ARG_TYPE_DOUBLE, ARG_TYPE_INT, ARG_TYPE_INT64, ARG_TYPE_BLOB, ARG_TYPE_STRING,
-        ARG_TYPE_RGBA, ARG_TYPE_MIDI, ARG_TYPE_TRUE, ARG_TYPE_FALSE, ARG_TYPE_NIL)
+        ARG_TYPE_FLOAT,
+        ARG_TYPE_DOUBLE,
+        ARG_TYPE_INT,
+        ARG_TYPE_INT64,
+        ARG_TYPE_BLOB,
+        ARG_TYPE_STRING,
+        ARG_TYPE_RGBA,
+        ARG_TYPE_MIDI,
+        ARG_TYPE_TRUE,
+        ARG_TYPE_FALSE,
+        ARG_TYPE_NIL,
+    )
 
     def __init__(self, address: Optional[str] = None) -> None:
         """Initialize a new builder for a message.
@@ -78,8 +90,10 @@ class OscMessageBuilder(object):
         """
         if arg_type and not self._valid_type(arg_type):
             raise ValueError(
-                'arg_type must be one of {}, or an array of valid types'
-                    .format(self._SUPPORTED_ARG_TYPES))
+                "arg_type must be one of {}, or an array of valid types".format(
+                    self._SUPPORTED_ARG_TYPES
+                )
+            )
         if not arg_type:
             arg_type = self._get_arg_type(arg_value)
         if isinstance(arg_type, list):
@@ -122,7 +136,7 @@ class OscMessageBuilder(object):
         elif arg_value is None:
             arg_type = self.ARG_TYPE_NIL
         else:
-            raise ValueError('Infered arg_value type is not supported')
+            raise ValueError("Infered arg_value type is not supported")
         return arg_type
 
     def build(self) -> osc_message.OscMessage:
@@ -136,18 +150,18 @@ class OscMessageBuilder(object):
           - an osc_message.OscMessage instance.
         """
         if not self._address:
-            raise BuildError('OSC addresses cannot be empty')
-        dgram = b''
+            raise BuildError("OSC addresses cannot be empty")
+        dgram = b""
         try:
             # Write the address.
             dgram += osc_types.write_string(self._address)
             if not self._args:
-                dgram += osc_types.write_string(',')
+                dgram += osc_types.write_string(",")
                 return osc_message.OscMessage(dgram)
 
             # Write the parameters.
             arg_types = "".join([arg[0] for arg in self._args])
-            dgram += osc_types.write_string(',' + arg_types)
+            dgram += osc_types.write_string("," + arg_types)
             for arg_type, value in self._args:
                 if arg_type == self.ARG_TYPE_STRING:
                     dgram += osc_types.write_string(value)  # type: ignore[arg-type]
@@ -165,16 +179,33 @@ class OscMessageBuilder(object):
                     dgram += osc_types.write_rgba(value)  # type: ignore[arg-type]
                 elif arg_type == self.ARG_TYPE_MIDI:
                     dgram += osc_types.write_midi(value)  # type: ignore[arg-type]
-                elif arg_type in (self.ARG_TYPE_TRUE,
-                                  self.ARG_TYPE_FALSE,
-                                  self.ARG_TYPE_ARRAY_START,
-                                  self.ARG_TYPE_ARRAY_STOP,
-                                  self.ARG_TYPE_NIL):
+                elif arg_type in (
+                    self.ARG_TYPE_TRUE,
+                    self.ARG_TYPE_FALSE,
+                    self.ARG_TYPE_ARRAY_START,
+                    self.ARG_TYPE_ARRAY_STOP,
+                    self.ARG_TYPE_NIL,
+                ):
                     continue
                 else:
-                    raise BuildError('Incorrect parameter type found {}'.format(
-                        arg_type))
+                    raise BuildError(
+                        "Incorrect parameter type found {}".format(arg_type)
+                    )
 
             return osc_message.OscMessage(dgram)
         except osc_types.BuildError as be:
-            raise BuildError('Could not build the message: {}'.format(be))
+            raise BuildError("Could not build the message: {}".format(be))
+
+
+def build_msg(address: str, value: ArgValue = "") -> osc_message.OscMessage:
+    builder = OscMessageBuilder(address=address)
+    values: ArgValue
+    if value == "":
+        values = []
+    elif not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
+        values = [value]
+    else:
+        values = value
+    for val in values:
+        builder.add_arg(val)
+    return builder.build()