Module kptools

Overview

The kptools module provides some classes that make constructing and managing a Knowbot Program easier than using the KPReprImpl.Representation class by itself. This is accomplished by providing a simpler way to construct and add modules to the KP; by providing a simple mechanism to redirect standard I/O back to the point of origin, and by providing a simple mechanism to track KP migration and termination.

KPReprImpl.Representation is a straightforward implementation of the KPRepr.Representation class; it is not documented separately.)

Classes

Reprsentation

Subclass of KPReprImpl.Representation with added functionality for easily adding modules and submitting the KP.

ReprWrapper

A wrapper class around a KPReprImpl.Representation object that defines methods for accessing the KP's suitcase.

SimpleReporter

A reporting station (see module RS) that supports callback on termination.

To make effective use of callbacks, a KP needs to be submitted using the kpname optional argument (see Representation.submit() below). Whenever a KP with that name terminates, the callback function will be called.

Example:

rs = SimpleReporter()
rs.register_callback('mine', my_callback)
kp.submit('kos', kpname='mine')

KPReporter

A subclass of SimpleReporter above for use in a KP. Its start() and stop() methods manage the KP's main loop instead of the ILU main loop (which cannot be executed directly in a KP).

IOServer

A simple I/O server class useful for redirecting a KP's standard I/O streams.

This implements most of the FileAPI.File interface (which looks a lot like Python's standard file objects). The main use is to provide a simple way to connect the standard I/O stream of a KP to that of its submittor: the submittor instantiates an IOServer instance, and set its SBH in the metadata of the KP as stdin-server, stdout-server and stderr-server. (In fact, there's a true-object-only method that does this for you.)

Constants

DEFAULT_KP_CLASS = "KP"

Default class name for a KP. If the class name is not specified when loading the main module for a KP, the loader methods will use this name. It will not be used if the main module is not specified.

Exceptions

LoadingError

This will be raised by the constructor for the Representation class if a named module could not be located.

Functions

default_kernel ()

Return the default kernel name for KP launches.

Representation Objects

__init__ ([modules[, main[, klass[, path]]]])

The constructor provides for the use of a search path for module loading, with sys.path used by default. (XXX This is probably a poor default.) Modules are loaded into the KP by name. The main module can be distinguished at creation time or after creation using load_main_module() or setting the KP metadata appropriately afterwards.

Arguments:

modules - sequence of string objects
main - string object
klass - string object
path - string object

load_module(name)

Loads a single module by name.

get_path ()

Returns the KP module search path.

load_main_module (name[, klass])

Loads the main module for a KP, setting metadata appropriately. name is the name of the module to load. klass is the name of the KP class within the module. If omitted, klass defaults to DEFAULT_KP_CLASS.

Return conditions are the same as for load_module(). If module loading is successful, the metadata attributes for main-module and knowbot-class are set appropriately.

add_main_module (name, source[, klass])

Add main module from source string. name is the name of the main module. source is the module source code klass is the name of the KP class within the module. The metadata attributes for main-module and knowbot-class are set appropriately. If unset, klass defaults to DEFAULT_KP_CLASS.

get_suitcase_fs ()

Return the suitcase filesystem object for this KP.

add_file (path[, string[, file[, srcpath]]])

Add string, file, or the contents of srcpath to the suitcase of this KP.

add_argv (args)

Assign the KP's sys.argv to the list args.

submit ([kosname[, receiver[, reporter[, kpname[, repid[, repsbh]]]]]])

Submit this KP to a KOS, with a plethora of options. kosname is the name for the KOS to submit to (default: use the receiver argument). receiver is the receiver object (default: look up /kos/kosname/receiver). Exactly one of kosname or receiver should be specified. reporter is the reporting station to use (default: new NullRS instance). kpname is the name for the KP (default: metadata['main-module']; 'kp' if none). repid is the reporting ID for the KP (default: new ID from reporter). repsbh is the String Binding Handle of reporting station (default: reporter.IluSBH()).

Arguments:

kosname - string objects
receiver - receiver object
reporter - reporting station object
kpname - string object
repid - string object
repsbh - string object

Marshal ()

Same as KPReprImpl.Representation.Marshal(), except flushes the suitcase to disk first.

ReprWrapper Objects

__init__ (repr[, copy])

Constructor.

Arguments:

repr - KPRepr object
copy - Boolean

get_suitcase_fs ()

Return the suitcase filesystem object associated with this KP.

get_file (path[, file[, dstpath]])

Reads suitcase file specified by path. If file is non-None, it is assumed to be a file-like object, and the contents of the attribute referenced by path is written to it. If dstpath is specified, then it is opened for writing and the contents of the attribute referenced by path is written to the newly opened file.

SimpleReporter Objects

register_callback (name, callback)

Add function callback as the completion callback for KP name.

wait ()

Tell the reporting station to wait around until KPTerminated() is received. This calls the stop() method.

AllocateID (prefix)

Calculate, save, and return the next valid reporting ID.

KPMigrationReceived (id, kpid, dest)

This is the method that gets called for all reporting stations after a KP successfully completes a migration. This implementation simply sets the pending flag for this KP. (XXX What pending flag?)

KPTerminated (id, reason, details, repr)

This is the method that gets called for all reporting stations after a KP terminates. This implementation calls a callback function if one is registered and calls the stop() method, if the wait() has been specified and we've already received the KPMigrationReceived() message.

start ()

Calls ilutools.RunInterruptableMainLoop(). Can be sub-classed to run a different main loop than the one ILU provides.

stop ()

Calls ilutools.ExitMainLoop(). Can be sub-classed to use a different main loop than ILU's.

KPReporter Objects

This is a derived class of class SimpleReporter above. Only changed methods are listed.

__init__ (kos)

Constructor. Pass the KOS Bastion as argument.

start ()

Calls ilutools.RunInterruptableMainLoop(). Can be subclassed to run a different main loop than the one ILU provides.

stop ()

Calls ilutools.ExitMainLoop(). Can be subclassed to use a different main loop than ILU's.

IOServer Objects

__init__ ([r, [w]])

Constructor.

Arguments:

r - file object to read, default sys.stdin
w - file object to write, default sys.stdout

linktokp (kprepr)

Sets the metadata in the KP to indicate that stdout, stderr, and stdin should be redirected to the String Binding Handle for the current object (self).

The following methods are generally called by the KP (via ILU). Some of these are not really methods but instance attributes that directly reference the corresponding method of the r or w object.

read (size)

readline ()

readlines ()

Call the corresponding method of the r object.

write (string)

writelines (lines)

flush ()

Call the corresponding method of the w object.

close ()

Call the flush() method of the w object.