rf: Rename schema adapter, drop bids_schema reference, default load(None)

Author: effigies

bids2table/_entities.py

@@ -13,7 +13,7 @@
 import pyarrow as pa
 
 from ._logging import setup_logger
-from ._schema import BIDSSchema
+from ._schema import SchemaAdapter
 
 BIDSValue = str | int
 
@@ -93,15 +93,15 @@ def _parse_bids_datatype(path: Path) -> str | None:
 
 def validate_bids_entities(
     entities: dict[str, Any],
-    schema: BIDSSchema | pa.Schema | None = None,
+    schema: SchemaAdapter | pa.Schema | None = None,
 ) -> tuple[dict[str, BIDSValue], dict[str, Any]]:
     """Validate BIDS entities against a schema.
 
     Validates the type and allowed values of each entity against the BIDS schema.
 
     Args:
         entities: dict mapping BIDS keys to unvalidated entities.
-        schema: A `BIDSSchema`, a `pa.Schema` (e.g. inside a worker process), or
+        schema: A `SchemaAdapter`, a `pa.Schema` (e.g. inside a worker process), or
             None to use the module-level default.
 
     Returns:
@@ -110,15 +110,14 @@ def validate_bids_entities(
             mapping of any leftover entity mappings that didn't match a known entity or
             failed validation.
     """
-    entity_schema, name_entity_map = BIDSSchema.prepare(schema).lookups()
+    schema_adapter = SchemaAdapter.load(schema)
 
     valid_entities: dict[str, BIDSValue] = {}
-    extra_entities: dict[str, Any] = {}
+    extra_entities: dict[str, str] = {}
 
     for name, value in entities.items():
-        if name in name_entity_map:
-            entity = name_entity_map[name]
-            cfg = entity_schema[entity]
+        if entity := schema_adapter.name_entity_map.get(name):
+            cfg = schema_adapter.entity_schema[entity]
             typ = _BIDS_FORMAT_PY_TYPE_MAP[cfg["format"]]
 
             # Cast to target type.

bids2table/_indexing.py

@@ -25,7 +25,7 @@
 )
 from ._logging import setup_logger
 from ._pathlib import CloudPath, PathT, as_path, cloudpathlib_is_available
-from ._schema import BIDSSchema
+from ._schema import SchemaAdapter
 
 _BIDS_SUBJECT_DIR_PATTERN = re.compile(r"sub-[a-zA-Z0-9]+")
 
@@ -91,15 +91,15 @@
 
 
 def get_arrow_schema(
-    schema: BIDSSchema | pa.Schema | None = None,
+    schema: SchemaAdapter | pa.Schema | None = None,
 ) -> pa.Schema:
     """Get Arrow schema of the BIDS dataset index.
 
     Args:
-        schema: A `BIDSSchema`, a `pa.Schema`, or None to use the module-level
+        schema: A `SchemaAdapter`, a `pa.Schema`, or None to use the module-level
             default BIDS schema.
     """
