testbeds, prototypes, model: Add docstrings

This adds docstrings for methods of in the testbeds, prototypes and
certain things in the model.

5 files changed, 95 insertions, 29 deletions

diff --git a/rumba/testbeds/dockertb.py b/rumba/testbeds/dockertb.py
index d018f8c..6d7c7b5 100644
--- a/rumba/testbeds/dockertb.py
+++ b/rumba/testbeds/dockertb.py
@@ -36,8 +36,19 @@ from rumba.executors.docker import DockerExecutor
 logger = log.get_logger(__name__)
 
 class Testbed(mod.Testbed):
+    """
+    Represents a docker testbed.
+    """
     def __init__(self, exp_name, base_image, pull_image=True,
                  use_ovs=False):
+        """
+        Initializes the testbed class.
+
+        :param exp_name: The experiment name.
+        :param base_image: The docker base image.
+        :param pull_image: Retrieve the docker image from the Docker hub?
+        :param use_ovs: Use the OVS switch instead of the Linux bridge?
+        """
         mod.Testbed.__init__(self, exp_name, "", "", "")
 
         img = base_image.rsplit(":", 1)
@@ -159,7 +170,7 @@ class Testbed(mod.Testbed):
 
         logger.info("Experiment swapped in")
 
-    def swap_out(self, experiment):
+    def _swap_out(self, experiment):
         for name, container in self.running_containers.items():
             container.remove(force=True)
 
@@ -184,4 +195,4 @@ class Testbed(mod.Testbed):
 
         self.running_containers = {}
 
-        logger.info("Experiment swapped out")
\ No newline at end of file
+        logger.info("Experiment swapped out")
diff --git a/rumba/testbeds/emulab.py b/rumba/testbeds/emulab.py
index 605e326..690612f 100644
--- a/rumba/testbeds/emulab.py
+++ b/rumba/testbeds/emulab.py
@@ -63,14 +63,14 @@ class Testbed(mod.Testbed):
         self.url = url
         self.image = image
         self.ip = dict()
-        self.ops_ssh_config = mod.SSHConfig(self.ops_server())
+        self.ops_ssh_config = mod.SSHConfig(self._ops_server())
 
         self.executor = SSHExecutor
 
         if "wall" in url:
             self.http_proxy="https://proxy.atlantis.ugent.be:8080"
 
-    def ops_server(self):
+    def _ops_server(self):
         """
         Return server name of the ops-server (is testbed specific).
 
@@ -78,7 +78,7 @@ class Testbed(mod.Testbed):
         """
         return 'ops.' + self.url
 
-    def full_name(self, node_name):
+    def _full_name(self, node_name):
         """
         Return server name of a node.
 
@@ -88,7 +88,7 @@ class Testbed(mod.Testbed):
         return node_name + '.' + self.exp_name + '.' + \
             self.proj_name + '.' + self.url
 
-    def get_experiment_list(self, project_name=None):
+    def _get_experiment_list(self, project_name=None):
         """
         Get list of made emulab experiments accessible with your credentials.
 
@@ -106,7 +106,7 @@ class Testbed(mod.Testbed):
         except:
             return {project_name: {project_name: []}}
 
-    def swap_exp_in(self):
+    def _swap_exp_in(self):
         """
         Swaps experiment in.
 
@@ -139,7 +139,7 @@ class Testbed(mod.Testbed):
         proj_name = self.proj_name
         exp_name = self.exp_name
 
-        exp_list = self.get_experiment_list()
+        exp_list = self._get_experiment_list()
 
         try:
             if exp_name in exp_list[proj_name][proj_name]:
@@ -148,7 +148,7 @@ class Testbed(mod.Testbed):
         except:
             logger.info("First experiment to be created for that project.")
 
-        ns = self.generate_ns_script(experiment)
+        ns = self._generate_ns_script(experiment)
         dest_file_name = '/users/' + self.username + \
                          '/temp_ns_file.%s.ns' % os.getpid()
         ssh.write_text_to_file(self, self.ops_ssh_config, ns, dest_file_name)
@@ -167,7 +167,7 @@ class Testbed(mod.Testbed):
             ssh.execute_command(self, self.ops_ssh_config,
                                 'rm ' + dest_file_name)
 
-    def generate_ns_script(self, experiment):
+    def _generate_ns_script(self, experiment):
         """
         Generate ns script based on network graph.
         Enables to customize default node image.
@@ -198,7 +198,7 @@ class Testbed(mod.Testbed):
 
         return ns2_script
 
-    def wait_until_nodes_up(self):
+    def _wait_until_nodes_up(self):
         """
         Checks if nodes are up.
         """
@@ -221,7 +221,7 @@ class Testbed(mod.Testbed):
             logger.info("Still waiting")
             time.sleep(5)
 
-    def complete_experiment_graph(self, experiment):
+    def _complete_experiment_graph(self, experiment):
         """
         Gets the interface (ethx) to link mapping.
 
@@ -229,7 +229,7 @@ class Testbed(mod.Testbed):
         """
 
         for node in experiment.nodes:
-            node.ssh_config.hostname = self.full_name(node.name)
+            node.ssh_config.hostname = self._full_name(node.name)
             node.ssh_config.set_username(self.username)
             node.ssh_config.set_password(self.password)
 
@@ -273,12 +273,12 @@ class Testbed(mod.Testbed):
         mod.Testbed.swap_in(self, experiment)
 
         self._create_experiment(experiment)
-        wait = self.swap_exp_in()
+        wait = self._swap_exp_in()
         if wait:
-            self.wait_until_nodes_up()
-        self.complete_experiment_graph(experiment)
+            self._wait_until_nodes_up()
+        self._complete_experiment_graph(experiment)
 
-    def swap_out(self, experiment):
+    def _swap_out(self, experiment):
         """
         Swaps experiment out
 
diff --git a/rumba/testbeds/jfed.py b/rumba/testbeds/jfed.py
index a1ceded..24e6737 100644
--- a/rumba/testbeds/jfed.py
+++ b/rumba/testbeds/jfed.py
@@ -47,11 +47,30 @@ logger = log.get_logger(__name__)
 
 
 class Testbed(mod.Testbed):
-
+    """
+    Represents a jFed testbed.
+    """
     def __init__(self, exp_name, username, cert_file, exp_hours="2",
                  proj_name="ARCFIRE", authority="wall2.ilabt.iminds.be",
                  image=None, image_custom=False, image_owner=None,
                  use_physical_machines=None):
+        """
+        Initializes the testbed class.
+
+        :param exp_name: The experiment name.
+        :param username: User of the experiment.
+        :param cert_file: Certificate file of the user.
+        :param exp_hours: Duration of the experiment.
+        :param proj_name: Project name of the experiment.
+        :param authority: Actual testbed authority to use.
+        :param image: Specific image to use.
+        :param image_custom: Is the image a custom one?
+        :param image_owner: Creator of the image.
+        :param use_physical_machines: Try to allocate physical machines.
+
+        .. note:: Supported authorities are wall1.ilabt.iminds.be,
+                  wall2.ilabt.iminds.be, exogeni.net, exogeni.net:umassvmsite.
+        """
         passwd = getpass.getpass(prompt="Password for certificate file: ")
         mod.Testbed.__init__(self,
                              exp_name,
@@ -110,7 +129,13 @@ class Testbed(mod.Testbed):
             os.remove(tarball)
         self.flags['no_vlan_offload'] = True
 
-    def create_rspec(self, experiment):
+    def _create_rspec(self, experiment):
+        """
+        Create an rspec which is an XML file with configuration for jFed.
+
+        :param experiment: The experiment.
+        :return: rspec of the experiment.
+        """
         impl = xml.getDOMImplementation()
         doc = impl.createDocument(None, "rspec", None)
 
@@ -197,7 +222,12 @@ class Testbed(mod.Testbed):
         file.write(doc.toprettyxml())
         file.close()
 
-    def swap_out(self, experiment):
+    def _swap_out(self, experiment):
+        """
+        Swaps experiment out
+
+        :param experiment: The experiment.
+        """
         try:
             subprocess.check_call(["java", "-jar", self.jfed_jar, "delete",
                                    "-S", self.proj_name, "-s", self.exp_name,
@@ -207,9 +237,16 @@ class Testbed(mod.Testbed):
             raise
 
     def _swap_in(self, experiment):
+        """
+        Swaps experiment in
+
+        :param experiment: The experiment.
+        """
+        mod.Testbed.swap_in(self, experiment)
+
         for node in experiment.nodes:
             node.ssh_config.set_http_proxy(self.http_proxy)
-        self.create_rspec(experiment)
+        self._create_rspec(experiment)
 
         auth_name_r = self.auth_name.replace(".", "-")
 
diff --git a/rumba/testbeds/local.py b/rumba/testbeds/local.py
index 068ee03..f7b505d 100644
--- a/rumba/testbeds/local.py
+++ b/rumba/testbeds/local.py
@@ -61,7 +61,7 @@ class Testbed(mod.Testbed):
 
         logger.info("Experiment swapped in")
 
-    def swap_out(self, experiment):
+    def _swap_out(self, experiment):
         """
         Does not actually swap the experiment out.
 
diff --git a/rumba/testbeds/qemu.py b/rumba/testbeds/qemu.py
index 5636e75..218f3e1 100644
--- a/rumba/testbeds/qemu.py
+++ b/rumba/testbeds/qemu.py
@@ -46,9 +46,27 @@ logger = log.get_logger(__name__)
 
 
 class Testbed(mod.Testbed):
+    """
+    Represents a QEMU testbed.
+    """
     def __init__(self, exp_name, bzimage_path=None, initramfs_path=None,
                  proj_name="ARCFIRE", password="root", username="root",
                  use_vhost=True):
+        """
+        Initializes the testbed class.
+
+        :param exp_name: The experiment name.
+        :param bzimage_path: Path of the bzimage.
+        :param initramfs_path: Path of the initramfs.
+        :param proj_name: Project name of the experiment.
+        :param password: Password of the user.
+        :param username: User of the VM.
+        :param use_vhost: Use virtual hosting or not?
+
+        .. note:: In case no bzimage or initramfs is provided, Rumba
+                  will automatically download the latest version available
+                  from a repository.
+        """
         mod.Testbed.__init__(self, exp_name,
                              username, password,
                              proj_name, system_logs=['/var/log/messages'])
@@ -63,7 +81,7 @@ class Testbed(mod.Testbed):
         self.executor = SSHExecutor(self)
 
     # Prepend sudo to all commands if the user is not 'root'
-    def may_sudo(self, cmds):
+    def _may_sudo(self, cmds):
         if os.geteuid() != 0:
             for i, cmd in enumerate(cmds):
                 cmds[i] = "sudo %s" % cmd
@@ -106,7 +124,7 @@ class Testbed(mod.Testbed):
         else:
             results_queue.put("Command chain ran with %d error(s)" % errors)
 
-    def recover_if_names(self, experiment):
+    def _recover_if_names(self, experiment):
         for node in experiment.nodes:
             for ipcp in node.ipcps:
                 if isinstance(ipcp, mod.ShimEthIPCP):
@@ -228,7 +246,7 @@ class Testbed(mod.Testbed):
         executors = []
         for i, script in enumerate(br_tab_scripts):
             names.append(i)
-            self.may_sudo(script)
+            self._may_sudo(script)
             args.append(script)
             executors.append(executor)
 
@@ -335,7 +353,7 @@ class Testbed(mod.Testbed):
 
         logger.info('All VMs are running. Moving on...')
 
-        self.recover_if_names(experiment)
+        self._recover_if_names(experiment)
 
         for node in experiment.nodes:
             pub_key = os.path.join(os.path.expanduser("~"),
@@ -349,7 +367,7 @@ class Testbed(mod.Testbed):
 
         logger.info('Experiment has been successfully swapped in.')
 
-    def swap_out(self, experiment):
+    def _swap_out(self, experiment):
         """
         :rtype str
         :return: The script to tear down the experiment
@@ -389,7 +407,7 @@ class Testbed(mod.Testbed):
                              'ip tuntap del mode tap name %(tap)s'
                              % {'tap': tap, 'br': shim.name}
                              ).split('\n')
-                self.may_sudo(commands)
+                self._may_sudo(commands)
 
                 names.append(index)
                 index += 1
@@ -412,7 +430,7 @@ class Testbed(mod.Testbed):
                          'brctl delbr %(br)s'
                          % {'br': shim.name}
                          ).split('\n')
-            self.may_sudo(commands)
+            self._may_sudo(commands)
 
             names.append(index)
             index += 1