Dispatcher

The dispatcher maps OSC addresses to functions and calls the functions with the messages’ arguments. Function can also be mapped to wildcard addresses.

Example

from pythonosc.dispatcher import Dispatcher
from typing import List, Any

dispatcher = Dispatcher()


def set_filter(address: str, *args: List[Any]) -> None:
    # We expect two float arguments
    if not len(args) == 2 or type(args[0]) is not float or type(args[1]) is not float:
        return

    # Check that address starts with filter
    if not address[:-1] == "/filter":  # Cut off the last character
        return

    value1 = args[0]
    value2 = args[1]
    filterno = address[-1]
    print(f"Setting filter {filterno} values: {value1}, {value2}")


dispatcher.map("/filter*", set_filter)  # Map wildcard address to set_filter function

# Set up server and client for testing
from pythonosc.osc_server import BlockingOSCUDPServer
from pythonosc.udp_client import SimpleUDPClient

server = BlockingOSCUDPServer(("127.0.0.1", 1337), dispatcher)
client = SimpleUDPClient("127.0.0.1", 1337)

# Send message and receive exactly one message (blocking)
client.send_message("/filter1", [1., 2.])
server.handle_request()

client.send_message("/filter8", [6., -2.])
server.handle_request()

Mapping

The dispatcher associates addresses with functions by storing them in a mapping. An address can contains wildcards as defined in the OSC specifications. Call the Dispatcher.map method with an address pattern and a handler callback function:

from pythonosc.dispatcher import Dispatcher
disp = Dispatcher()
disp.map("/some/address*", some_printing_func)

This will for example print any OSC messages starting with /some/address.

Additionally you can provide any amount of extra fixed argument that will always be passed before the OSC message arguments:

handler = disp.map("/some/other/address", some_printing_func, "This is a fixed arg", "and this is another fixed arg")

The handler callback signature must look like this:

def some_callback(address: str, *osc_arguments: List[Any]) -> None:
def some_callback(address: str, fixed_argument: List[Any], *osc_arguments: List[Any]) -> None:

Instead of a list you can of course also use a fixed amount of arguments for osc_arguments

The Dispatcher.map method returns a Handler object, which can be used to remove the mapping from the dispatcher.

Unmapping

A mapping can be undone with the Dispatcher.unmap method, which takes an address and Handler object as arguments. For example, to unmap the mapping from the Mapping section:

disp.unmap("some/other/address", handler)

Alternatively the handler can be reconstructed from a function and optional fixed argument:

disp.unmap("some/other/address", some_printing_func, *some_fixed_args)

If the provided mapping doesn’t exist, a ValueError is raised.

Default Handler

It is possible to specify a handler callback function that is called for every unmatched address:

disp.set_default_handler(some_handler_function)

This is extremely useful if you quickly need to find out what addresses an undocumented device is transmitting on or for building a learning function for some controls. The handler must have the same signature as map callbacks:

def some_callback(address: str, *osc_arguments: List[Any]) -> None:

Handler Responses

Handler functions can return responses back to the client, when running on a server, or to the server when running as a client. Handler functions should return one of:

• None

• An OSC address in string format

• A tuple containing a string OSC address and the associated arguments

If the handler function response is not None it will be encoded in an OSCMessage and sent to the remote client or server.

Dispatcher Module Documentation

Maps OSC addresses to handler functions

class pythonosc.dispatcher.Dispatcher

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.

__init__() → None

async async_call_handlers_for_packet(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, …)

call_handlers_for_packet(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.

Parameters:

• 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

handlers_for_address(address_pattern: str) → Generator[Handler, None, None]

Yields handlers matching an address

Parameters:

address_pattern – Address to match

Returns:

Generator yielding Handlers matching address_pattern

map(address: str, handler: Callable, *args: 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.

Parameters:

• 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

set_default_handler(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.

Parameters:

• handler – Callback function to handle unmapped requests

• needs_reply_address – Whether the callback shall be passed the client address

class pythonosc.dispatcher.Handler(_callback: Callable, _args: Any | List[Any], _needs_reply_address: bool = False)

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.

__eq__(other: Any) → bool

Return self==value.

__hash__ = None

__init__(_callback: Callable, _args: Any | List[Any], _needs_reply_address: bool = False) → None

Parameters:

• invoked (_callback Function that is called when handler is)

• _args – Message causing invocation

• not (_needs_reply_address Whether the client's ip address shall be passed as an argument or)

invoke(client_address: Tuple[str, int], message: OscMessage) → None | AnyStr | Tuple[AnyStr, str | bytes | bool | int | float | Tuple[int, int, int, int] | list]

Invokes the associated callback function

Parameters:

• 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.