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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-osc
-Version: 1.8.3
+Version: 1.9.1
 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
 
@@ -60,10 +60,12 @@ and is currently in a stable state.
 Features
 ========
 
-* UDP blocking/threading/forking/asyncio server implementations
-* UDP client
+* UDP and TCP blocking/threading/forking/asyncio server implementations
+* UDP and TCP clients, including asyncio support
+* TCP support for 1.0 and 1.1 protocol formats
 * int, int64, float, string, double, MIDI, timestamps, blob, nil OSC arguments
 * simple OSC address<->callback matching system
+* support for sending responses from callback handlers in client and server
 * extensive unit test coverage
 * basic client and server examples
 
@@ -188,7 +190,8 @@ Building bundles
     # The bundle has 5 elements in total now.
 
     bundle = bundle.build()
-    # You can now send it via a client as described in other examples.
+    # You can now send it via a client with the `.send()` method:
+    client.send(bundle)
 
 License?
 ========

{python-osc-1.8.3 → python_osc-1.9.1}/README.rst

@@ -18,10 +18,12 @@ and is currently in a stable state.
 Features
 ========
 
-* UDP blocking/threading/forking/asyncio server implementations
-* UDP client
+* UDP and TCP blocking/threading/forking/asyncio server implementations
+* UDP and TCP clients, including asyncio support
+* TCP support for 1.0 and 1.1 protocol formats
 * int, int64, float, string, double, MIDI, timestamps, blob, nil OSC arguments
 * simple OSC address<->callback matching system
+* support for sending responses from callback handlers in client and server
 * extensive unit test coverage
 * basic client and server examples
 
@@ -146,7 +148,8 @@ Building bundles
     # The bundle has 5 elements in total now.
 
     bundle = bundle.build()
-    # You can now send it via a client as described in other examples.
+    # You can now send it via a client with the `.send()` method:
+    client.send(bundle)
 
 License?
 ========

python_osc-1.9.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-osc"
+version = "1.9.1"
+description = "Open Sound Control server and client implementations in pure Python"
+readme = "README.rst"
+requires-python = ">=3.10"
+license = { file = "LICENSE.txt" }
+authors = [
+    { name = "attwad", email = "tmusoft@gmail.com" },
+]
+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",
+]
+
+[project.urls]
+Repository = "https://github.com/attwad/python-osc"
+
+[tool.mypy]
+# Would be great to turn this on, however there's too many cases it would break
+# right now.
+# disallow_any_generics = true
+
+disallow_subclassing_any = true
+
+# Allow functions _without_ type annotations, but require that annotations be
+# complete (possibly including the `Any` type) where they are present.
+disallow_incomplete_defs = true
+# check_untyped_defs = true
+disallow_untyped_decorators = true
+
+# # Would be great to turn these on eventually
+# no_implicit_optional = true
+# strict_optional = true
+
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+# # Would be great to turn this on eventually
+# # warn_return_any = true
+# warn_unreachable = true
+
+# implicit_reexport = False
+# strict_equality = true
+
+scripts_are_modules = true
+warn_unused_configs = true
+
+enable_error_code = "ignore-without-code"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-osc
-Version: 1.8.3
+Version: 1.9.1
 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
 
@@ -60,10 +60,12 @@ and is currently in a stable state.
 Features
 ========
 
-* UDP blocking/threading/forking/asyncio server implementations
-* UDP client
+* UDP and TCP blocking/threading/forking/asyncio server implementations
+* UDP and TCP clients, including asyncio support
+* TCP support for 1.0 and 1.1 protocol formats
 * int, int64, float, string, double, MIDI, timestamps, blob, nil OSC arguments
 * simple OSC address<->callback matching system
+* support for sending responses from callback handlers in client and server
 * extensive unit test coverage
 * basic client and server examples
 
@@ -188,7 +190,8 @@ Building bundles
     # The bundle has 5 elements in total now.
 
     bundle = bundle.build()
-    # You can now send it via a client as described in other examples.
+    # You can now send it via a client with the `.send()` method:
+    client.send(bundle)
 
 License?
 ========

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

@@ -2,7 +2,6 @@ LICENSE.txt
 MANIFEST.in
 README.rst
 pyproject.toml
-setup.cfg
 python_osc.egg-info/PKG-INFO
 python_osc.egg-info/SOURCES.txt
 python_osc.egg-info/dependency_links.txt
@@ -15,7 +14,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 +29,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.1/pythonosc/dispatcher.py

@@ -0,0 +1,337 @@
+"""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(
+                    f"Address '{address}' doesn't have handler '{handler}' mapped to it"
+                ) 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 = f"{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.1}/pythonosc/osc_bundle.py

@@ -33,11 +33,13 @@ class OscBundle(object):
         try:
             self._timestamp, index = osc_types.get_date(self._dgram, index)
         except osc_types.ParseError as pe:
-            raise ParseError("Could not get the date from the datagram: %s" % pe)
+            raise ParseError(f"Could not get the date from the datagram: {pe}")
         # 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,9 +61,10 @@ class OscBundle(object):
                     contents.append(osc_message.OscMessage(content_dgram))
                 else:
                     logging.warning(
-                        "Could not identify content type of dgram %r" % content_dgram)
+                        f"Could not identify content type of dgram {content_dgram!r}"
+                    )
         except (osc_types.ParseError, osc_message.ParseError, IndexError) as e:
-            raise ParseError("Could not parse a content datagram: %s" % e)
+            raise ParseError(f"Could not parse a content datagram: {e}")
 
         return contents
 

{python-osc-1.8.3 → python_osc-1.9.1}/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,20 @@ 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)))
+                        f"Content must be either OscBundle or OscMessage, found {type(content)}"
+                    )
             return osc_bundle.OscBundle(dgram)
         except osc_types.BuildError as be:
-            raise BuildError('Could not build the bundle {}'.format(be))
+            raise BuildError(f"Could not build the bundle {be}")

{python-osc-1.8.3 → python_osc-1.9.1}/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,21 @@ 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(
+                            f"Unexpected closing bracket in type tag: {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(f"Unhandled parameter type: {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(f"Missing closing bracket in type tag: {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 +96,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: