# pyliblo 0.10 API Documentation

Homepage: http://das.nasophon.de/pyliblo/

The latest version of this manual can be found at http://dsacre.github.io/pyliblo/doc/.

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 and the OSC spec.

## Module-level Functions

`send`(target, *messages)
`send`(target, path, *args)

  Send messages to the the given target, without requiring a server. Arguments may be one or more `Message` or `Bundle` objects, or a single message given by its path and optional arguments.

  Parameters:

  - target – the address to send the message to; an `Address` object, a port number, a `(hostname, port)` tuple, or a URL.
  - messages – one or more objects of type `Message` or `Bundle`.
  - path – the path of the message to be sent.

  Raises:

  - AddressError – if the given target is invalid.
  - IOError – if the message couldn’t be sent.

`time`()

  Return the current time as a floating point number (seconds since January 1, 1900).

## OSC Server Classes

class `Server`

  A server that can receive OSC messages using a simple single-threaded polling model. Use `ServerThread` for an OSC server that runs in its own thread and never blocks.

  `Server`(port[, proto])

    Create a new `Server` object.

    Parameters:

    - port – a decimal port number or a UNIX socket path. If omitted, an arbitrary free UDP port will be used.
    - proto – one of the constants `UDP`, `TCP`, or `UNIX`; default is `UDP`.
    - reg_methods – `False` if you don’t want the init function to automatically register callbacks defined with the `make_method()` decorator (keyword argument only).

    Exceptions: ServerError

  `recv`(timeout=None)

    Receive and dispatch one OSC message. Blocking by default, unless timeout is specified.

    Parameters: | timeout – Time in milliseconds after which the function returns if no messages have been received. timeout may be 0, in which case the function always returns immediately, whether messages have been received or not.
    Returns: | `True` if a message was received, otherwise `False`.

  `send`(target, *messages)
  `send`(target, path, *args)

    Send a message or bundle from this server to the the given target. Arguments may be one or more `Message` or `Bundle` objects, or a single message given by its path and optional arguments.

    Parameters:

    - target – the address to send the message to; an `Address` object, a port number, a `(hostname, port)` tuple, or a URL.
    - messages – one or more objects of type `Message` or `Bundle`.
    - path – the path of the message to be sent.

    Raises:

    - AddressError – if the given target is invalid.
    - IOError – if the message couldn’t be sent.

  `add_method`(path, typespec, func, user_data=None)

    Register a callback function for OSC messages with matching path and argument types.

    Parameters:

    - path – the message path to be handled by the registered method. `None` may be used as a wildcard to match any OSC message.
    - typespec – the argument types to be handled by the registered method. `None` may be used as a wildcard to match any OSC message.
    - func – the callback function. This may be a global function, a class method, or any other callable object, pyliblo will know what to do either way.
    - user_data – An arbitrary object that will be passed on to func every time a matching message is received.

  `del_method`(path, typespec)

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

    New in version 0.9.2.

  `register_methods`(obj=None)

    Call `add_method()` for all methods of an object that are decorated with `make_method()`.

    Parameters: | obj – The object that implements the OSC callbacks to be registered. By default this is the server object itself.

    This function is usually called automatically by the server’s constructor, unless its reg_methods parameter was set to `False`.

  `add_bundle_handlers`(start_handler, end_handler, user_data=None)

    Add bundle notification handlers.

    Parameters:

    - start_handler – a callback which fires when at the start of a bundle. This is called with the bundle’s timestamp and user_data.
    - end_handler – a callback which fires when at the end of a bundle. This is called with user_data.
    - user_data – data to pass to the handlers.

    New in version 0.10.0.

  `url`

    The server’s URL.

  `port`

    The server’s port number.

  `protocol`

    The server’s protocol (one of the constants `UDP`, `TCP`, or `UNIX`).

  `fileno`()

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

  `free`()

    Free the underlying server object and close its port. Note that this will also happen automatically when the server is deallocated.

class `ServerThread`

  Unlike `Server`, `ServerThread` uses its own thread which runs in the background to dispatch messages. `ServerThread` has the same methods as `Server`, with the exception of `Server.recv()`. Instead, it defines two additional methods `start()` and `stop()`.

  Note

  Because liblo creates its own thread to receive and dispatch messages, callback functions will not be run in the main Python thread!

  `ServerThread`(port[, proto])

    Create a new `ServerThread` object, which can receive OSC messages. 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!

    Parameters:

    - port – a decimal port number or a UNIX socket path. If omitted, an arbitrary free UDP port will be used.
    - proto – one of the constants `UDP`, `TCP`, or `UNIX`; default is `UDP`.
    - reg_methods – `False` if you don’t want the init function to automatically register callbacks defined with the make_method decorator (keyword argument only).

    Raises:

    - ServerError – if creating the server fails, e.g. because the given port could not be opened.

  `start`()

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

  `stop`()

    Stop the server thread.

class `make_method`

  A decorator that serves as a more convenient alternative to `Server.add_method()`.

  `make_method`(path, typespec[, user_data])

    Set the path and argument types for which the decorated method is to be registered.

    Parameters:

    - path – the message path to be handled by the registered method. `None` may be used as a wildcard to match any OSC message.
    - typespec – the argument types to be handled by the registered method. `None` may be used as a wildcard to match any OSC message.
    - user_data – An arbitrary object that will be passed on to the decorated method every time a matching message is received.

## Utility Classes

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

    Create a new `Address` object from the given hostname/port or URL.

    Parameters:

    - hostname – the target’s hostname.
    - port – the port number on the target.
    - proto – one of the constants `UDP`, `TCP`, or `UNIX`.
    - url – a URL in liblo notation, e.g. `'osc.udp://hostname:1234/'`.

    Raises:

    - AddressError – if the given parameters do not represent a valid address.

  `url`

    The address’s URL.

  `hostname`

    The address’s hostname.

  `port`

    The address’s port number.

  `protocol`

    The address’s protocol (one of the constants `UDP`, `TCP`, or `UNIX`).

class `Message`

  An OSC message, consisting of a path and arbitrary arguments.

  `Message`(path, *args)

    Create a new `Message` object.

  `add`(*args)

    Append the given arguments to the message. Arguments can be single values or `(typetag, data)` tuples.

class `Bundle`

  A bundle of one or more messages to be sent and dispatched together.

  `Bundle`([timetag, ]*messages)

    Create 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`(*messages)
  `add`(path, *args)

    Add one or more messages to the bundle.

exception `ServerError`

  Raised when creating a liblo OSC server fails.

exception `AddressError`

  Raised when trying to create an invalid `Address` object.

## Mapping between OSC and Python data types

When constructing a message, pyliblo automatically converts arguments to an appropriate OSC data type. To explicitly specify the OSC data type to be transmitted, pass a `(typetag, data)` tuple instead. Some types can’t be unambiguously recognized, so they can only be sent that way.

The mapping between OSC and Python data types is shown in the following table:

typetag | OSC data type | Python data type
--- | --- | ---
`'i'` | int32 | `int`
`'h'` | int64 | `long` (Python 2.x), `int` (Python 3.x)
`'f'` | float | `float`
`'d'` | double | `float`
`'c'` | char | `str` (single character)
`'s'` | string | `str`
`'S'` | symbol | `str`
`'m'` | midi | `tuple` of four `int`s
`'t'` | timetag | `float`
`'T'` | true |
`'F'` | false |
`'N'` | nil |
`'I'` | infinitum |
`'b'` | blob | `list` of `int`s (Python 2.x), `bytes` (Python 3.x)