Updated the doc strings

Author: VisLab

hed/errors/error_reporter.py

@@ -1,7 +1,28 @@
-""""
+"""
 Support functions for reporting validation errors.
 
 You can scope the formatted errors with calls to push_error_context and pop_error_context.
+The standard context keys are:
+
+    CUSTOM_TITLE = 'ec_title'
+    FILE_NAME = 'ec_filename'
+    SIDECAR_COLUMN_NAME = 'ec_sidecarColumnName'
+    SIDECAR_KEY_NAME = 'ec_sidecarKeyName'
+    ROW = 'ec_row'
+    COLUMN = 'ec_column'
+    LINE = "ec_line"
+    HED_STRING = 'ec_HedString'
+    SCHEMA_SECTION = 'ec_section'
+    SCHEMA_TAG = 'ec_schema_tag'
+    SCHEMA_ATTRIBUTE = 'ec_attribute'
+
+The standard error keys are:
+    'code' -- the standard HED error code
+    'message' -- the error message
+    'severity' -- 1 is error and 10 is warning.
+    'url' -- the web page in the HED Specification corresponding to the error (has explanation of how can occur).
+    'source_tag' -- the source tag that caused the error if application.
+
 """
 from __future__ import annotations
 from functools import wraps
@@ -490,6 +511,7 @@ def get_printable_issue_string(issues, title=None, severity=None, skip_filename=
         skip_filename (bool):  If True, don't add the filename context to the printable string.
         add_link (bool): Add a link at the end of message to the appropriate error if True
         show_details (bool):  If True, show details about the issues.
+
     Returns:
         str:   A string containing printable version of the issues or ''.
 
@@ -531,13 +553,25 @@ def get_printable_issue_string_html(issues, title=None, severity=None, skip_file
     return et.tostring(root_element, encoding='unicode')
 
 def iter_errors(issues):
-    """ An iterator over issues represented as flat dictionaries.
+    """ An iterator over issues that flattens the context into each issue dictionary.
+
+    This function takes a list of issues and transforms each one into a "flat" dictionary.
+    A flat dictionary contains all the information about a single error, including its context,
+    in a single, non-nested dictionary. This is useful for reporting or logging errors
+    in a simple, straightforward format.
+
+    For example, context information like file name or row number, which might be stored
+    in a nested structure or separate from the issue dictionary, is merged into the
+    top level of the dictionary.
+
+    It also adds a 'url' key with a link to the documentation for known HED error codes.
+    Any complex objects like HedTag or HedString are converted to their string representations.
 
     Parameters:
-        issues (list):  Issues to iterator over.
+        issues (list):  A list of issue dictionaries to iterate over.
 
     Yields:
-        dict: Represents the information in a single error.
+        dict: A flattened dictionary representing a single error.
     """
 
     for issue in issues:
@@ -563,7 +597,7 @@ def create_doc_link(error_code):
         error_code(str): A HED error code.
 
     Returns:
