Add python tools documentation to sphinx (#1991)

* Adding python autodocs to sphinx, fixing docstring errors

* Adding type hints for python tools

* Modernizing python setup configurations

* Adding hdf5_wrapper unit tests

Author: cssherman

geosx_mesh_tools_package/geosx_mesh_tools/abaqus_converter.py

@@ -1,20 +1,24 @@
-import meshio
-from meshio._mesh import CellBlock
+import meshio    # type: ignore[import]
+from meshio._mesh import CellBlock    # type: ignore[import]
 import numpy as np
-import argparse
 import logging
-import sys
 
 
-def convert_abaqus_to_gmsh(input_mesh, output_mesh, logger=None):
+def convert_abaqus_to_gmsh(input_mesh: str, output_mesh: str, logger: logging.Logger = None) -> int:
     """
-    @brief Convert an abaqus mesh to gmsh 2 format, preserving nodeset information.
-    @details If the code encounters any issues with region/element indices,
-             the conversion will attempt to continue, with errors
-             indicated by -1 values in the output file.
-    @param input_mesh path of the input abaqus file
-    @param output_mesh path of the output gmsh file
-    @param logger an instance of logging.Logger
+    Convert an abaqus mesh to gmsh 2 format, preserving nodeset information.
+
+    If the code encounters any issues with region/element indices,
+    the conversion will attempt to continue, with errors
+    indicated by -1 values in the output file.
+
+    Args:
+        input_mesh (str): path of the input abaqus file
+        output_mesh (str): path of the output gmsh file
+        logger (logging.Logger): an instance of logging.Logger
+
+    Returns:
+        int: Number of potential warnings encountered during conversion
     """
     # Initialize the logger if it is empty
     if not logger:
@@ -123,15 +127,20 @@ def convert_abaqus_to_gmsh(input_mesh, output_mesh, logger=None):
     return (n_warnings > 0)
 
 
-def convert_abaqus_to_vtu(input_mesh, output_mesh, logger=None):
+def convert_abaqus_to_vtu(input_mesh: str, output_mesh: str, logger: logging.Logger = None) -> int:
     """
-    @brief Convert an abaqus mesh to vtu format, preserving nodeset information.
-    @details If the code encounters any issues with region/element indices,
-             the conversion will attempt to continue, with errors
-             indicated by -1 values in the output file.
-    @param input_mesh path of the input abaqus file
-    @param output_mesh path of the output vtu file
-    @param logger an instance of logging.Logger
+    Convert an abaqus mesh to vtu format, preserving nodeset information.
+    
+    If the code encounters any issues with region/element indices, the conversion will 
+    attempt to continue, with errors indicated by -1 values in the output file.
+    
+    Args:
+        input_mesh (str): path of the input abaqus file
+        output_mesh (str): path of the output vtu file
+        logger (logging.Logger): a logger instance
+
+    Returns:
+        int: Number of potential warnings encountered during conversion
     """
     # Initialize the logger if it is empty
     if not logger:
@@ -159,33 +168,3 @@ def convert_abaqus_to_vtu(input_mesh, output_mesh, logger=None):
     logger.info('Done!')
 
     return (n_warnings > 0)
-
-
-def main():
-    """
-    @brief Entry point for the abaqus convertor console script
-    @arg input_mesh Input abaqus file name
-    @arg output_mesh Output gmsh or vtu file name
-    """
-
-    # Parse the user arguments
-    parser = argparse.ArgumentParser()
-    parser.add_argument('input', type=str, help='Input abaqus mesh file name')
-    parser.add_argument('output', type=str, help='Output gmsh mesh file name')
-    parser.add_argument('-v', '--verbose', help='Increase verbosity level', action="store_true")
-    args = parser.parse_args()
-
-    # Set up a logger
-    logging.basicConfig(level=logging.WARNING)
-    logger = logging.getLogger(__name__)
-    if args.verbose:
-        logger.setLevel(logging.INFO)
-
-    # Call the converter
-    err = 0
-    if ('.msh' in args.output):
-        err = convert_abaqus_to_gmsh(args.input, args.output, logger)
-    else:
-        err = convert_abaqus_to_vtu(args.input, args.output, logger)
-    if err:
-        sys.exit('Warnings detected: check the output file for potential errors!')

geosx_mesh_tools_package/geosx_mesh_tools/main.py

@@ -0,0 +1,51 @@
+import argparse
+import logging
+import sys
+
+
+def build_abaqus_converter_input_parser() -> argparse.ArgumentParser:
+    """Build the input argument parser
+
+    Returns:
+        argparse.ArgumentParser: a parser instance
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument('input', type=str, help='Input abaqus mesh file name')
+    parser.add_argument('output', type=str, help='Output gmsh/vtu mesh file name')
+    parser.add_argument('-v', '--verbose', help='Increase verbosity level', action="store_true")
+    return parser
+
+
+def main() -> None:
+    """
+    Entry point for the abaqus convertor console script
+
+    Args:
+        input (str): Input abaqus mesh file name
+        output (str): Output mesh file name
+        -v/--verbose (flag): Increase verbosity level
+    """
+    from geosx_mesh_tools import abaqus_converter
+
+    # Parse the user arguments
+    parser = build_abaqus_converter_input_parser()
+    args = parser.parse_args()
+
+    # Set up a logger
+    logging.basicConfig(level=logging.WARNING)
+    logger = logging.getLogger(__name__)
+    if args.verbose:
+        logger.setLevel(logging.INFO)
+
+    # Call the converter
+    err = 0
+    if ('.msh' in args.output):
+        err = abaqus_converter.convert_abaqus_to_gmsh(args.input, args.output, logger)
+    else:
+        err = abaqus_converter.convert_abaqus_to_vtu(args.input, args.output, logger)
+    if err:
+        sys.exit('Warnings detected: check the output file for potential errors!')
+
+
+if __name__ == '__main__':
+    main()

geosx_mesh_tools_package/geosx_mesh_tools/py.typed

@@ -0,0 +1,8 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true

geosx_mesh_tools_package/pyproject.toml

@@ -0,0 +1,22 @@
+[metadata]
+name = geosx_mesh_tools
+version = 0.2.0
+description = Tools for managing meshes in GEOSX
+author = Christopher Sherman
+author_email = [email protected]
+license = LGPL-2.1
+
+[options]
+packages =
+    geosx_mesh_tools
+install_requires =
+    meshio>=5.3.2
+    numpy
+python_requires = >=3.6
+
+[options.package_data]
+geosx_mesh_tools = py.typed
+
+[options.entry_points]
+console_scripts =
+    convert_abaqus = geosx_mesh_tools.main:main

geosx_mesh_tools_package/setup.cfg

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

geosx_mesh_tools_package/setup.py

@@ -1,27 +1,34 @@
-from lxml import etree as ElementTree
+from lxml import etree as ElementTree    # type: ignore[import]
 import os
 from pathlib import Path
-import argparse
+from typing import Any, Iterable, Dict
+from geosx_xml_tools import command_line_parsers
 
+record_type = Dict[str, Dict[str, Any]]
 
-def parse_schema_element(root,
-                         node,
-                         xsd='{http://www.w3.org/2001/XMLSchema}',
-                         recursive_types=['PeriodicEvent', 'SoloEvent', 'HaltEvent'],
-                         folders=['src', 'examples']):
+
+def parse_schema_element(root: ElementTree.Element,
+                         node: ElementTree.Element,
+                         xsd: str = '{http://www.w3.org/2001/XMLSchema}',
+                         recursive_types: Iterable[str] = ['PeriodicEvent', 'SoloEvent', 'HaltEvent'],
+                         folders: Iterable[str] = ['src', 'examples']) -> record_type:
     """Parse the xml schema at the current level
 
-    @arg root the root schema node
-    @arg node current schema node
-    @arg xsd the file namespace
-    @arg recursive_types node tags that allow recursive nesting
-    @arg folders folders to sort xml attribute usage into
+    Args:
+        root (lxml.etree.Element): the root schema node
+        node (lxml.etree.Element): current schema node
+        xsd (str): the file namespace
+        recursive_types (list): node tags that allow recursive nesting
+        folders (list): folders to sort xml attribute usage into
+
+    Returns:
+        dict: Dictionary of attributes and children for the current node
     """
 
     element_type = node.get('type')
     element_name = node.get('name')
     element_def = root.find("%scomplexType[@name='%s']" % (xsd, element_type))
-    local_types = {'attributes': {}, 'children': {}}
+    local_types: record_type = {'attributes': {}, 'children': {}}
 
     # Parse attributes
     for attribute in element_def.findall('%sattribute' % (xsd)):
@@ -41,23 +48,28 @@ def parse_schema_element(root,
     return local_types
 
 
-def parse_schema(fname):
+def parse_schema(fname: str) -> record_type:
     """Parse the schema file into the xml attribute usage dict
 
-    @arg fname schema name
+    Args:
+        fname (str): schema name
+
+    Returns:
+        dict: Dictionary of attributes and children for the entire schema
     """
     xml_tree = ElementTree.parse(fname)
     xml_root = xml_tree.getroot()
     problem_node = xml_root.find("{http://www.w3.org/2001/XMLSchema}element")
     return {'Problem': parse_schema_element(xml_root, problem_node)}
 
 
-def collect_xml_attributes_level(local_types, node, folder):
+def collect_xml_attributes_level(local_types: record_type, node: ElementTree.Element, folder: str) -> None:
     """Collect xml attribute usage at the current level
 
-    @arg local_types dict containing attribute usage
-    @arg node current xml node
-    @arg folder the source folder for the current file
+    Args:
+        local_types (dict): dictionary containing attribute usage
+        node (lxml.etree.Element): current xml node
+        folder (str): the source folder for the current file
     """
     for ka in node.attrib.keys():
         local_types['attributes'][ka][folder].append(node.get(ka))
@@ -67,12 +79,13 @@ def collect_xml_attributes_level(local_types, node, folder):
             collect_xml_attributes_level(local_types['children'][child.tag], child, folder)
 
 
-def collect_xml_attributes(xml_types, fname, folder):
+def collect_xml_attributes(xml_types: record_type, fname: str, folder: str) -> None:
     """Collect xml attribute usage in a file
 
-    @arg xml_types dict containing attribute usage
-    @arg fname name of the target file
-    @arg folder the source folder for the current file
+    Args:
+        xml_types (dict): dictionary containing attribute usage
+        fname (str): name of the target file
+        folder (str): the source folder for the current file
     """
     parser = ElementTree.XMLParser(remove_comments=True, remove_blank_text=True)
     xml_tree = ElementTree.parse(fname, parser=parser)
@@ -81,11 +94,14 @@ def collect_xml_attributes(xml_types, fname, folder):
     collect_xml_attributes_level(xml_types['Problem'], xml_root, folder)
 
 
-def write_attribute_usage_xml_level(local_types, node, folders=['src', 'examples']):
+def write_attribute_usage_xml_level(local_types: record_type,
+                                    node: ElementTree.Element,
+                                    folders: Iterable[str] = ['src', 'examples']) -> None:
     """Write xml attribute usage file at a given level
 
-    @arg local_types dict containing attribute usage at the current level
-    @arg node current xml node
+    Args:
+        local_types (dict): dict containing attribute usage at the current level
+        node (lxml.etree.Element): current xml node
     """
 
     # Write attributes
@@ -112,11 +128,12 @@ def write_attribute_usage_xml_level(local_types, node, folders=['src', 'examples
         write_attribute_usage_xml_level(local_types['children'][ka], child)
 
 
-def write_attribute_usage_xml(xml_types, fname):
+def write_attribute_usage_xml(xml_types: record_type, fname: str) -> None:
     """Write xml attribute usage file
 
-    @arg xml_types dict containing attribute usage by xml type
-    @arg fname output file name
+    Args:
+        xml_types (dict): dictionary containing attribute usage by xml type
+        fname (str): output file name
     """
     xml_root = ElementTree.Element('Problem')
     xml_tree = ElementTree.ElementTree(xml_root)
@@ -125,11 +142,12 @@ def write_attribute_usage_xml(xml_types, fname):
     xml_tree.write(fname, pretty_print=True)
 
 
-def process_xml_files(geosx_root, output_name):
+def process_xml_files(geosx_root: str, output_name: str) -> None:
     """Test for xml attribute usage
 
-    @arg geosx_root GEOSX root directory
-    @arg output_name output file name
+    Args:
+        geosx_root (str): GEOSX root directory
+        output_name (str): output file name
     """
 
     # Parse the schema
@@ -149,17 +167,16 @@ def process_xml_files(geosx_root, output_name):
     write_attribute_usage_xml(xml_types, output_name)
 
 
-def main():
+def main() -> None:
     """Entry point for the xml attribute usage test script
 
-    @arg -r/--root GEOSX root directory
-    @arg -o/--output output file name
+    Args:
+        -r/--root (str): GEOSX root directory
+        -o/--output (str): output file name
     """
 
     # Parse the user arguments
-    parser = argparse.ArgumentParser()
-    parser.add_argument('-r', '--root', type=str, help='GEOSX root', default='')
-    parser.add_argument('-o', '--output', type=str, help='Output file name', default='attribute_test.xml')
+    parser = command_line_parsers.build_attribute_coverage_input_parser()
     args = parser.parse_args()
 
     # Parse the xml files