Merge pull request #858 from VisLab/develop

Clean up pass before release.

hed/errors/error_messages.py

@@ -1,11 +1,12 @@
 """
-This module contains the actual formatted error messages for each type.
+The actual formatted error messages for each type.
 
 Add new errors here, or any other file imported after error_reporter.py.
 """
 
 from hed.errors.error_reporter import hed_error, hed_tag_error
-from hed.errors.error_types import ValidationErrors, SidecarErrors, ErrorSeverity, DefinitionErrors, OnsetErrors, ColumnErrors
+from hed.errors.error_types import (ValidationErrors, SidecarErrors, ErrorSeverity, DefinitionErrors,
+                                    OnsetErrors, ColumnErrors)
 
 
 @hed_tag_error(ValidationErrors.UNITS_INVALID)
@@ -30,7 +31,6 @@ def val_error_hed_onset_with_no_column(tag):
     return f"Cannot have Temporal tags without an 'Onset' column.  Found tag: '{tag}'"
 
 
-
 @hed_tag_error(ValidationErrors.TAG_EXTENDED, has_sub_tag=True, default_severity=ErrorSeverity.WARNING)
 def val_error_tag_extended(tag, problem_tag):
     return f"Hed tag is extended. '{problem_tag}' in {tag}"
@@ -108,7 +108,8 @@ def val_error_invalid_extension(tag):
     return f'Invalid extension on tag - "{tag}"'
 
 
-@hed_tag_error(ValidationErrors.INVALID_PARENT_NODE, has_sub_tag=True, actual_code=ValidationErrors.TAG_EXTENSION_INVALID)
+@hed_tag_error(ValidationErrors.INVALID_PARENT_NODE, has_sub_tag=True,
+               actual_code=ValidationErrors.TAG_EXTENSION_INVALID)
 def val_error_invalid_parent(tag, problem_tag, expected_parent_tag):
     return f"In '{tag}', '{problem_tag}' appears as '{str(expected_parent_tag)}' and cannot be used as an extension."
 
@@ -141,15 +142,15 @@ def val_error_sidecar_with_column(column_names):
 
 
 @hed_error(ValidationErrors.DUPLICATE_COLUMN_IN_LIST)
-def val_error_duplicate_clumn(column_number, column_name, list_name):
+def val_error_duplicate_column(column_number, column_name, list_name):
     if column_name:
         return f"Found column '{column_name}' at index {column_number} twice in {list_name}."
     else:
-        return f"Found column number {column_number} twice in {list_name}.  This isn't a major concern, but does indicate a mistake."
+        return f"Found column number {column_number} twice in {list_name}.  This may indicate a mistake."
 
 
 @hed_error(ValidationErrors.DUPLICATE_COLUMN_BETWEEN_SOURCES)
-def val_error_duplicate_clumn(column_number, column_name, list_names):
+def val_error_duplicate_column(column_number, column_name, list_names):
     if column_name:
         return f"Found column '{column_name}' at index {column_number} in the following inputs: {list_names}. " \
                f"Each entry must be unique."
@@ -178,8 +179,6 @@ def val_error_sidecar_key_missing(invalid_key, category_keys):
     return f"Category key '{invalid_key}' does not exist in column.  Valid keys are: {category_keys}"
 
 
-
-
 @hed_tag_error(ValidationErrors.HED_DEF_EXPAND_INVALID, actual_code=ValidationErrors.DEF_EXPAND_INVALID)
 def val_error_bad_def_expand(tag, actual_def, found_def):
     return f"A data-recording's Def-expand tag does not match the given definition." + \
@@ -314,7 +313,6 @@ def def_error_wrong_group_tags(def_name, tag_list):
     return f"Too many tags found in definition for {def_name}.  Expected 1, found: {tag_list_strings}"
 
 
-
 @hed_error(DefinitionErrors.WRONG_NUMBER_PLACEHOLDER_TAGS, actual_code=ValidationErrors.DEFINITION_INVALID)
 def def_error_wrong_placeholder_count(def_name, expected_count, tag_list):
     tag_list_strings = [str(tag) for tag in tag_list]
@@ -417,5 +415,3 @@ def nested_column_ref(column_name, ref_column):
 @hed_error(ColumnErrors.MALFORMED_COLUMN_REF, actual_code=SidecarErrors.SIDECAR_BRACES_INVALID)
 def nested_column_ref(column_name, index, symbol):
     return f"Column {column_name} has a malformed column reference.  Improper symbol {symbol} found at index {index}."
-
-

hed/errors/error_reporter.py

@@ -1,5 +1,5 @@
 """
-This module is used to report errors found in the validation.
+Support functions for reporting validation errors.
 
 You can scope the formatted errors with calls to push_error_context and pop_error_context.
 """
@@ -12,10 +12,10 @@
 
 error_functions = {}
 
-# Controls if the default issue printing skips adding indentation for this context
+# Controls if the default issue printing skips adding indentation for this context.
 no_tab_context = {ErrorContext.HED_STRING, ErrorContext.SCHEMA_ATTRIBUTE}
 
-# Default sort ordering for issues list
+# Default sort ordering for issues list.
 default_sort_list = [
     ErrorContext.CUSTOM_TITLE,
     ErrorContext.FILE_NAME,
@@ -65,7 +65,7 @@ def wrapper(*args, severity=default_severity, **kwargs):
                 kwargs (**kwargs): Any keyword args to be passed down to error message function.
 
             Returns:
-                list: A list of dict with the errors.=
+                list: A list of dict with the errors.
             """
             base_message = func(*args, **kwargs)
             error_object = ErrorHandler._create_error_object(actual_code, base_message, severity)
@@ -97,9 +97,9 @@ def wrapper(tag, index_in_tag, index_in_tag_end, *args, severity=default_severit
                 """ Wrapper function for error handling tag errors with sub tags.
 
                 Parameters:
-                    tag (HedTag): The hed tag object with the problem,
-                    index_in_tag (int): The index into the tag with a problem(usually 0),
-                    index_in_tag_end (int): The last index into the tag with a problem - usually len(tag),
+                    tag (HedTag): The HED tag object with the problem.
+                    index_in_tag (int): The index into the tag with a problem(usually 0).
+                    index_in_tag_end (int): The last index into the tag with a problem - usually len(tag).
                     args (args): Any other non keyword args.
                     severity (ErrorSeverity): Used to include warnings as well as errors.
                     kwargs (**kwargs): Any keyword args to be passed down to error message function.
@@ -136,7 +136,7 @@ def wrapper(tag, *args, severity=default_severity, **kwargs):
                 """ Wrapper function for error handling tag errors.
 
                 Parameters:
-                    tag (HedTag or HedGroup): The hed tag object with the problem.
+                    tag (HedTag or HedGroup): The HED tag object with the problem.
                     args (non keyword args): Any other non keyword args.
                     severity (ErrorSeverity): For including warnings.
                     kwargs (keyword args): Any keyword args to be passed down to error message function.
@@ -286,7 +286,7 @@ def format_error_from_context(error_type, error_context, *args, actual_error=Non
             kwargs (kwargs): Keyword parameters to pass down to the error handling func.
 
         Returns:
-            list:  A list containing a single dictionary
+            list:  A list containing a single dictionary.
 
         Notes:
             - Generally the error_context is returned from _add_context_to_errors.
@@ -379,7 +379,7 @@ def val_error_unknown(*args, **kwargs):
         """ Default error handler if no error of this type was registered.
 
         Parameters:
-            args (args):     List of non-keyword parameters (varies).
+            args (args):  List of non-keyword parameters (varies).
             kwargs (kwargs): Keyword parameters (varies)
 
         Returns:
@@ -404,7 +404,7 @@ def filter_issues_by_severity(issues_list, severity):
 
 
 def sort_issues(issues, reverse=False):
-    """Sorts a list of issues by the error context values.
+    """Sort a list of issues by the error context values.
 
     Parameters:
         issues (list): A list of dictionaries representing the issues to be sorted.
@@ -427,7 +427,7 @@ def _get_keys(d):
 
 
 def check_for_any_errors(issues_list):
-    """Returns True if there are any errors with a severity of warning"""
+    """ Return True if there are any errors with a severity of warning. """
     for issue in issues_list:
         if issue['severity'] < ErrorSeverity.WARNING:
             return True
@@ -485,13 +485,13 @@ def get_printable_issue_string_html(issues, title=None, severity=None, skip_file
 
 
 def create_doc_link(error_code):
-    """If error code is a known code, return a documentation url for it
+    """If error code is a known code, return a documentation url for it.
 
     Parameters:
-        error_code(str): A HED error code
+        error_code(str): A HED error code.
 
     Returns:
-        url(str or None): The URL if it's a valid code
+        url(str or None): The URL if it's a valid code.
     """
     if error_code in known_error_codes["hed_validation_errors"] \
             or error_code in known_error_codes["schema_validation_errors"]:
@@ -501,7 +501,7 @@ def create_doc_link(error_code):
 
 
 def _build_error_context_dict(issues, skip_filename):
-    """Builds the context -> error dictionary for an entire list of issues
+    """Build the context -> error dictionary for an entire list of issues.
 
     Returns:
         dict: A nested dictionary structure with a "children" key at each level for unrelated children.
@@ -515,12 +515,12 @@ def _build_error_context_dict(issues, skip_filename):
 
 
 def _add_single_error_to_dict(items, root=None, issue_to_add=None):
-    """ Build a nested dictionary out of the context lists
+    """ Build a nested dictionary out of the context lists.
 
     Parameters:
         items (list): A list of error contexts
         root (dict, optional): An existing nested dictionary structure to update.
-        issue_to_add (dict, optional): The issue to add at this level of context
+        issue_to_add (dict, optional): The issue to add at this level of context.
 
     Returns:
         dict: A nested dictionary structure with a "children" key at each level for unrelated children.
@@ -587,13 +587,13 @@ def _get_context_from_issue(val_issue, skip_filename=True):
 
 
 def _get_error_prefix(single_issue):
-    """Returns the prefix for the error message based on severity and error code.
+    """Return the prefix for the error message based on severity and error code.
 
     Parameters:
-        single_issue(dict): A single issue object
+        single_issue(dict): A single issue object.
 
     Returns:
-        error_prefix(str):  the prefix to use
+        error_prefix(str):  the prefix to use.
     """
     severity = single_issue.get('severity', ErrorSeverity.ERROR)
     error_code = single_issue['code']
@@ -610,7 +610,7 @@ def _format_single_context_string(context_type, context, tab_count=0):
 
     Parameters:
         context_type (str): The context type of this entry.
-        context (str or HedString): The value of this context
+        context (str or HedString): The value of this context.
         tab_count (int): Number of tabs to name_prefix each line with.
 
     Returns:
@@ -647,7 +647,7 @@ def _create_error_tree(error_dict, parent_element=None, add_link=True):
                 error_prefix = _get_error_prefix(child)
                 single_issue_message = child["message"]
 
-                # Create a link for the error prefix if add_link is True
+                # Create a link for the error prefix if add_link is True.
                 if add_link:
                     link_url = create_doc_link(child['code'])
                     if link_url:
@@ -669,11 +669,11 @@ def _create_error_tree(error_dict, parent_element=None, add_link=True):
 
 
 def replace_tag_references(list_or_dict):
-    """Utility function to remove any references to tags, strings, etc from any type of nested list or dict
+    """ Utility function to remove any references to tags, strings, etc. from any type of nested list or dict.
 
        Use this if you want to save out issues to a file.
 
-       If you'd prefer a copy returned, use replace_tag_references(list_or_dict.copy())
+       If you'd prefer a copy returned, use replace_tag_references(list_or_dict.copy()).
 
     Parameters:
        list_or_dict(list or dict): An arbitrarily nested list/dict structure

hed/errors/error_types.py

@@ -1,11 +1,13 @@
+""" Error codes used in different error messages. """
+
 
 class ErrorSeverity:
     ERROR = 1
     WARNING = 10
 
 
 class ErrorContext:
-    """Indicates the context this error took place in, each error potentially having multiple contexts"""
+    """Context this error took place in, each error potentially having multiple contexts. """
     # Use this one to display any passed in message without modification
     CUSTOM_TITLE = 'ec_title'
     FILE_NAME = 'ec_filename'
@@ -21,7 +23,7 @@ class ErrorContext:
 
 
 class ValidationErrors:
-    # General validation errors
+    # General validation errors.
     CHARACTER_INVALID = 'CHARACTER_INVALID'
     COMMA_MISSING = 'COMMA_MISSING'
     DEF_EXPAND_INVALID = "DEF_EXPAND_INVALID"
@@ -75,9 +77,7 @@ class ValidationErrors:
     HED_GROUP_EMPTY = 'HED_GROUP_EMPTY'
     # end internal codes
 
-
     # Still being worked on below this line
-
     HED_MISSING_REQUIRED_COLUMN = "HED_MISSING_REQUIRED_COLUMN"
     HED_UNKNOWN_COLUMN = "HED_UNKNOWN_COLUMN"
     SIDECAR_AND_OTHER_COLUMNS = "SIDECAR_AND_OTHER_COLUMNS"
@@ -168,6 +168,7 @@ class OnsetErrors:
     ONSET_SAME_DEFS_ONE_ROW = "ONSET_SAME_DEFS_ONE_ROW"
     HED_ONSET_WITH_NO_COLUMN = 'HED_ONSET_WITH_NO_COLUMN'
 
+
 class ColumnErrors:
     INVALID_COLUMN_REF = "INVALID_COLUMN_REF"
     SELF_COLUMN_REF = "SELF_COLUMN_REF"

hed/errors/exceptions.py

@@ -1,7 +1,8 @@
-from hed.errors.error_types import ErrorContext
+""" HED exceptions and exception codes. """
 
 
 class HedExceptions:
+    """ HED exception codes. """
     GENERIC_ERROR = 'GENERIC_ERROR'
     # A list of all exceptions that can be generated by the hedtools.
     URL_ERROR = "URL_ERROR"
@@ -29,7 +30,6 @@ class HedExceptions:
     IN_LIBRARY_IN_UNMERGED = "SCHEMA_LIBRARY_INVALID"
     INVALID_LIBRARY_PREFIX = "SCHEMA_LIBRARY_INVALID"
 
-
     SCHEMA_VERSION_INVALID = 'SCHEMA_VERSION_INVALID'
     SCHEMA_SECTION_MISSING = 'SCHEMA_SECTION_MISSING'
 

hed/errors/known_error_codes.py

@@ -1,3 +1,5 @@
+""" Known error codes as reported in the HED specification. """
+
 known_error_codes = {
     "hed_validation_errors": [
         "CHARACTER_INVALID",
@@ -43,4 +45,4 @@
         "WIKI_SEPARATOR_INVALID",
         "XML_SYNTAX_INVALID"
     ]
-}
+}