Docstringed IFormat interface and concrete subclasses

MDANSE/Framework/Formats/ASCIIFormat.py

@@ -25,9 +25,9 @@
 #Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 ''' 
-Created on Mar 27, 2015
+Created on May 26, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os
@@ -39,6 +39,10 @@ import numpy
 from MDANSE.Framework.Formats.IFormat import IFormat
 
 class ASCIIFormat(IFormat):
+    '''
+    This class handles the writing of output variables in ASCII format. Each output variable is written into separate ASCII files which are further
+    added to a single archive file. 
+    '''
     
     type = 'ascii'
 
@@ -48,6 +52,18 @@ class ASCIIFormat(IFormat):
     
     @classmethod
     def write(cls, filename, data, header=""):
+        '''
+        Write a set of output variables into a set of ASCII files.
+        
+        Each output variable will be output in a separate ASCII file. All the ASCII files will be compressed into a tar file.
+        
+        :param filename: the path to the output archive file that will contain the ASCII files written for each output variable.
+        :type filename: str
+        :param data: the data to be written out.
+        :type data: dict of Framework.OutputVariables.IOutputVariable
+        :param header: the header to add to the output file.
+        :type header: str
+        '''
                 
         filename = os.path.splitext(filename)[0]
         filename = "%s_%s.tar" % (filename,cls.type)
@@ -73,6 +89,18 @@ class ASCIIFormat(IFormat):
 
     @classmethod
     def write_array(cls, fileobject, array, slices=None):
+        '''
+        Write an Framework.OutputVariables.IOutputVariable into a file-like object
+        
+        :param fileobject: the file object where the output variable should be written.
+        :type fileobject: python file-like object
+        :param array: the output variable to write (subclass of NumPy array).
+        :type array: Framework.OutputVariables.IOutputVariable
+        :param slices: the slices of the output variable to write. If None, the whole output variable will be written.
+        :type: python slice
+        
+        :attention: this is a recursive method.
+        '''
         
         if slices is None:
             slices = [0]*array.ndim

MDANSE/Framework/Formats/IFormat.py

@@ -25,24 +25,37 @@
 #Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 ''' 
-Created on Mar 27, 2015
+Created on May 26, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
-import abc
-
 from MDANSE import REGISTRY
 
 class IFormat(object):
     '''
-    This is the base class for MDANSE data.
+    This is the base class for writing MDANSE output data. In MDANSE, the output of an analysis can be written in different file format.
+    
+    Currently, MDANSE supports NetCDF, SVG and ASCII output file formats. To introduce a new file output file format, just create a new concrete 
+    subclass of IFormat and overload the "write" class method as defined in IFormat base class which will actually write the output variables, 
+    and redefine the "type", "extension" and "extensions" class attributes.
     '''
     
     __metaclass__ = REGISTRY
     
     type = "format"
-    
-    @abc.abstractmethod
-    def write(self, filename, data, header=""):
+
+    @classmethod    
+    def write(cls, filename, data, header=""):
+        '''
+        Write a set of output variables into filename using a given file format.
+        
+        :param filename: the path to the output file.
+        :type filename: str
+        :param data: the data to be written out.
+        :type data: dict of Framework.OutputVariables.IOutputVariable
+        :param header: the header to add to the output file.
+        :type header: str
+        '''
+        
         pass

MDANSE/Framework/Formats/NetCDFFormat.py

@@ -25,9 +25,9 @@
 #Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 ''' 
-Created on Mar 27, 2015
+Created on May 26, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os
@@ -39,6 +39,9 @@ from Scientific.IO.NetCDF import NetCDFFile
 from MDANSE.Framework.Formats.IFormat import IFormat
 
 class NetCDFFormat(IFormat):
+    '''
+    This class handles the writing of output variables in NetCDF file format.
+    '''
 
     type = 'netcdf'
 
@@ -49,10 +52,14 @@ class NetCDFFormat(IFormat):
     @classmethod
     def write(cls, filename, data, header=""):
         '''
-        This method writes (or append) a list of MDANSE.Job.Output.OutputVariable objects to a NetCDF file.
-    
-        @param filename: the path for the output NetCDF file.
-        @type filename: string
+        Write a set of output variables into a NetCDF file.
+                
+        :param filename: the path to the output NetCDF file.
+        :type filename: str
+        :param data: the data to be written out.
+        :type data: dict of Framework.OutputVariables.IOutputVariable
+        :param header: the header to add to the output file.
+        :type header: str
         '''
                 
         filename = os.path.splitext(filename)[0]

MDANSE/Framework/Formats/SVGFormat.py

@@ -25,9 +25,9 @@
 #Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 ''' 
-Created on Mar 27, 2015
+Created on May 26, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os
@@ -46,6 +46,12 @@ def format_unit_string(unitString):
     return re.sub('[%()]','',unitString)
 
 class SVGFormat(IFormat):
+    '''
+    This class handles the writing of output variables in SVG format. Each output variable is written into separate SVG files which are further
+    added to a single archive file.
+    
+    :attention: only the 1D output variables can be written in SVG file format.
+    '''
 
     type = 'svg'
     
@@ -55,6 +61,18 @@ class SVGFormat(IFormat):
         
     @classmethod
     def write(cls,filename,data, header=""):
+        '''
+        Write a set of output variables into a set of SVG files.
+        
+        Each output variable will be output in a separate SVG file. All the SVG files will be compressed into a tar file.
+        
+        :param filename: the path to the output archive file that will contain the SVG files written for each output variable.
+        :type filename: str
+        :param data: the data to be written out.
+        :type data: dict of Framework.OutputVariables.IOutputVariable
+        :param header: the header to add to the output file.
+        :type header: str
+        '''
 
         filename = os.path.splitext(filename)[0]
         filename = "%s.tar" % filename