= Topdl Library =

This page describes the python library for manipulating topologies that follow the [TopDl topdl] model and are generally output in the topdl language.  It is broken up into a reference section describing the various python classes and procedures and an examples section.

= Reference =

== Installing and Accessing ==

The topdl library is available as oart of the DETER module of the DETER federation system.  Any system that has fedd installed will have topdl installed as well.  In particular, {{{users.isi.deterlab.net}}} has the library installed.

To install the library separately, follow the [FeddDownload#GitAccess instructions for getting fedd from git], make the distribution, and install the {{{deter-data-}}}''version''{{{.tar.gz}}} tar file using the [FeddDownload#DownloadingandInstallingthetarfile same procedure for installing the fedd tar file].  Installing all of fedd will work as well, of course.

Once the library is installed, python programs can access it by:

{{{
#!/usr/bin/env python

from deter import topdl
}}}

== The Classes ==

The class hierarchy mirrors the entities of the [TopDl topdl model].  Where the description of the model glosses over the details of the classes that parameterize the top-level abstractions, this reference will discuss them all.  Each of these classes is a python class, and can be created and manipulated independently, but in a proper topology they are grouped together.

A Substrate object has members that are Capacity and Latency objects.  This listing shows that nesting:

 * Substrate
   * Capacity (0 or 1)
   * Latency (0 or 1)
   * Attribute (0 or more)

The other common element, a Computer object, has the following nested objects:

 * [TopdlLibrary#ComputerClass Computer]
  * CPU (0 or more)
    * Attribute (0 or more)
  * !OperatingSystem (0 or more)
    * Attribute
  * Software (0 or more)
    * Attribute (0 or more)
  * Storage
    * Attribute
  * Interface (0 or more)
    * Capacity (0 or 1)
    * Latency (0 or 1)
    * Attribute (0 or more)
  * Service (0 or more)
    * !ServiceParam (0 or more)

Most classes can have attributes attached to them that contain extention attributes that different applications make use of.  The presence or absence of an optional nested object does not mean the presence or absence of the thing it describes, but that the description is unbound.  As [TopDl#Representation we have seen] a Computer without a nested CPU object does not describe a computer without a CPU, but a computer with no constraints on the CPU.
  
== Adaptive Constructors ==

The constructors of the various topdl classes will accept contained classes in several formats.  They will always accept an object of the relevant class.  They will also take a dict that maps constructor parameters to values for the given class.  Examples make this clearer than description.

The following calls to create a CPU object are equivalent:

{{{
cpu = topdl.CPU(type='Intel', attribute=[topdl.Attribute(attribute='clock_rate', value='1Ghz')])
}}}

and

{{{
cpu = topdl.CPU(type='Intel', attribute=[{'attribute': 'clock_rate', 'value': '1Ghz'}])
}}}


and 

{{{
cpu = topdl.CPU(**{'type': 'Intel', 'attribute' : [ {'attribute': 'clock_rate', 'value': '1Ghz'}]})
}}}

That is, inner class parameters can be specified using dicts directly, and a top level dict can user the standard ** operator

== Topdl Class Features ==

All topdl classes implement the following methods:

 {{{set_attribute(self, key, value)}}}::
   Attach an user-defined attribute with the given key and value to this object; value and key are strings.  The method includes a key/value pair (encoded as an [TopdlLibrary#Attribute attribute object]) into the {{{attribute}}} member of the object.  If an attribute with the given key exists, it is overwritten. 
   This method accesses the attribute member of the given object, not any named members. Objects that do not have an {{{attribute}}} member silently discard the operation.
 {{{get_attribute(self, key)}}}::
   Return the attribute of this object with the given key.  The attribute - a string - is returned.  If no such attribute exists, or the object has no {{{attribute}}} member, return None.
 {{{remove_attribute(self, key)}}}::
   If an attribute with the given key exists, remove it.
 {{{clone(self)}}}::
   Returns a deep copy of this object.
 {{{to_dict(self)}}}::
   Return the object as a python dict.  No copies are made, so make modifications with caution.
 {{{to_xml(self)}}}::
   Return the XML encoding (from the topdl language) of this object (and nested objects)

== Computer Class ==

A Computer object is a programmable computer in a topology.  A webserver is well represented by a computer, as is a desktop.  
It has the following members:

 {{{name}}}::
   The unique name of the computer in the topology, a string.  Other names may be assigned in the {{{localname}}} attribute.
 {{{cpu}}}::
   A list of [TopdlLibrary#CPUObject CPU objects] that describe the CPUs of the machine.  The list may be empty, meaning no CPU requirements or information are present.
 {{{software}}}::
   A list of [TopdlLibrary#SoftwareObject Software objects] that describe the software to install.  The list may be empty, meaning no software is to be installed.
 {{{storage}}}::
    A list of [TopdlLibrary#StorageObject Storage objects] that describe the storage present the machine.  Storage objects can describe memory or persistent storage requirements.  The list may be empty, meaning no storage requirements or information are present.
 {{{interface}}}::
   A list of [TopdlLibrary#InterfaceObject Interface objects] that describe connections of the Computer to communications substrates.  The list may be empty, meaning that the computer is not connected to any substrates.
 {{{attribute}}}::
   A list of [TopdlLibrary#AttributeObject Attribute objects] that are attached to the machine.  The list may be empty.
 {{{localname}}}::
   A list of strings giving alternative names for the object.  When a machine is allocated to a testbed the DNS names assigned to the machine are given as {{{localname}}}s.  The list may be empty, meaning no such alternatives exist.
 {{{status}}}::
   A string indicating the current status of the Computer (if any).  Valid values are
     * "empty" - no allocation of resources has been attempted - generally not applied to Computers
     * "active" - Computer is functioning as part of an experiment
     * "inactive" - Computer is allocated, but not functioning
     * "starting" - Computer is transitioning from "inactive" to "active"
     * "terminating" - Computer is transitioning from "active" to "inactive"
     * "failed" - an allocation of resources has failed - generally not applied to Computers
 {{{service}}}::
   A list of [TopdlLibrary#ServiceObject Service objects] that describe the services this machine uses or supplies of the machine.  These are generally used by the federation system, and their definition is somewhat in flux. The list may be empty.
 {{{operation}}}::
   A list of strings that describe the valid operations on the machine.  These are generally used by the federation system, and their definition is somewhat in flux.The list may be empty.



= Examples =