Python API

Python Bindings

Serverboards provides Python API bindings via the serverboards module.

A common way to use the bindings is as follows:

import serverboards

@serverboards.rpc_method
def add(a,b):
	return a + b

serverboards.loop()

Globals

__dir()

Returns the list of all registered methods.

Normally used by the other endpoint.

debug(s)

Logs a debug into the other endpoint

error(s)

Logs an error into the other endpoint

info(s)

Logs an info line into the other endpoint

loop(debug)

Wrapper to easily start rpc loop

It allows setting the debug flag/file here.

Parameters

param type description
debug bool|file Whether to debug to stderr, or to another file object

rpc_method(f)

Decorator to add this method to the known RPC methods.

Use as simple decorator:

@decorator
def func(param1, param2):
    ....

or with a specific name

@decorator("rpc-name")
def func(param1=None):
    ...

warning(s)

Logs a warning into the other endpoint

class Config

Easy access some configuration data for this plugin

file(self, filename)

Gets the absolute path of a local file for this plugin.

This uses the serverboards configured local storage for the current plugin

class RPC

Manages all the RPC status and calls.

__decorate_log(self, extra, level)

Helper that decorates the given log messages with data of which function, line and file calls the log.

__init__(self, stdin, stdout)

Initilize the JSON-RPC communication object

This class allows to register methods, event handlers, timers and file descriptor handlers to ease the communication using JSON-RPC.

Parameters

param type description
stdin file Which input file to use to read JSON-RPC calls. Normally stdin.
stdout file File to use to write JSON-RPC calls to the remote endpoint. Normally stdout.

__process_request(self, rpc)

Performs the request processing to the external RPC endpoint.

This internal function is used to do the real writing to the othe rend, as in some conditions it ma be delayed.

add_event(self, fd, cont)

Watches for changes in a external file descriptor and calls the continuation function.

This allows this class to also listen for external processes and file description changes.

Parameters

param type description
fd int File descriptor
cont function() Continuation function to call when new data ready to read at fd

add_method(self, name, f)

Adds a method to the local method registry.

All local methods that can be caled b the remote endpoint have to be registered here.

Normally the @rpc_method decorator is used for ease of use.

add_timer(self, interval, cont)

Adds a timer to the rpc object

After the given interval the continuation object will be called. The timer is not rearmed; it must be added again by the caller if desired.

Tis timers are not in realtime, and may be called well after the timer expires, if the process is performing other actions, but will be called as soon as possible.

Parameters

param type description
interval float Time in seconds to wait until calling this timer
cont function() Function to call when the timer expires.

Returns

timer_id : int Timer id to be used for later removal of timer

call(self, method)

Calls a method on the other side and waits until answer.

If receives a call while waiting for answer there are two behaviours:

  1. If at self.loop, processes the request inmediatly
  2. If not, queues it to be processed wehn loop is called

This allows to setup the environment.

call_local(self, rpc)

Performs a local call into a registered method.

This is use internally for all incomming rpc calls.

debug(self, msg, extra, level)

Sends a debug message

debug_stdout(self, x)

Helper that writes to stderr some message.

It adds the required \r at the line start, as elixir/erlang removes them on externals processes / ports. Also adds the current PID to ease debugging, as diferent calls to the same command will have diferent pids.

This is used when self.debug is in use.

error(self, msg, extra, level)

Send an error message

event(self, method)

Sends an event to the other side

info(self, msg, extra, level)

Sends and information message

log(self, message, type)

Writes a log message on the other end.

Used by error, debug and info.

loop(self)

Ener into the read remote loop.

This loop also perform the timers watch and extra fds select.

loop_stop(self, debug)

Forces loop stop on next iteration.

This can be used to force program stop, although normally serverboards will emit a SIGSTOP signal to stop processes when required.

println(self, line)

Prints a line onto the external endpoint.

This function allows for easy debugging and some error conditions.

read_parse_line(self)

Reads a line from the rpc input line, and parses it.

remove_event(self, fd)

Removes an event from the event watching list

remove_timer(self, tid)

Removes a timer.

reply(self, result)

Shortcuts request processing returning an inmediate answer. The final answer will be ignored.

This allows to start long running processes that may send events in a loop.

If more calls are expected, it is recomended to spawn new threads.

set_debug(self, debug)

Sets the debug mode for this rpc object.

Parameters

param type description
debug bool Whether to activate debug data to stderr
debug file To which file to write

subscribe(self, event, callback)

Subscribes for a serverevent, calling the callback(eventdata) when it happens.

Returns a subscription id, tahta can be used to unsubscribe.

unsubscribe(self, subscription_id)

Unsubscribes from an event.