The Coils programming API

Functions

coils.string2time(text)

Return datetime.datetime object from given string, or None if failed to translate.

coils.time2string(tstamp, micro=True)

Given a datetime.datetime object, return a formatted time string.

coils.time2levels(tstamp)

Given a datetime.datetime object, return a list of directory levels (as strings).

For example, given “2013-09-08 13:01:44”, return [‘2013’, ‘09’, ‘08’, ‘13’, ‘01’]

coils.time2dir(tstamp)

Given a datetime.datetime object, return a path assembled with os.path.join() for the levels.

coils.time2fname(tstamp, full=False)

Return full path to filename prefix (i.e. without dot extension) represented by given datetime.datetime object.

coils.user_input(field, default='', choices=None, password=False, empty_ok=False, accept=False)

Prompt user for input until a value is retrieved or default is accepted. Return the input.

Arguments:

field - Description of the input being prompted for.

default - Default value for the input accepted with a Return-key.

password - Whether the user input should not be echoed to screen.

empty_ok - Whether it’s okay to accept an empty input.

accept - Whether to skip getting actual user input and just accept the default value, unless prevented by the combination of arguments empty_ok and default. That is, unless default is an empty string and empty_ok is False.

Classes

class coils.Averager(max_count)

Keeps a running average with limited history.

Initialize the averager with maximum number of (latest) samples to keep.

__len__()

Length operator.

add(value)

Add a value, and return current average.

class coils.MapSockServer(host, port, on_action=None, encode=True)

Initialize the server object.

host - socket host

port - socket port

on_action - callback upon action reception,
is called with action string
run()

Continuously retrieve client requests until given “stop” request.

class coils.MapSockClient(host, port, encode=True)

Client to the map server.

Initialize the object.

host - socket host

port - socket port

send(request)

Send request to server and return server response.

class coils.MapSockRequest(action, key=None, value=None)

Request object sent from client to server.

class coils.RateTicker(periods)

Computes rates of ticking.

Initialize the object with a tuple of time periods in seconds. For example, use (60, 300, 900) to track rates at 1, 5 and 15 minute periods (like when reporting system load.)

tick()

Tick the ticker. Return a tuple of values corresponding to periods given in initializer, each value representing the rate of ticks (number of ticks per second) during that period.

class coils.Ring(donor)

Circular data structure implemented as a list.

Initialize the ring with a donor list.

__getitem__(index)
__len__()
first()

Return the first entry.

last()

Return the last entry.

turn()

Turn the ring for a single position. For example, [a, b, c, d] becomes [b, c, d, a].

class coils.SocketTalk(sock, encode=True)

A simple layer of socket communication, implementing send/receive messaging protocol where each (variable length) message is prefixed with a (fixed length) header containing the length of the remaining message data string.

Ideas for protocol and byte-handling are borrowed from:
http://docs.python.org/howto/sockets.html.

Initialize the object with a socket.

static client(addr)

Return a SocketTalk client.

close()
get()

Receive a message. Return the message upon successful reception, or None upon failure.

static pair()

Return a pair of connected SocketTalk peers.

put(message)

Send the given message. Return True if successful, False if not.

static server(addr)

Return a SocketTalk server.

class coils.SortedList(donor=[])

Maintains a list of sorted items, with fast trimming using less-than/greater-than comparison.

Initialize the object with a copy of the donor list, sorted.

add(item)

Add item to the list while maintaining sorted order.

getCountGT(item)

Return number of elements greater than item.

getCountLT(item)

Return number of elements less than item.

removeLT(item)

Trim off any elements less than item. Return number of elements trimmed.

class coils.Timer

Times duration of code blocks.

Initialize the object, marking the current time.

get()

Return a datetime.timedelta object representing time elapsed since object construction, or since last call to this function, whichever is more recent.

getTotal()

Return a datetime.timedelta object representing total time elapsed since construction.