Evaluate the public interface pre release of v1.0.0

[VisLab]

We are getting ready to make the v1.0.0 release which will be a breaking change. @claude do a careful evaluation of the init files and the public interface. Find flaws and suggest improvements.

[github-actions]

Claude finished @VisLab's task in 3m 31s —— View job

---

Public Interface Evaluation for v1.0.0

Tasks:

• Gather context and understand request
• Read main hed/__init__.py
• Read all sub-package __init__.py files
• Analyze public API surface for consistency and flaws
• Post detailed findings and recommendations

---

Findings and Recommendations

I evaluated all __init__.py files across the package, the exported symbols, and key source files. Below are the issues found, grouped by category.

---

1. Inconsistent Exports Between hed/__init__.py and hed/errors/__init__.py

HedQueryError missing from hed.errors (errors/__init__.py:20):

• hed/__init__.py exports HedQueryError via from hed.errors.exceptions import ..., HedQueryError
• But hed/errors/__init__.py does NOT export HedQueryError
• from hed.errors import HedQueryError currently raises ImportError
• Fix: add HedQueryError to hed/errors/__init__.py

SchemaAttributeErrors not exported (error_types.py:138):

• Defined in error_types.py but absent from hed/errors/__init__.py
• Users implementing schema validators can't access these codes via the package

TagQualityErrors not exported (error_types.py:206):

• Same problem. Defined but not exported anywhere in the public API.

get_printable_issue_string_html not exported (error_reporter.py:604):

• There is an HTML variant of the primary get_printable_issue_string function.
• It is not exported from hed/errors/__init__.py, only the plain-text version is.

check_for_any_errors not exported (error_reporter.py:567):

• Useful utility after calling validate(). Not exported from hed/errors/__init__.py.

---

2. hed/__init__.py Top-Level Namespace Bloat / Inconsistency

BaseInput exposed at top level (hed/__init__.py:6):

• BaseInput is an abstract/internal superclass — end users never need to import it directly.
• Its presence at the top level invites misuse and pollutes the top-level namespace.
• Recommend removing from hed/__init__.py (keep in hed.models for typing purposes).

get_printable_issue_string at top level (hed/__init__.py:3):

• This is a low-level formatting utility, not a core API symbol. Moving it to hed.errors (already there) and removing from top-level would keep the top-level namespace focused on the major classes/functions.

HedGroup absent from top level:

• HedString inherits from HedGroup, and HedGroup is the object returned when traversing tag groups. Yet HedGroup is not in hed/__init__.py, forcing users to from hed.models import HedGroup.
• This is an inconsistency since HedTag IS at top level.

TimeseriesInput and batch helpers absent from top level:

• hed/models/__init__.py exports TimeseriesInput, convert_to_form, shrink_defs, expand_defs, process_def_expands, but none of these appear in hed/__init__.py.
• Either they belong in the top-level API (if public), or the models/__init__.py docstring is misleading.

---

3. hed/models/__init__.py — Internal Classes in Public API

ColumnMapper exported (models/__init__.py:51):

• An internal mapping class, implementation detail of TabularInput/SpreadsheetInput. Should not be public unless users are expected to subclass or configure it directly.

DefinitionEntry exported (models/__init__.py:54):

• Lower-level companion to DefinitionDict. Unless users iterate over definitions and need the entry type, this is an implementation detail.

ColumnMetadata / ColumnType exported (models/__init__.py:52):

• These support column configuration, which is somewhat public. However, ColumnType is used to set column behavior, so it is needed. Worth explicitly documenting the intended use.

---

4. hed/schema/__init__.py — Over-Exposed Internal Classes

HedSchemaEntry, UnitClassEntry, UnitEntry, HedTagEntry (schema/__init__.py:44):

• These are internal schema entry classes representing nodes in the schema tree.
• Unless users are expected to navigate schema structure programmatically (schema authors), these are implementation details.

HedSchemaSection (schema/__init__.py:46):

• Same concern — internal structure class.

from_dataframes / save_dataframes / load_dataframes consistency:

• from_dataframes is exported from hed.schema, but save_dataframes / load_dataframes are only available via hed.schema.schema_io. If these are a coherent set of DataFrame round-trip functions, they should all be at the same level.

---

5. hed/tools/__init__.py — Incomplete and Inconsistent Exports

hed/tools/util/__init__.py is empty (tools/util/__init__.py:1):

• tools/util/ contains data_util.py and io_util.py with dozens of utility functions.
• The util/__init__.py exports nothing at all. Users who from hed.tools.util import X get nothing; they must use from hed.tools.util.data_util import X.
• hed/tools/__init__.py re-exports a subset of data_util and io_util but many functions are silently missing:
  • Not re-exported from tools.__init__: add_columns, check_match, delete_columns, delete_rows_by_column, get_eligible_values, get_key_hash, get_row_hash, make_info_dataframe, replace_na, separate_values from data_util
  • Not re-exported: get_alphanumeric_path, get_full_extension, get_unique_suffixes, get_basename, get_filtered_by_element, get_filtered_list, get_timestamp, get_task_from_file, get_task_dict, separate_by_ext from io_util

Inconsistency between hed/tools/__init__.py and hed/tools/bids/__init__.py:

• tools/bids/__init__.py exports walk_back, get_candidates, matches_criteria from bids_util
• tools/__init__.py only re-exports parse_bids_filename from bids_util
• The others are accessible via hed.tools.bids but not hed.tools. Decide whether these are public API (if so, add to tools.__init__) or internal (if so, remove from tools/bids/__init__.py).

---

6. hed/validator/__init__.py — Internal Sub-validators Exposed

hed/validator/util/__init__.py exposes low-level internal classes (validator/util/__init__.py):

• CharValidator, CharRexValidator, StringValidator, UnitValueValidator, TagValidator, GroupValidator are all internal sub-validators.
• These are implementation details of HedValidator. For v1.0, either document them as stable internal API or unexpose them.

Too many validators in hed.validator:

• SidecarValidator, DefValidator, OnsetValidator, SpreadsheetValidator are exported.
• In most workflows users only need HedValidator. Consider whether the sub-validators belong in the public API or should only be imported if users have advanced use cases.

---

7. hed/schema/schema_validation/__init__.py — Too Much Exposed

This sub-package exports a large number of internal implementation details:

• Attribute validator functions (attribute_is_deprecated, allowed_characters_check, etc.) are internal schema validation helpers
• Constants DOMAIN_TO_SECTION, SECTION_TO_DOMAIN, CONTENT_SECTIONS are schema-internal structure data
• The _new suffix on validate_schema_description_new, validate_schema_tag_new, validate_schema_term_new is a code smell suggesting mid-refactor state — these should be renamed or removed before 1.0

---

8. API Design Issues Appropriate for a Breaking 1.0 Release

Issues are dict not a typed object:

• All validate() calls return list[dict] with string keys ("code", "message", "severity", "source_tag", etc.)
• For a 1.0 public API, a typed HedIssue (or ValidationIssue) dataclass/namedtuple would be far more discoverable and stable
• This would also allow IDE autocomplete and type-checking

ErrorSeverity is a plain class with integer class variables (error_types.py:4):

• ErrorSeverity.ERROR = 1, ErrorSeverity.WARNING = 10
• For 1.0, this should be a proper IntEnum to get membership testing, iteration, string representation, and prevent invalid values

include_groups magic integer parameter in find_top_level_tags (hed_string.py:362):

• include_groups=0 means return only tags, include_groups=1 means return only groups, include_groups=2 means return both
• Magic integers are a well-known anti-pattern — use an Enum or Literal type for v1.0

Silent parse failure in HedString.__init__ (hed_string.py:31-48):

• When parsing fails due to malformed parentheses, the constructor silently falls back to an empty children list
• This is documented but surprising: calling code that doesn't validate will see no errors and get an empty object
• Consider raising a parse error or providing a factory method HedString.try_parse() that makes the choice explicit

HedString.validate() vs HedValidator.validate():

• Users can call hed_string.validate() (creates a new HedValidator each time) or HedValidator.validate(hed_string) (reuses the validator)
• The convenience method HedString.validate() is fine, but the docs should clearly explain the performance trade-off for batch validation

HedExceptions code values are a mix of styles (exceptions.py):

• Some codes use SCREAMING_SNAKE_CASE (e.g. FILE_NOT_FOUND = "FILE_NOT_FOUND")
• Others use camelCase string values (e.g. FILE_NOT_FOUND = "fileNotFound", BAD_PARAMETERS = "badParameters")
• This should be normalized to one style for v1.0

Same issue in SidecarErrors (error_types.py:106):

• Values like "blankValueString", "wrongHedDataType", "invalidNumberPoundSigns" mix camelCase with SCREAMING_SNAKE_CASE in a class called SidecarErrors

---

Summary of Priority Recommendations

Priority	Issue
High	Fix HedQueryError missing from hed.errors (breaks from hed.errors import HedQueryError)
High	Export SchemaAttributeErrors and TagQualityErrors from hed.errors
High	Normalize error code string values (camelCase vs SNAKE_CASE) in HedExceptions, SidecarErrors
High	Fix _new-suffixed functions in schema_validation/__init__.py
Medium	Remove BaseInput from hed/__init__.py top-level
Medium	Add HedGroup to hed/__init__.py for consistency with HedTag/HedString
Medium	Make ErrorSeverity a proper IntEnum
Medium	Replace include_groups magic integer with Enum/Literal
Medium	Populate or document hed/tools/util/__init__.py
Medium	Align hed/tools/__init__.py and hed/tools/bids/__init__.py exports
Low	Consider typed HedIssue dataclass instead of raw dict
Low	Remove or clearly document internal classes (ColumnMapper, DefinitionEntry, HedSchemaSection, etc.)
Low	Export get_printable_issue_string_html and check_for_any_errors from hed.errors

[VisLab]

Addressed in PR #1265