Module nstools

Overview

The nstools module provides interfaces for interacting with the KOE namespace. The namespace itself is distributed; parts of the namespace are managed by the worldroot servers, Knowbot Service Stations, and perhaps other processes.

Context: An object that behaves similar to a directory in a filesystem: it binds object names to typed object references. Context objects have a simple API that allows manipulation and inspection of the bindings.
Root Context: A designated Context object that serves as the starting point for name lookup operations.
Object name: The name of an object reference in a context.
Descriptor: A structure stored in a context containing a type and an object reference. Performing a name lookup yields a descriptor.
Pathname: A series of object names separated by slashes that direct a corresponding series of lookup operations, each except the last one expecting the descriptor containing a reference to a context object in which the next object name is looked up. Note: A pathname never begins with a "/"; an absolute path is one resolved relative to the Context of the worldroot server, but it isn't distinguished with a slash.

Note: There are two versions of the nstools module -- one for general use, and one for KPs. The interface provided by the KP version is a subset of the general version. This document describes the general version of the module. KPs only have direct access to the functions Lookup() and WorldOpen() and the exception BadPathError. Note that since Lookup() returns a Descriptor instance, and the Open() method of a Descriptor object can return a Context instance, the Descriptor and Context documentation is also relevant.

Classes

Context (context[, parent[, linkname]]) -> instance

This class implements the Context object defined in the ILU Namespace interface. The implementation attempt to perform transparent error recovery when the referred Context object appears to be unresponsive. Class instances store the pathname and root context used to open the current Context. If a communication error occurs using the current Context, the stored information is used to re-open the current context. This is useful in case a a reference to a Context managed by a process that is restarted (e.g. a rebooted kernel).

context: An ILU Context object to wrap around.
parent
linkname: If both are specified, parent specifies a Context object (either an ILU Context object or an nstools.Context object), and linkname specifies the name in the parent context, such that context == parent.Lookup1(linkname).

Descriptor(reference[, typename]) -> instance

This class wraps around an ILU Descriptor record, defined in the Namespace interface. In addition to the dictionary-like interface of ILU records, it provides methods reference() and typename() to reference the record components. It also provides an Open() method that creates an ILU surrogate for the referenced object.

reference: The ILU SBH of the referenced object.
typename: The type of the referenced object, a string of the form "module.interface". Defaults to "Namespace.Context".

Functions

Lookup (context, path) -> Descriptor instance: Perform a complete lookup of the given path, starting at the given context. Raise BadPathError if the entire path is not resolvable. The msg attribute of the exception is the portion of the path that could not be resolved. Otherwise, return the descriptor for the resolved object.
GetWorldroot () -> Context instance: Return a Context object for the worldroot. Raise NoWorldrootError if no valid worldroot server was found. The worldroot SBH is read from the file var/worldroot.sbh.
WorldOpen (path[, typeobj]) -> ILU surrogate object: Equivalent to Lookup(GetWorldroot(), path).Open(typeobj); except that if the Open() call returns None, BadPathError is raised instead. The typeobj argument has the same default as for Open().

Exceptions

The module defines the following exceptions; each is a class. The constructor arguments correspond to the instance variables and default to the empty string ("").

NamespaceError ([msg]): Base class for the other exceptions defined here. Has one instance variable, msg, giving a detailed error message. Converting an instance to a string using repr(), str(), or back quotes yields the value of msg.
NoWorldrootError (sbhfile, [msg]): Exception raised when the worldroot server cannot be reached. Derived from NamespaceError. In addition to the msg instance variable, it has an sbhfile instance variable, which is the filename that was consulted to find the SBH of the worldroot server.
BadPathError ([msg]): Exception raised when a pathname lookup failed for any other reason than a missing worldroot server. Derived from NamespaceError. The only instance variable is msg.

Context Objects

The semantics of these methods are identical to the semantics of the ILU Context class, except that they use Descriptor instances instead of ILU Descriptor records, and they attempt transparent recovery if the referenced ILU Context object appears invalid (see above), and sometimes raises the BadPathError exception instead of Namespace.ResolutionError.

Lookup1 (component) -> Descriptor instance: Resolve the binding for component in this context and return a Descriptor instance for it. Raise BadPathError if no entry with this name exists.
List () -> list of strings: Return a list of all names currently bound in this context.
Bind (name, desc): Create a new binding from name to the object descriptor desc. The desc argument may be a Descriptor instance or an ILU Descriptor record. Raise Namespace.ResolutionError if there is already a binding for name.
Rebind (name, desc): Like Bind(name, desc) except that if a binding for name already exists, the binding is replaced and no exception is raised.
Unbind (name): Remove the binding for name name in this context. Raise Namespace.ResolutionError if there is no binding for name.
GetDescriptor () -> Descriptor instance: Return a Descriptor instance for this context.

Descriptor Objects

reference () -> string: Return the object reference -- the value of the `reference' argument to the constructor.
typename () -> string: Return the object type -- the value of the `typename' argument to the constructor.
Open ([typeobj]) -> ILU surrogate object: Return an ILU surrogate object for the referenced object. If typeobj is given, it must match the object type stored in the Descriptor instance. The surrogate can be used to interact with the object. When there is an error creating the surrogate, no exception is raised, but None is returned.
descriptor_of () -> dictionary{string: string}: Return a Python dictionary containing the typename and reference for the descriptor.