pyliblo 0.9 - API Documentation

For the most part, pyliblo is just a thin wrapper around liblo, which does all the real work. For questions not answered here, also see the liblo documentation.

The Python module is simply called liblo.

functions

send(target, message)
send(target, bundle)
send(target, path[, arg, ...])

Sends a message or bundle to the the given target, without requiring a server.
target may be an Address object, a port number, a (hostname, port) tuple, or a URL.
Exceptions: AddressError, IOError

time()

Returns the current time as a float in OSC format, that is, the number of seconds since the epoch (January 1, 1900).

class Server

Server([port[, proto[, **kwargs]]])

Creates a new Server object, which can receive OSC messages.
port may be a decimal port number or a UNIX socket path. If omitted, an arbitrary free UDP port will be used.
proto can be one of the constants UDP, TCP, UNIX.
Optional keyword arguments:
reg_methods: False if you don't want the init function to automatically register callbacks defined with the @make_method decorator.
Exceptions: ServerError

add_method(path, typespec, callback_func[, user_data])

Registers a callback function for OSC messages with matching path and argument types.
For both path and typespec, None may be used as a wildcard.
The optional user_data will be passed on to the callback function. callback_func may be a global function or a class method, pyliblo will know what to do either way.

del_method(path, typespec)

Deletes a callback function. For both path and typespec, None may be used as a wildcard.

@make_method(path, typespec[, user_data])

Decorator that basically serves the same purpose as add_method().
Note that @make_method is defined at module scope, and not a member of class Server.

register_methods([obj])

Calls add_method() for all methods of obj decorated with @make_method. obj defaults to the Server object itself.
This function is called automatically by the Server's init function, unless its reg_methods parameter is False.

my_callback(path, args[, types[, src[, user_data]]])
my_callback(self, path, args[, types[, src[, user_data]]])

User-defined callback function, to be registered using add_method() or @make_method; called when a matching OSC message is received.
args will be a list of message arguments, using appropriate built-in Python data types. types is a string with the typespec of the message. src is an Address object, containing the address the message came from. types, src and user_data may be omitted if not needed.
The callback should return zero (or nothing/None) if the message has been dealt with correctly, or non-zero to look for another matching message handler.

recv([timeout])

Receives and dispatches one OSC message. Blocking by default, unless timeout (in ms) is specified.
timeout may be 0, in which case recv() returns immediately. Returns True if a message was received, False otherwise.

send(target, message)
send(target, bundle)
send(target, path[, arg, ...])

Sends a message or bundle from this server to the the given target.
target may be an Address object, a port number, a (hostname, port) tuple, or a URL.
Exceptions: AddressError, IOError

url
get_url()

The server's URL.

port
get_port()

The server's port number.

protocol
get_protocol()

The server's protocol (one of the constants UDP, TCP, UNIX).

fileno()

Returns the file descriptor of the server socket, or -1 if not supported by the underlying server protocol.

free()

Frees the underlying server object and closes its port. Note that this will also happen automatically when the server is garbage-collected.

class ServerThread

Unlike Server, ServerThread uses its own thread which runs in the background to dispatch messages. Note that callback methods will not be run in the main Python thread!
ServerThread has the same methods as Server, with the exception of recv(). Instead, it defines these two methods:

start()

Starts the server thread, liblo will now start to dispatch any messages it receives.

stop()

Stops the server thread.

class Address

Address(hostname, port[, proto])
Address(port)
Address(url)

Creates a new Address object from the given hostname/port or URL.
proto can be one of the constants UDP, TCP, UNIX.
Exceptions: AddressError

url
get_url()

The address' URL.

hostname
get_hostname()

The address' hostname.

port
get_port()

The address' port number.

protocol
get_protocol()

The address' protocol (one of the constants UDP, TCP, UNIX).

class Message

Message(path[, arg, ...])

Creates a new Message object.

add(arg[, ...])

Appends the given argument(s) to the message.

class Bundle

Bundle([timetag, ][message, ...])

Creates a new Bundle object. You can optionally specify a time at which the messages should be dispatched (as an OSC timetag float), and any number of messages to be included in the bundle.

add(message[, ...])
add(path[, arg, ...])

Adds one or more messages to the bundle.

constants

UDP
TCP
UNIX

Specifies the protocol of a server or address object.

mapping between OSC and Python data types

When constructing a message, pyliblo tries to automatically convert arguments to an appropriate OSC data type, depending on the Python argument. To explicitly specify the OSC data type to be transmitted, pass a (typetag, data) tuple. Some types can't be unambiguously recognized, so they can only be sent that way.
Callback functions always receive their arguments according to the following table: