Continue to improve option docs

docs/api.rst

@@ -19,13 +19,6 @@ Ensemble
 .. automodule:: pysumma.ensemble
     :members:
 
-File Manager
-=========
-.. automodule:: pysumma.file_manager
-    :show-inheritance:
-    :members:
-    :inherited-members:
-
 Decisions
 =========
 .. automodule:: pysumma.decisions

pysumma/decisions.py

@@ -62,7 +62,7 @@ def set_option(self, key, value):
             else:
                 raise
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         decision, *value = line.split('!')[0].split()
         if isinstance(value, list):
             value = " ".join(value).replace("'", "")

pysumma/file_manager.py

@@ -35,17 +35,32 @@ def __str__(self):
 class FileManager(OptionContainer):
     """
     The FileManager object provides an interface to
-    a SUMMA file manager file.
+    a SUMMA file manager file. Generally, this object
+    is not meant to be instantiated on its own (though
+    it can be), but rather as a member of a simulation
+    object.
+
+    Example usage::
+
+        import pysumma as ps
+        s = ps.Simulation('summa.exe', 'file_manager.txt')
+        print(s.manager)
+
+    Parameters
+    ----------
+    path (string):
+        The path to the file manager file.
     """
 
     def __init__(self, path):
         super().__init__(path, FileManagerOption)
 
     def set_option(self, key, value):
+        """Change the value of an option"""
         o = self.get_option(key)
         o.set_value(value)
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         return (OPTION_NAMES[self.opt_count],
                 line.split('!')[0].replace("'", "").strip())
 

pysumma/force_file_list.py

@@ -30,7 +30,7 @@ def set_option(self, key, value):
         o = self.get_option(key)
         o.set_value(value)
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         file_name = line.replace("'", "")
         return (os.path.join(self.prefix, file_name.strip()), )
 

pysumma/local_param_info.py

@@ -56,10 +56,10 @@ def read(self, path):
                 self.header.append(line)
             elif not line.startswith('!'):
                 self.options.append(self.OptionType(
-                    *self.get_constructor_args(line)))
+                    *self._get_constructor_args(line)))
                 self.opt_count += 1
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         param, *value = line.split('|')
         default, low, high = map(lambda x: float(x.strip().replace('d', 'e')),
                                  value)

pysumma/option.py

@@ -16,7 +16,7 @@ def __str__(self):
         return "{} : {}".format(self.name, self.value)
 
 
-class OptionContainer(object):
+class OptionContainer():
     """
     Base implementation for representing text based configuration
     files for SUMMA. This class is meant to be extended rather than
@@ -39,7 +39,7 @@ def set_option(self):
         """This has to be implemented by subclasses"""
         raise NotImplementedError()
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         """
         This has to be implemented by subclasses
 
@@ -62,11 +62,20 @@ def read(self, path):
                 self.header.append(line)
             elif not line.startswith('!'):
                 self.options.append(self.OptionType(
-                    *self.get_constructor_args(line)))
+                    *self._get_constructor_args(line)))
                 self.opt_count += 1
 
     def write(self, path=None):
-        """Write the configuration given the values of the options"""
+        """
+        Write the configuration based on the string
+        representation of the OptionType of the instance.
+
+        Parameters
+        ----------
+        path: (string, optional)
+            Where to write the file. If not provided
+            the original file will be overwritten.
+        """
         self.validate()
         if not path:
             path = self.original_path
@@ -75,7 +84,18 @@ def write(self, path=None):
             f.writelines((str(o) + '\n' for o in self.options))
 
     def get_option(self, name, strict=False):
-        """Retrieve an option"""
+        """
+        Retrieve an option
+
+        Parameters
+        ----------
+        name: (string)
+            The name of the option to search for
+        strict: (bool, optional)
+            Whether to raise an error if the option
+            is not found. Defaults to ``False``, which
+            does not raise exceptions.
+        """
         for o in self.options:
             if name == o.name:
                 return o
@@ -84,7 +104,19 @@ def get_option(self, name, strict=False):
         return None
 
     def get_value(self, name, strict=False):
-        """Retrieve the value of a given option"""
+        """
+        Retrieve the value of a given option
+
+        Parameters
+        ----------
+        name: (string)
+            The name of the option whose value
+            to search for
+        strict: (bool, optional)
+            Whether to raise an error if the option
+            is not found. Defaults to ``False``, which
+            does not raise exceptions.
+        """
         for o in self.options:
             if name == o.name:
                 return o.value
@@ -93,7 +125,19 @@ def get_value(self, name, strict=False):
         return None
 
     def remove_option(self, name, strict=False):
-        """Remove an option"""
+        """
+        Remove an option
+
+        Parameters
+        ----------
+        name: (string)
+            The name of the option whose value
+            to remove
+        strict: (bool, optional)
+            Whether to raise an error if the option
+            is not found. Defaults to ``False``, which
+            does not raise exceptions.
+        """
         for i, o in enumerate(self.options):
             if name == o.name:
                 return self.options.pop(i)
@@ -102,6 +146,7 @@ def remove_option(self, name, strict=False):
         return None
 
     def clear(self):
+        """Clear all options"""
         self.options = []
 
     def validate(self):

pysumma/output_control.py

@@ -93,7 +93,6 @@ def set_option(self, name=None, period=None, sum=0, instant=1,
         """
         try:
             o = self.get_option(name, strict=True)
-            print(o)
             o.period = period
             o.sum = sum
             o.instant = instant
@@ -110,5 +109,5 @@ def set_option(self, name=None, period=None, sum=0, instant=1,
             else:
                 raise
 
-    def get_constructor_args(self, line):
+    def _get_constructor_args(self, line):
         return [l.strip() for l in line.split('!')[0].split('|')]