Error handling

Error handling and reporting classes for HED validation and processing.

Error types and constants

HedExceptions

class HedExceptions

Bases: object

HED exception codes.

BAD_COLUMN_NAMES = 'BAD_COLUMN_NAMES'

BAD_HED_LIBRARY_NAME = 'SCHEMA_LIBRARY_INVALID'

BAD_PARAMETERS = 'badParameters'

BAD_WITH_STANDARD = 'SCHEMA_LIBRARY_INVALID'

BAD_WITH_STANDARD_MULTIPLE_VALUES = 'SCHEMA_LOAD_FAILED'

CANNOT_PARSE_JSON = 'cannotParseJson'

CANNOT_PARSE_RDF = 'CANNOT_PARSE_RDF'

CANNOT_PARSE_XML = 'cannotParseXML'

FILE_NOT_FOUND = 'fileNotFound'

GENERIC_ERROR = 'GENERIC_ERROR'

HED_SCHEMA_NODE_NAME_INVALID = 'HED_SCHEMA_NODE_NAME_INVALID'

INVALID_DATAFRAME = 'INVALID_DATAFRAME'

INVALID_EXTENSION = 'invalidExtension'

INVALID_FILE_FORMAT = 'INVALID_FILE_FORMAT'

INVALID_HED_FORMAT = 'INVALID_HED_FORMAT'

INVALID_LIBRARY_PREFIX = 'SCHEMA_LIBRARY_INVALID'

IN_LIBRARY_IN_UNMERGED = 'SCHEMA_LIBRARY_INVALID'

ROOTED_TAG_DOES_NOT_EXIST = 'SCHEMA_LIBRARY_INVALID'

ROOTED_TAG_HAS_PARENT = 'SCHEMA_LIBRARY_INVALID'

ROOTED_TAG_INVALID = 'SCHEMA_LIBRARY_INVALID'

SCHEMA_DUPLICATE_LIBRARY = 'SCHEMA_LIBRARY_INVALID'

SCHEMA_DUPLICATE_NAMES = 'SCHEMA_DUPLICATE_NAMES'

SCHEMA_DUPLICATE_PREFIX = 'SCHEMA_LOAD_FAILED'

SCHEMA_HEADER_INVALID = 'SCHEMA_HEADER_INVALID'

SCHEMA_HEADER_MISSING = 'SCHEMA_HEADER_INVALID'

SCHEMA_INVALID = 'SCHEMA_INVALID'

SCHEMA_LIBRARY_INVALID = 'SCHEMA_LIBRARY_INVALID'

SCHEMA_LOAD_FAILED = 'SCHEMA_LOAD_FAILED'

SCHEMA_SECTION_MISSING = 'SCHEMA_SECTION_MISSING'

SCHEMA_TAG_TSV_BAD_PARENT = 'SCHEMA_TAG_TSV_BAD_PARENT'

SCHEMA_UNKNOWN_HEADER_ATTRIBUTE = 'SCHEMA_HEADER_INVALID'

SCHEMA_VERSION_INVALID = 'SCHEMA_VERSION_INVALID'

URL_ERROR = 'URL_ERROR'

WIKI_DELIMITERS_INVALID = 'WIKI_DELIMITERS_INVALID'

WIKI_LINE_INVALID = 'WIKI_LINE_INVALID'

WIKI_LINE_START_INVALID = 'WIKI_LINE_START_INVALID'

WIKI_SEPARATOR_INVALID = 'invalidSectionSeparator'

HedFileError

class HedFileError(code, message, filename, issues=None)

Bases: Exception

Exception raised when a file cannot be parsed due to being malformed, file IO, etc.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Error reporting

ErrorHandler

class ErrorHandler(check_for_warnings=True)

Bases: object

Class to hold error context and having general error functions.

add_context_and_filter(issues)

Filter out warnings if requested, while adding context to issues.

issues(list):

list: A list containing a single dictionary representing a single error.

static aggregate_code_counts(file_code_dict) → dict

Aggregate the counts of codes across multiple files.

Parameters:

file_code_dict (dict) – A dictionary where keys are filenames and values are dictionaries of code counts.

Returns:

A dictionary with the aggregated counts of codes across all files.

Return type:

dict

static filter_issues_by_count(issues, count, by_file=False) → tuple[list[dict], dict[str, int]]

Filter the issues list to only include the first count issues of each code.

Parameters:

issues (list): A list of dictionaries containing the full issue list. count (int): The number of issues to keep for each code. by_file (bool): If True, group by file name.

Returns:

A tuple containing:

• A list of dictionaries representing the filtered issue list.

• A dictionary with the codes as keys and the number of occurrences as values.

Return type:

tuple[list[dict], dict[str, int]]

static filter_issues_by_severity(issues_list: list[dict], severity: int) → list[dict]

Gather all issues matching or below a given severity.

Parameters:

• issues_list (list[dict]) – A list of dictionaries containing the full issue list.

• severity (int) – The level of issues to keep.

Returns:

A list of dictionaries containing the issue list after filtering by severity.

Return type:

list[dict]

static format_error(error_type: str, *args, actual_error=None, **kwargs) → list[dict]

Format an error based on the parameters, which vary based on what type of error this is.

Parameters:

• error_type (str) – The type of error for this. Registered with @hed_error or @hed_tag_error.

• args (args) – Any remaining non-keyword args after those required by the error type.

• actual_error (str or None) – Code to actually add to report out.

• kwargs (kwargs) – The other keyword args to pass down to the error handling func.

Returns:

A list containing a single dictionary representing a single error.

Return type:

list[dict]

Notes

The actual error is useful for errors that are shared like invalid character.

static format_error_from_context(error_type: str, error_context: list, *args, actual_error: str | None, **kwargs) → list[dict]

Format an error based on the error type.

Parameters:

• error_type (str) – The type of error. Registered with @hed_error or @hed_tag_error.

• error_context (list) – Contains the error context to use for this error.

• args (args) – Any remaining non-keyword args.

• actual_error (str or None) – Error code to actually add to report out.

• kwargs (kwargs) – Keyword parameters to pass down to the error handling func.

Returns:

A list containing a single dictionary.

Return type:

list[dict]

Notes

• Generally the error_context is returned from _add_context_to_error.

• The actual_error is useful for errors that are shared like invalid character.

• This can’t filter out warnings like the other ones.

format_error_with_context(*args, **kwargs)

static get_code_counts(issues: list[dict]) → dict[str, int]

Count the occurrences of each error code in the issues list.

Parameters:

issues (list[dict]) – A list of dictionaries containing the issues.

Returns:

A dictionary with error codes as keys and their occurrence counts as values.

Return type:

dict[str, int]

pop_error_context()

Remove the last scope from the error context.

Notes

Modifies the error context of this reporter.

push_error_context(context_type, context)

Push a new error context to narrow down error scope.

Parameters:

• context_type (str) – A value from ErrorContext representing the type of scope.

• context (str, int, or HedString) – The main value for the context_type.

Notes

The context depends on the context_type. For ErrorContext.FILE_NAME this would be the actual filename.

reset_error_context()

Reset all error context information to defaults.

Notes

This function is mainly for testing and should not be needed with proper usage.

val_error_unknown(**kwargs) → str

Default error handler if no error of this type was registered.

Parameters:

• args (args) – List of non-keyword parameters (varies).

• kwargs (kwargs) – Keyword parameters (varies)

Returns:

The error message.

Return type:

str

Error functions

get_printable_issue_string(issues, title=None, severity=None, skip_filename=True, add_link=False, show_details=False) → str

Return a string with issues list flatted into single string, one per line.

Parameters:

• issues (list) – Issues to print.

• title (str) – Optional title that will always show up first if present(even if there are no validation issues).

• severity (int) – Return only warnings >= severity.

• 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:

A string containing printable version of the issues or ‘’.