-    bids_schema = BIDSSchema.prepare(schema)
+    bids_schema = SchemaAdapter.load(schema)
     entity_schema = bids_schema.arrow_schema
     index_fields = {
         name: pa.field(name, cfg["dtype"], metadata=cfg["metadata"])
@@ -120,12 +120,12 @@ def get_arrow_schema(
 
 
 def get_column_names(
-    schema: BIDSSchema | pa.Schema | None = None,
+    schema: SchemaAdapter | pa.Schema | None = None,
 ) -> enum.StrEnum:
     """Get an enum of the BIDS index columns.
 
     Args:
-        schema: A `BIDSSchema`, a `pa.Schema`, or None to use the module-level
+        schema: A `SchemaAdapter`, a `pa.Schema`, or None to use the module-level
             default BIDS schema.
     """
     arrow_schema = get_arrow_schema(schema=schema)
@@ -210,7 +210,7 @@ def index_dataset(
     chunksize: int = 32,
     executor_cls: type[Executor] = ProcessPoolExecutor,
     show_progress: bool = False,
-    schema: BIDSSchema | pa.Schema | Namespace | str | Path | None = None,
+    schema: SchemaAdapter | pa.Schema | Namespace | str | Path | None = None,
 ) -> pa.Table:
     """Index a BIDS dataset.
 
@@ -226,7 +226,7 @@ def index_dataset(
             `ProcessPoolExecutor` when `max_workers > 0`.
         executor_cls: Executor class to use for parallel indexing.
         show_progress: Show progress bar.
-        schema: A `BIDSSchema`, `pa.Schema`, `Namespace`, path/URL, or None to use
+        schema: A `SchemaAdapter`, `pa.Schema`, `Namespace`, path/URL, or None to use
             the module-level default. Per-call schema overrides propagate to worker
             processes.
 
@@ -235,7 +235,7 @@ def index_dataset(
     """
     root = as_path(root)
 
-    bids_schema = BIDSSchema.prepare(schema)
+    bids_schema = SchemaAdapter.load(schema)
     entity_arrow_schema = bids_schema.arrow_schema
     full_schema = get_arrow_schema(schema=bids_schema)
 
@@ -278,7 +278,7 @@ def batch_index_dataset(
     max_workers: int | None = 0,
     executor_cls: type[Executor] = ProcessPoolExecutor,
     show_progress: bool = False,
-    schema: BIDSSchema | pa.Schema | Namespace | str | Path | None = None,
+    schema: SchemaAdapter | pa.Schema | Namespace | str | Path | None = None,
 ) -> Generator[pa.Table, None, None]:
     """Index a batch of BIDS datasets.
 
@@ -290,13 +290,13 @@ def batch_index_dataset(
             See `concurrent.futures.ProcessPoolExecutor` for details.
         executor_cls: Executor class to use for parallel indexing.
         show_progress: Show progress bar.
-        schema: A `BIDSSchema`, `pa.Schema`, `Namespace`, path/URL, or None to use
+        schema: A `SchemaAdapter`, `pa.Schema`, `Namespace`, path/URL, or None to use
             the module-level default.
 
     Yields:
         An Arrow table index for each BIDS dataset.
     """
-    bids_schema = BIDSSchema.prepare(schema)
+    bids_schema = SchemaAdapter.load(schema)
     entity_arrow_schema = bids_schema.arrow_schema
     func = partial(_batch_index_func, schema=entity_arrow_schema)
 
@@ -421,7 +421,7 @@ def _index_bids_subject_dir(
 
     Args:
         path: BIDS subject directory.
-        schema: BIDS entity Arrow schema (i.e. ``BIDSSchema.arrow_schema``).
+        schema: BIDS entity Arrow schema (i.e. ``SchemaAdapter.arrow_schema``).
             Pass-through to validation; the full index schema is derived from
             it. None uses the module-level default.
         dataset: Dataset identifier; computed if not given.

bids2table/_schema.py

@@ -105,37 +105,38 @@ def _entity_lookups_from_arrow(
 
 
 @dataclass(frozen=True)
-class BIDSSchema:
+class SchemaAdapter:
     """Encapsulates a BIDS schema and its derived Arrow representation.
 
-    Use `BIDSSchema.from_path`, `from_namespace`, `from_arrow`, or `prepare`
-    rather than constructing directly.
+    Use `SchemaAdapter.load` rather than constructing directly.
     """
 
     arrow_schema: pa.Schema
-    _entity_schema: dict[str, dict[str, Any]] = field(repr=False)
-    _name_entity_map: dict[str, str] = field(repr=False)
-    bids_schema: Namespace | None = field(default=None, repr=False)
+    entity_schema: dict[str, dict[str, Any]] = field(repr=False)
+    name_entity_map: dict[str, str] = field(repr=False)
 
     @classmethod
-    def prepare(
-        cls, schema: "BIDSSchema | pa.Schema | Namespace | str | Path | None"
-    ) -> "BIDSSchema":
+    def load(
+        cls,
+        schema: SchemaAdapter | pa.Schema | Namespace | str | Path | None = None,
+    ) -> SchemaAdapter:
         """Polymorphic constructor.
 
-        - `BIDSSchema` -> returned unchanged
-        - `pa.Schema` -> via `from_arrow`
-        - `Namespace` -> via `from_namespace`
-        - `str` / `Path` / `None` -> via `from_path`
+        Existing SchemaAdapters and pyarrow Schemas are passed through with minimal processing.
+
+        Paths and `None` are passed directly to `bidsschematools.schema.load_schema` for loading,
+        and the resulting `Namespace` is queried to extract the components used by bids2table.
+
+        A pre-loaded `Namespace` is also accepted, for callers that may want to modify a schema.
         """
         if isinstance(schema, cls):
             return schema
         elif isinstance(schema, pa.Schema):
             entity_schema, name_entity_map = _entity_lookups_from_arrow(schema)
             return cls(
                 arrow_schema=schema,
-                _entity_schema=entity_schema,
-                _name_entity_map=name_entity_map,
+                entity_schema=entity_schema,
+                name_entity_map=name_entity_map,
             )
 
         ns: Namespace = (
@@ -157,11 +158,6 @@ def prepare(
         )
         return cls(
             arrow_schema=arrow_schema,
-            _entity_schema=entity_schema,
-            _name_entity_map=name_entity_map,
-            bids_schema=ns,
+            entity_schema=entity_schema,
+            name_entity_map=name_entity_map,
         )
-
-    def lookups(self) -> tuple[dict[str, dict[str, Any]], dict[str, str]]:
-        """Return `(entity_schema, name_entity_map)` for validation."""
-        return self._entity_schema, self._name_entity_map

tests/test_entities.py

@@ -9,7 +9,7 @@
     parse_bids_entities,
     validate_bids_entities,
 )
-from bids2table._schema import BIDSSchema
+from bids2table._schema import SchemaAdapter
 
 
 class ExampleCase(NamedTuple):
@@ -104,14 +104,14 @@ def test_format_bids_path(path: str):
 
 
 def test_validate_bids_entities_accepts_explicit_bids_schema():
-    schema = BIDSSchema.prepare(None)
+    schema = SchemaAdapter.load()
     valid, extra = validate_bids_entities({"sub": "01", "task": "rest"}, schema=schema)
     assert valid == {"sub": "01", "task": "rest"}
     assert extra == {}
 
 
 def test_validate_bids_entities_accepts_arrow_schema():
-    schema = BIDSSchema.prepare(None)
+    schema = SchemaAdapter.load()
     valid, extra = validate_bids_entities(
         {"sub": "01", "task": "rest"}, schema=schema.arrow_schema
     )
@@ -126,7 +126,7 @@ def test_validate_bids_entities_default_schema_unchanged():
 
 
 def test_validate_bids_entities_arrow_and_bids_schema_paths_agree():
-    schema = BIDSSchema.prepare(None)
+    schema = SchemaAdapter.load()
     entities = {"sub": "01", "task": "rest", "run": "1"}
     bids_result = validate_bids_entities(entities, schema=schema)
     arrow_result = validate_bids_entities(entities, schema=schema.arrow_schema)

tests/test_indexing.py

@@ -9,7 +9,7 @@
 import bids2table._indexing as indexing
 from bids2table._indexing import get_arrow_schema, get_column_names
 from bids2table._pathlib import cloudpathlib_is_available
-from bids2table._schema import BIDSSchema
+from bids2table._schema import SchemaAdapter
 
 BIDS_EXAMPLES = Path(__file__).parents[1] / "bids-examples"
 
@@ -254,27 +254,27 @@ def test_h_fmt(num: int, expected: str):
 
 
 def test_get_arrow_schema_with_explicit_schema():
-    s = BIDSSchema.prepare(None)
+    s = SchemaAdapter.load()
     arrow = get_arrow_schema(schema=s)
     assert "sub" in {f.name for f in arrow}
     assert "dataset" in {f.name for f in arrow}
 
 
 def test_get_column_names_with_explicit_schema():
-    s = BIDSSchema.prepare(None)
+    s = SchemaAdapter.load()
     cols = get_column_names(schema=s)
     assert "sub" in [c.value for c in cols]
 
 
 def test_get_arrow_schema_accepts_pa_schema():
-    s = BIDSSchema.prepare(None)
+    s = SchemaAdapter.load()
     arrow = get_arrow_schema(schema=s.arrow_schema)
     assert "sub" in {f.name for f in arrow}
     assert "dataset" in {f.name for f in arrow}
 
 
 def test_index_dataset_with_explicit_schema():
-    s = BIDSSchema.prepare(None)
+    s = SchemaAdapter.load()
     table = indexing.index_dataset(BIDS_EXAMPLES / "ds102", schema=s)
     assert table.num_rows > 0
     assert "sub" in table.schema.names
@@ -284,10 +284,10 @@ def test_index_dataset_workers_honor_explicit_schema():
     """Regression: workers must use the schema passed to index_dataset, not
     re-import the module default.
     """
-    base = BIDSSchema.prepare(None)
+    base = SchemaAdapter.load()
     base_md = {k.decode(): v.decode() for k, v in base.arrow_schema.metadata.items()}
     tagged_arrow = base.arrow_schema.with_metadata({**base_md, "test_marker": "tagged"})
-    tagged = BIDSSchema.prepare(tagged_arrow)
+    tagged = SchemaAdapter.load(tagged_arrow)
 
     table = indexing.index_dataset(
         BIDS_EXAMPLES / "ds102", schema=tagged, max_workers=2
@@ -296,7 +296,7 @@ def test_index_dataset_workers_honor_explicit_schema():
 
 
 def test_batch_index_dataset_with_explicit_schema():
-    s = BIDSSchema.prepare(None)
+    s = SchemaAdapter.load()
     roots = [p.parent for p in BIDS_EXAMPLES.glob("*/dataset_description.json")][:2]
     tables = list(indexing.batch_index_dataset(roots, schema=s))
     assert len(tables) == len(roots)
@@ -305,15 +305,15 @@ def test_batch_index_dataset_with_explicit_schema():
 
 
 def test_two_schemas_one_process_produce_distinct_metadata():
-    """Two BIDSSchema instances yield index tables with distinguishable schemas.
+    """Two SchemaAdapter instances yield index tables with distinguishable schemas.
 
-    Distinguish via a custom marker injected into one BIDSSchema's arrow_schema
+    Distinguish via a custom marker injected into one SchemaAdapter's arrow_schema
     metadata. The non-marked schema must not pick up the marker.
     """
-    base = BIDSSchema.prepare(None)
+    base = SchemaAdapter.load()
     base_md = {k.decode(): v.decode() for k, v in base.arrow_schema.metadata.items()}
     tagged_arrow = base.arrow_schema.with_metadata({**base_md, "test_marker": "tagged"})
-    tagged = BIDSSchema.prepare(tagged_arrow)
+    tagged = SchemaAdapter.load(tagged_arrow)
 
     dataset_root = BIDS_EXAMPLES / "ds102"