Merge branch 'develop' into feature/sherman/consolidateVerbosityApproach

Author: rrsettgast

pygeos_package/pygeos/__init__.py

@@ -1,2 +1,3 @@
-
-
+"""@package pygeos
+A python module that enables advanced xml features for GEOSX.
+"""

pygeos_package/pygeos/__main__.py

@@ -1,10 +1,18 @@
+"""Command line tools for pygeos"""
 
 import argparse
 from pygeos import xml_processor
 
 
-# Entry point for the pygeos console script
 def main():
+  """Entry point for the pygeos console script
+
+  @arg input Input file name
+  @arg -o/--output Output filename (default = randomly generated string)
+  @arg -s/--schema GEOSX schema to use for validating the generated xml
+  @arg -v/--verbose Verbosity level
+  """
+
   # Parse the user arguments
   parser = argparse.ArgumentParser()
   parser.add_argument('input', type=str, help='Input file name')

pygeos_package/pygeos/format_xml.py

@@ -1,3 +1,5 @@
+"""Tools for managing regular expressions in pygeos"""
+
 import re
 
 
@@ -26,9 +28,11 @@
 symbolic_format = '%1.6e'
 
 
-# This function is used to evaluate symbolic expressions that are identified
-# using the patterns['symbolic'] regex
 def SymbolicMathRegexHandler(match):
+  """Evaluate symbolic expressions that are identified using the regex_tools.patterns['symbolic'].
+
+     @param match A matching string identified by the regex.
+  """
   k = match.group(1)
   if k:
     # Sanitize the input
@@ -43,13 +47,22 @@ def SymbolicMathRegexHandler(match):
     return
 
 
-# This class is used to substitute matched values with those stored in a dict
 class DictRegexHandler():
+  """This class is used to substitute matched values with those stored in a dict."""
+
   def __init__(self):
-    # Substitution definitions
+    """Initialize the handler with an empty target list.
+       The key/value pairs of self.target indicate which values
+       to look for and the values they will replace with.
+    """
     self.target = {}
 
   def __call__(self, match):
+    """Replace the matching strings with their target.
+
+       @param match A matching string identified by the regex.
+    """
+
     k = match.group(1)
     if k:
       if (k not in self.target.keys()):

pygeos_package/pygeos/regex_tools.py

@@ -1,14 +1,17 @@
+"""Tools for reading/writing GEOSX ascii tables"""
 
 import numpy as np
 
 
-# Write an GEOS-compatible ascii table
-#   axes_values = A list of the axes values in order
-#   properties = A dictionary of properties given as an ndarray
-#                The shape of the array must be consistent with the axes
-#   axes_names = A list of axes names (optional)
-#   string_format = Format for table values
 def write_GEOS_table(axes_values, properties, axes_names=['x', 'y', 'z', 't'], string_format='%1.5e'):
+  """Write an GEOS-compatible ascii table.
+
+     @param axes_values List of arrays containing the coordinates for each axis of the table.
+     @param properties Dict of arrays with dimensionality/size defined by the axes_values
+     @param axes_names Names for each axis (default = ['x', 'y', 'z', 't'])
+     @param string_format Format for output values (default = %1.5e)
+  """
+
   # Check to make sure the axes/property files have the correct shape
   axes_shape = tuple([len(x) for x in axes_values])
   for k in properties.keys():