Return type:

str

sort_issues(issues, reverse=False) → list[dict]

Sort a list of issues by the error context values.

Parameters:

• issues (list) – A list of dictionaries representing the issues to be sorted.

• reverse (bool, optional) – If True, sorts the list in descending order. Default is False.

Returns:

The sorted list of issues.

Return type:

list[dict]

replace_tag_references(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()).

Parameters:

list_or_dict (list or dict) – An arbitrarily nested list/dict structure

Error types

ValidationErrors

class ValidationErrors

Bases: object

CHARACTER_INVALID = 'CHARACTER_INVALID'

COMMA_MISSING = 'COMMA_MISSING'

CURLY_BRACE_UNSUPPORTED_HERE = 'CURLY_BRACE_UNSUPPORTED_HERE'

DEFINITION_INVALID = 'DEFINITION_INVALID'

DEF_EXPAND_INVALID = 'DEF_EXPAND_INVALID'

DEF_INVALID = 'DEF_INVALID'

DUPLICATE_COLUMN_BETWEEN_SOURCES = 'DUPLICATE_COLUMN_BETWEEN_SOURCES'

DUPLICATE_COLUMN_IN_LIST = 'DUPLICATE_COLUMN_IN_LIST'

ELEMENT_DEPRECATED = 'ELEMENT_DEPRECATED'

HED_BLANK_COLUMN = 'HED_BLANK_COLUMN'

HED_COLUMN_MISSING = 'HED_COLUMN_MISSING'

HED_DEF_EXPAND_INVALID = 'HED_DEF_EXPAND_INVALID'

HED_DEF_EXPAND_UNMATCHED = 'HED_DEF_EXPAND_UNMATCHED'

HED_DEF_EXPAND_VALUE_EXTRA = 'HED_DEF_EXPAND_VALUE_EXTRA'

HED_DEF_EXPAND_VALUE_MISSING = 'HED_DEF_EXPAND_VALUE_MISSING'

HED_DEF_UNMATCHED = 'HED_DEF_UNMATCHED'

HED_DEF_VALUE_EXTRA = 'HED_DEF_VALUE_EXTRA'

HED_DEF_VALUE_MISSING = 'HED_DEF_VALUE_MISSING'

HED_GROUP_EMPTY = 'HED_GROUP_EMPTY'

HED_LIBRARY_UNMATCHED = 'HED_LIBRARY_UNMATCHED'

HED_MISSING_REQUIRED_COLUMN = 'HED_MISSING_REQUIRED_COLUMN'

HED_MULTIPLE_TOP_TAGS = 'HED_MULTIPLE_TOP_TAGS'

HED_PLACEHOLDER_OUT_OF_CONTEXT = 'HED_PLACEHOLDER_OUT_OF_CONTEXT'

HED_RESERVED_TAG_GROUP_ERROR = 'HED_RESERVED_TAG_GROUP_ERROR'

HED_RESERVED_TAG_REPEATED = 'HED_RESERVED_TAG_REPEATED'

HED_TAGS_NOT_ALLOWED = 'HED_TAGS_NOT_ALLOWED'

HED_TAG_GROUP_TAG = 'HED_TAG_GROUP_TAG'

HED_TAG_REPEATED = 'HED_TAG_REPEATED'

HED_TAG_REPEATED_GROUP = 'HED_TAG_REPEATED_GROUP'

HED_TOP_LEVEL_TAG = 'HED_TOP_LEVEL_TAG'

HED_UNKNOWN_COLUMN = 'HED_UNKNOWN_COLUMN'

INVALID_PARENT_NODE = 'invalidParent'

INVALID_TAG_CHARACTER = 'invalidTagCharacter'

INVALID_VALUE_CLASS_CHARACTER = 'INVALID_VALUE_CLASS_CHARACTER'

INVALID_VALUE_CLASS_VALUE = 'INVALID_VALUE_CLASS_VALUE'

NODE_NAME_EMPTY = 'NODE_NAME_EMPTY'

NO_VALID_TAG_FOUND = 'invalidTag'

ONSETS_UNORDERED = 'ONSETS_UNORDERED'

PARENTHESES_MISMATCH = 'PARENTHESES_MISMATCH'

PLACEHOLDER_INVALID = 'PLACEHOLDER_INVALID'

REQUIRED_TAG_MISSING = 'REQUIRED_TAG_MISSING'

SIDECAR_AND_OTHER_COLUMNS = 'SIDECAR_AND_OTHER_COLUMNS'

SIDECAR_INVALID = 'SIDECAR_INVALID'

SIDECAR_KEY_MISSING = 'SIDECAR_KEY_MISSING'

STYLE_WARNING = 'STYLE_WARNING'

TAG_EMPTY = 'TAG_EMPTY'

TAG_EXPRESSION_REPEATED = 'TAG_EXPRESSION_REPEATED'

TAG_EXTENDED = 'TAG_EXTENDED'

TAG_EXTENSION_INVALID = 'TAG_EXTENSION_INVALID'

TAG_GROUP_ERROR = 'TAG_GROUP_ERROR'

TAG_INVALID = 'TAG_INVALID'

TAG_NAMESPACE_PREFIX_INVALID = 'TAG_NAMESPACE_PREFIX_INVALID'

TAG_NOT_UNIQUE = 'TAG_NOT_UNIQUE'

TAG_REQUIRES_CHILD = 'TAG_REQUIRES_CHILD'

TEMPORAL_TAG_ERROR = 'TEMPORAL_TAG_ERROR'

TILDES_UNSUPPORTED = 'TILDES_UNSUPPORTED'

TSV_COLUMN_MISSING = 'TSV_COLUMN_MISSING'

UNITS_INVALID = 'UNITS_INVALID'

VALUE_INVALID = 'VALUE_INVALID'

VERSION_DEPRECATED = 'VERSION_DEPRECATED'

SchemaErrors

class SchemaErrors

Bases: object

SCHEMA_DUPLICATE_FROM_LIBRARY = 'SCHEMA_LIBRARY_INVALID'

SCHEMA_DUPLICATE_NODE = 'SCHEMA_DUPLICATE_NODE'

SCHEMA_INVALID_CHILD = 'SCHEMA_INVALID_CHILD'

SCHEMA_INVALID_SIBLING = 'SCHEMA_INVALID_SIBLING'

SidecarErrors

class SidecarErrors

Bases: object

BLANK_HED_STRING = 'blankValueString'

INVALID_POUND_SIGNS_CATEGORY = 'tooManyPoundSigns'

INVALID_POUND_SIGNS_VALUE = 'invalidNumberPoundSigns'

SIDECAR_BRACES_INVALID = 'SIDECAR_BRACES_INVALID'

SIDECAR_HED_USED = 'SIDECAR_HED_USED'

SIDECAR_NA_USED = 'SIDECAR_NA_USED'

UNKNOWN_COLUMN_TYPE = 'sidecarUnknownColumn'

WRONG_HED_DATA_TYPE = 'wrongHedDataType'

ErrorContext

class ErrorContext

Bases: object

Context this error took place in, each error potentially having multiple contexts.

COLUMN = 'ec_column'

CUSTOM_TITLE = 'ec_title'

FILE_NAME = 'ec_filename'

HED_STRING = 'ec_HedString'

LINE = 'ec_line'

ROW = 'ec_row'

SCHEMA_ATTRIBUTE = 'ec_attribute'

SCHEMA_SECTION = 'ec_section'

SCHEMA_TAG = 'ec_schema_tag'

SIDECAR_COLUMN_NAME = 'ec_sidecarColumnName'

SIDECAR_KEY_NAME = 'ec_sidecarKeyName'

TABLE_NAME = 'ec_table_name'

ErrorSeverity

class ErrorSeverity

Bases: object

Severity codes for errors

ERROR = 1

WARNING = 10