-        url(str or None): The URL if it's a valid code.
+        Union[str, 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"]:
@@ -684,7 +718,7 @@ def _get_error_prefix(single_issue):
         single_issue(dict): A single issue object.
 
     Returns:
-        error_prefix(str):  the prefix to use.
+        str:  the prefix to use.
     """
     severity = single_issue.get('severity', ErrorSeverity.ERROR)
     error_code = single_issue['code']

hed/models/base_input.py

@@ -36,7 +36,10 @@ def __init__(self, file, file_type=None, worksheet_name=None, has_column_names=T
             name (str or None): Optional field for how this file will report errors.
             allow_blank_names(bool): If True, column names can be blank
 
-        :raises HedFileError:
+        Raises:
+             HedFileError: For various issues.
+
+        Notes: Reasons for raising HedFileError include:
             - file is blank.
             - An invalid dataframe was passed with size 0.
             - An invalid extension was provided.
@@ -96,7 +99,8 @@ def dataframe_a(self) ->pd.DataFrame:
         """Return the assembled dataframe Probably a placeholder name.
 
         Returns:
-            pd.Dataframe: the assembled dataframe"""
+            pd.Dataframe: the assembled dataframe
+        """
         return self.assemble()
 
     @property
@@ -114,7 +118,7 @@ def series_filtered(self) -> Union[pd.Series, None]:
         """Return the assembled dataframe as a series, with rows that have the same onset combined.
 
         Returns:
-            Union[pd.Series, None] the assembled dataframe with columns merged, and the rows filtered together.
+            Union[pd.Series, None]: the assembled dataframe with columns merged, and the rows filtered together.
         """
         if self.onsets is not None:
             return filter_series_by_onset(self.series_a, self.onsets)
@@ -210,11 +214,9 @@ def to_excel(self, file):
         Parameters:
             file (str or file-like): Location to save this base input.
 
-        :raises ValueError:
-            - If empty file object was passed.
-
-        :raises OSError:
-            - Cannot open the indicated file.
+        Raises:
+            ValueError: If empty file object was passed.
+            OSError: If the file cannot be opened.
         """
         if not file:
             raise ValueError("Empty file name or object passed in to BaseInput.save.")
@@ -242,11 +244,12 @@ def to_csv(self, file=None):
 
         Parameters:
             file (str, file-like, or None): Location to save this file. If None, return as string.
+
         Returns:
             None or str:  None if file is given or the contents as a str if file is None.
 
-        :raises OSError:
-            - Cannot open the indicated file.
+        Raises:
+            OSError: If the file cannot be opened.
         """
         dataframe = self._dataframe
         csv_string_if_filename_none = dataframe.to_csv(file, sep='\t', index=False, header=self._has_column_names)
@@ -259,7 +262,7 @@ def columns(self):
             Empty if no column names.
 
         Returns:
-            columns(list): The column names.
+            list: The column names.
         """
         columns = []
         if self._dataframe is not None and self._has_column_names:
@@ -288,14 +291,10 @@ def set_cell(self, row_number, column_number, new_string_obj, tag_form="short_ta
         Notes:
              Any attribute of a HedTag that returns a string is a valid value of tag_form.
 
-        :raises ValueError:
-            - There is not a loaded dataframe.
-
-        :raises KeyError:
-            - The indicated row/column does not exist.
-
-        :raises AttributeError:
-            - The indicated tag_form is not an attribute of HedTag.
+        Raises:
+            ValueError: If there is not a loaded dataframe.
+            KeyError: If the indicated row/column does not exist.
+            AttributeError: If the indicated tag_form is not an attribute of HedTag.
         """
         if self._dataframe is None:
             raise ValueError("No data frame loaded")
@@ -315,8 +314,8 @@ def get_worksheet(self, worksheet_name=None) -> Union[openpyxl.workbook.Workbook
         Notes:
             If None, returns the first worksheet.
 
-        :raises KeyError:
-            - The specified worksheet name does not exist.
+        Raises:
+            KeyError: If the specified worksheet name does not exist.
         """
         if worksheet_name and self._loaded_workbook:
             # return self._loaded_workbook.get_sheet_by_name(worksheet_name)
@@ -380,6 +379,7 @@ def assemble(self, mapper=None, skip_curly_braces=False) ->pd.DataFrame:
         Parameters:
             mapper (ColumnMapper or None): Generally pass none here unless you want special behavior.
             skip_curly_braces (bool): If True, don't plug in curly brace values into columns.
+
         Returns:
             pd.Dataframe: The assembled dataframe.
         """

hed/models/column_mapper.py

@@ -151,13 +151,14 @@ def _set_sidecar(self, sidecar):
         Parameters:
             sidecar (Sidecar or None): The sidecar to use.
 
-        :raises ValueError:
-            - A sidecar was previously set.
+        Raises:
+             ValueError: A sidecar was previously set.
+
         """
         if self._sidecar:
             raise ValueError("Trying to set a second sidecar on a column mapper.")
         if not sidecar:
-            return None
+            return
 
         self._sidecar = sidecar
 

hed/models/def_expand_gather.py

@@ -51,9 +51,11 @@ def add_def(self, def_tag, def_expand_group):
     def resolve_definition(self):
         """ Try to resolve the definition based on the information available.
 
-        Returns: boolean - True if successfully resolved and False if it can't be resolved from information available.
+        Returns:
+            boolean: True if successfully resolved and False if it can't be resolved from information available.
 
-        Raises: ValueError - If the actual_contents conflict.
+        Raises:
+            ValueError: If the actual_contents conflict.
 
         If the definition has already been resolved, this rechecks based on the information.
 

hed/models/definition_dict.py

@@ -20,8 +20,8 @@ def __init__(self, def_dicts=None, hed_schema=None):
                 a single string whose definitions should be added.
             hed_schema (HedSchema or None): Required if passing strings or lists of strings, unused otherwise.
 
-        :raises TypeError:
-            - Bad type passed as def_dicts.
+        Raises:
+             TypeError: Bad type passed as def_dicts.
         """
 
         self.defs = {}
@@ -41,8 +41,8 @@ def add_definitions(self, def_dicts, hed_schema=None):
                 Note - str or list of strings will parse the strings using the hed_schema.
                 Note - You can mix and match types, eg [DefinitionDict, str, list of str] would be valid input.
 
-        :raises TypeError:
-            - Bad type passed as def_dicts.
+        Raises:
+             TypeError: Bad type passed as def_dicts.
         """
         if not isinstance(def_dicts, list):
             def_dicts = [def_dicts]
@@ -181,8 +181,9 @@ def _validate_placeholders(def_tag_name, group, def_takes_value, error_handler):
             def_takes_value (bool): True if the definition takes a value (should have #).
             error_handler (ErrorHandler or None): Error context used to identify where definitions are found.
 
-            Returns:
-               list:  List of issues encountered in checking for definitions. Each issue is a dictionary.
+        Returns:
+            list:  List of issues encountered in checking for definitions. Each issue is a dictionary.
+
         """
         new_issues = []
         placeholder_tags = []
@@ -232,8 +233,9 @@ def _find_group(definition_tag, group, error_handler):
             group (HedGroup): The entire definition group include the Definition tag.
             error_handler (ErrorHandler or None): Error context used to identify where definitions are found.
 
-            Returns:
-               list:  List of issues encountered in checking for definitions. Each issue is a dictionary.
+        Returns:
+            list:  List of issues encountered in checking for definitions. Each issue is a dictionary.
+
         """
         # initial validation
         groups = group.groups()
@@ -306,8 +308,7 @@ def _get_definition_contents(self, def_tag):
             def_tag (HedTag): Source HED tag that may be a Def or Def-expand tag.
 
         Returns:
-            def_contents: HedGroup
-            The contents to replace the previous def-tag with.
+            HedGroup: The contents to replace the previous def-tag with.
         """
         tag_label, _, placeholder = def_tag.extension.partition('/')
 
@@ -328,7 +329,7 @@ def get_as_strings(def_dict) -> dict[str, str]:
             def_dict (dict): A dict of definitions
 
         Returns:
-            dict[str,str]: definition name and contents
+            dict[str,str]: Definition name and contents
         """
         if isinstance(def_dict, DefinitionDict):
             def_dict = def_dict.defs

hed/models/definition_entry.py

@@ -37,10 +37,10 @@ def get_definition(self, replace_tag, placeholder_value=None, return_copy_of_tag
             return_copy_of_tag(bool): Set to True for validation.
 
         Returns:
-            HedGroup:     The contents of this definition(including the def tag itself).
+            Union[HedGroup, None]:     The contents of this definition(including the def tag itself).
 
-        :raises ValueError:
-            - Something internally went wrong with finding the placeholder tag.  This should not be possible.
+        Raises:
+            ValueError: Something internally went wrong with finding the placeholder tag. This should not be possible.
         """
         if self.takes_value == (not placeholder_value):
             return None

hed/models/df_util.py

@@ -112,7 +112,7 @@ def sort_dataframe_by_onsets(df):
         df(pd.Dataframe): Dataframe to sort.
 
     Returns:
-        The sorted dataframe, or the original dataframe if it didn't have an onset column.
+        pd.DataFrame: The sorted dataframe, or the original dataframe if it didn't have an onset column.
     """
     if "onset" in df.columns:
         # Create a copy and sort by onsets as floats(if needed), but continue to keep the string version.
@@ -177,7 +177,7 @@ def _handle_curly_braces_refs(df, refs, column_names):
         column_names(list): the columns we are interested in(should include all ref columns)
 
     Returns:
-        modified_df(pd.DataFrame): The modified dataframe with refs replaced
+        pd.DataFrame: The modified dataframe with refs replaced
     """
     # Filter out columns and refs that don't exist.
     refs_new = [ref for ref in refs if ref in column_names]
@@ -221,7 +221,7 @@ def split_delay_tags(series, hed_schema, onsets):
         onsets(pd.Series or None)
 
     Returns:
-        sorted_df(pd.Dataframe or None): If we had onsets, a dataframe with 3 columns
+        Union[pd.Dataframe, None]: If we had onsets, a dataframe with 3 columns
             "HED": The HED strings(still str)
             "onset": the updated onsets
             "original_index": the original source line.  Multiple lines can have the same original source line.
@@ -260,10 +260,11 @@ def filter_series_by_onset(series, onsets):
     """Return the series, with rows that have the same onset combined.
 
     Parameters:
-        series(pd.Series or pd.Dataframe): the series to filter.  If dataframe, it filters the "HED" column
-        onsets(pd.Series): the onset column to filter by
+        series(pd.Series or pd.Dataframe): The series to filter.  If dataframe, it filters the "HED" column.
+        onsets(pd.Series): The onset column to filter by.
+
     Returns:
-        Series or Dataframe: the series with rows filtered together.
+        Union[Series, Dataframe]: the series with rows filtered together.
     """
 
     indexed_dict = _indexed_dict_from_onsets(pd.to_numeric(onsets, errors='coerce'))