@@ -25,11 +28,13 @@ def write_GEOS_table(axes_values, properties, axes_names=['x', 'y', 'z', 't'], s
     np.savetxt('%s.geos' % (k), tmp, fmt=string_format, delimiter=',')
 
 
-# Read an GEOS-compatible ascii table
-#   axes_files = A list of the axes file names in order
-#   property_files = A list of the property file names
 def read_GEOS_table(axes_files, property_files):
-  # Open spatial files
+  """Read an GEOS-compatible ascii table.
+
+     @param axes_files List of the axes file names in order.
+     @param property_files List of property file names
+     @return List of axis definitions, dict of property values
+  """
   axes_values = []
   for f in axes_files:
     axes_values.append(np.loadtxt('%s.geos' % (f), unpack=True, delimiter=','))
@@ -44,8 +49,9 @@ def read_GEOS_table(axes_files, property_files):
   return axes_values, properties
 
 
-# Example of how to read/write GEOS tables using the above functions
 def write_read_GEOS_table_example():
+  """Table read / write example."""
+
   # Define table axes
   a = np.array([0.0, 1.0])
   b = np.array([0.0, 0.5, 1.0])

pygeos_package/pygeos/table_generator.py

@@ -1,19 +1,28 @@
+"""Tool for generating test xml files for processing."""
 
 from lxml import etree as ElementTree
 import os
 
 
-# Format the xml files to enable comparison
 def pretty_print_xml(init, final):
+  """Format the xml files to enable comparison
+
+     @param init The input file name.
+     @param final The output file name.
+  """
   parser = ElementTree.XMLParser(remove_comments=True, remove_blank_text=True)
   tree = ElementTree.parse(init, parser)
   tree.write(final, pretty_print=True)
   os.remove(init)
 
 
-# Build example input/output xml files, which can be used to test the parser
-# These are derived from a GEOSX integrated test xml
 def generate_test_xml_files(root_dir):
+  """Build example input/output xml files, which can be used to test the parser.
+     These are derived from a GEOSX integrated test xml.
+
+     @param root_dir The folder to write the example xml files.
+  """
+
   # Build segments of an xml file that can be compiled to form a test
   # File header/footer
   xml_header = """<Problem>"""

pygeos_package/pygeos/tests/generate_test_xml.py

@@ -1,17 +1,24 @@
+"""Tools for managing units in GEOSX"""
 
 import re
 from pygeos import regex_tools
 
 
-# A structure for creating and applying unit definitions
 class UnitManager():
+  """This class is used to manage unit definitions."""
+
   def __init__(self):
+    """Initialize the class by creating an instance of the dict regex handler, building units."""
     self.units = {}
     self.unitMatcher = regex_tools.DictRegexHandler()
     self.buildUnits()
 
-  # Evaluate the symbolic expression
   def __call__(self, unitStruct):
+    """Evaluate the symbolic expression for matched strings.
+
+       @param unitStruct A list containing the variable scale and the unit definition.
+    """
+
     # Replace all instances of units in the string with their scale defined in self.units
     symbolicUnits = re.sub(regex_tools.patterns['units_b'], self.unitMatcher, unitStruct[1])
 
@@ -26,14 +33,18 @@ def __call__(self, unitStruct):
     str_value = re.sub(regex_tools.patterns['strip_trailing_b'], '', str_value)
     return str_value
 
-  # This function is called when the regex identifies unit definitions in a string
   def regexHandler(self, match):
+    """Split the matched string into a scale and unit definition.
+
+       @param match The matching string from the regex.
+    """
     # The first matched group includes the scale of the value (e.g. 1.234)
     # The second matches the string inside the unit definition (e.g. m/s**2)
     return self.__call__([match.group(1), match.group(2)])
 
-  # Build the unit definitions
   def buildUnits(self):
+    """Build the unit definitions."""
+
     # Long, short names for SI prefixes
     prefixes = {'giga':  {'value': 1e9,  'alt': 'G'},
                 'mega':  {'value': 1e6,  'alt': 'M'},

pygeos_package/pygeos/unit_manager.py

@@ -1,3 +1,5 @@
+"""Tools for processing xml files in GEOSX"""
+
 from lxml import etree as ElementTree
 from lxml.etree import XMLSyntaxError
 import re
@@ -10,9 +12,14 @@
 parameterHandler = regex_tools.DictRegexHandler()
 
 
-# Merge nodes in an included file into the current
-# structure level by level
 def merge_xml_nodes(existingNode, targetNode, level):
+  """Merge nodes in an included file into the current structure level by level.
+
+     @param existingNode The current node in the base xml structure.
+     @param targetNode The node to insert.
+     @param level The xml file depth.
+  """
+
   # Copy attributes on the current level
   for tk in targetNode.attrib.keys():
     existingNode.set(tk, targetNode.get(tk))
@@ -51,8 +58,15 @@ def merge_xml_nodes(existingNode, targetNode, level):
       existingNode.insert(-1, target)
 
 
-# Recursively merge included files into the current structure
 def merge_included_xml_files(root, fname, includeCount, maxInclude=100):
+  """Recursively merge included files into the current structure.
+
+     @param root The root node of the base xml structure.
+     @param fname The name of the target xml file to merge.
+     @param includeCount The current recursion depth.
+     @param maxInclude The maximum number of xml files to include (default = 100)
+  """
+
   # Expand the input path
   pwd = os.getcwd()
   includePath, fname = os.path.split(os.path.abspath(os.path.expanduser(fname)))
@@ -88,9 +102,13 @@ def merge_included_xml_files(root, fname, includeCount, maxInclude=100):
   os.chdir(pwd)
 
 
-# Apply regexes that handle parameters, units, and symbolic math to
-# each xml attribute in the structure
 def apply_regex_to_node(node):
+  """Apply regexes that handle parameters, units, and symbolic math to each
+     xml attribute in the structure.
+
+     @param node The target node in the xml structure.
+  """
+
   for k in node.attrib.keys():
     value = node.get(k)
 
@@ -126,8 +144,12 @@ def apply_regex_to_node(node):
     apply_regex_to_node(subNode)
 
 
-# If the target name is not specified, generate a random name for the compiled xml
 def generate_random_name(prefix='', suffix='.xml'):
+  """If the target name is not specified, generate a random name for the compiled xml
+
+     @param prefix The file prefix (default = '').
+     @param suffix The file suffix (default = '.xml')
+  """
   from hashlib import md5
   from time import time
   from os import getpid
@@ -136,8 +158,16 @@ def generate_random_name(prefix='', suffix='.xml'):
   return '%s%s%s' % (prefix, md5(tmp.encode('utf-8')).hexdigest(), suffix)
 
 
-# Process an xml file
 def process(inputFile, outputFile='', schema='', verbose=0, keep_parameters=True, keep_includes=True):
+  """Process an xml file
+
+     @param inputFile Input file name.
+     @param outputFile Output file name (if not specified, then generate randomly).
+     @param schema Schema file name to validate the final xml (if not specified, then do not validate).
+     @param verbose Verbosity level.
+     @param keep_parameters If True, then keep parameters in the compiled file (default = True)
+     @param keep_includes If True, then keep includes in the compiled file (default = True)
+  """
   if verbose:
     print('\nReading input xml parameters and parsing symbolic math...')
 
@@ -206,8 +236,13 @@ def process(inputFile, outputFile='', schema='', verbose=0, keep_parameters=True
   return outputFile
 
 
-# Validate an xml file, and parse the warnings
 def validate_xml(fname, schema, verbose):
+  """Validate an xml file, and parse the warnings.
+
+     @param fname Target xml file name.
+     @param schema Schema file name.
+     @param verbose Verbosity level.
+  """
   if verbose:
     print('Validating the xml against the schema...')
   try: