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[source]¶
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.
- async async_call_handlers_for_packet(data: bytes, client_address: Tuple[str, int]) List [source]¶
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 [source]¶
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] [source]¶
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 [source]¶
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 [source]¶
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)[source]¶
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.
- __hash__ = None¶
- __init__(_callback: Callable, _args: Any | List[Any], _needs_reply_address: bool = False) None [source]¶
- 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] [source]¶
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.