Merge pull request #1309 from VisLab/new_release

Removed string search from public interface -- experimental

Author: VisLab

README.md

@@ -160,6 +160,19 @@ jupyter notebook examples/
 
 See [`examples/README.md`](examples/README.md) for more details.
 
+## Experimental features
+
+**String-based search** (`hed.models.string_search` and `hed.models.schema_lookup`) is a middle-ground search facility that operates on raw HED strings without requiring pre-parsed `HedString` objects or a loaded schema. It supports the full `QueryHandler` query syntax (logical operators, grouping, wildcards) and optionally accepts a pre-generated schema lookup dictionary to enable ancestor-aware matching on short-form strings.
+
+> **This facility is still experimental.** Its API — including class names, function signatures, and module structure — may change in future releases without notice. These modules are **not** exported from the top-level `hed` package; import them directly:
+>
+> ```python
+> from hed.models.string_search import StringQueryHandler, string_search
+> from hed.models.schema_lookup import generate_schema_lookup
+> ```
+
+See the [search details documentation](https://www.hedtags.org/hed-python/search_details.html) for a full comparison of all three search implementations and performance benchmarks.
+
 ## Documentation
 
 📖 **Full Documentation:** [https://www.hedtags.org/hed-python](https://www.hedtags.org/hed-python)

docs/api/models.rst

@@ -177,8 +177,16 @@ search_hed_objs
 
 .. autofunction:: hed.models.query_service.search_hed_objs
 
-String-based search
--------------------
+String-based search (experimental)
+-----------------------------------
+
+.. warning::
+
+   This facility is **experimental**. Its API (classes, function signatures, and
+   behaviour) may change in future releases without notice.  Do **not** rely on
+   ``hed.models.string_search`` or ``hed.models.schema_lookup`` as a stable
+   public interface.  Import directly from those sub-modules rather than from
+   the top-level ``hed`` package.
 
 Search functions that operate on raw HED strings without requiring pre-parsed ``HedString`` objects
 or a loaded schema. See also :doc:`/search_details` for a full comparison of all three

docs/search_details.md

@@ -53,7 +53,14 @@ Use `QueryHandler` when you need schema-aware ancestor matching, or when you wan
 
 #### `StringQueryHandler` — tree-based schema-optional search
 
-Located in {mod}`hed.models.string_search`, `StringQueryHandler` is a new middle-ground implementation that inherits from `QueryHandler` and reuses the full expression-tree compiler, but operates on raw strings rather than pre-parsed `HedString` objects.
+```{warning}
+This facility is **experimental**. The API of `hed.models.string_search` and
+`hed.models.schema_lookup` may change in future releases without notice.
+These modules are **not** part of the stable public interface exported from
+the top-level `hed` package.  Import directly from the sub-modules.
+```
+
+Located in {mod}`hed.models.string_search`, `StringQueryHandler` is a middle-ground implementation that inherits from `QueryHandler` and reuses the full expression-tree compiler, but operates on raw strings rather than pre-parsed `HedString` objects.
 
 It parses each raw HED string into a lightweight {class}`~hed.models.string_search.StringNode` tree that duck-types the `HedGroup`/`HedTag` interfaces expected by the existing expression evaluators — so all `QueryHandler` query syntax works unchanged.
 
@@ -71,11 +78,16 @@ Use `StringQueryHandler` when you have raw strings (not `HedString` objects), ne
 
 #### Generating a schema lookup
 
+```{note}
+`hed.models.schema_lookup` is part of the experimental string-search facility.
+Its interface may change in future releases.
+```
+
 If you want `StringQueryHandler` to resolve ancestors for short-form strings (e.g. query `Event` matching `Sensory-event`) without a full schema parse per row, you can pre-generate a lookup dictionary from a `HedSchema`:
 
 ```python
 from hed import load_schema_version
-from hed import generate_schema_lookup, save_schema_lookup, load_schema_lookup
+from hed.models.schema_lookup import generate_schema_lookup, save_schema_lookup, load_schema_lookup
 
 schema = load_schema_version("8.4.0")
 lookup = generate_schema_lookup(schema)  # {short_name_casefold: tag_terms_tuple}

hed/__init__.py

@@ -9,8 +9,6 @@
 from hed.models.definition_dict import DefinitionDict
 from hed.models.query_handler import QueryHandler
 from hed.models.query_service import get_query_handlers, search_hed_objs
-from hed.models.string_search import StringQueryHandler, parse_hed_string, string_search
-from hed.models.schema_lookup import generate_schema_lookup, load_schema_lookup, save_schema_lookup
 
 from hed.schema.hed_schema import HedSchema
 from hed.schema.hed_schema_group import HedSchemaGroup