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.
- 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).
Parameters:
- 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.
Parameters:
- 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".
- 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().
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.
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.
- 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.