feat: Allow schema paths/objects to be passed to API functions

[effigies]

This is a backwards-incompatible break of the current API.

Along the lines of #70 (comment), this introduces a public type:

SchemaSpec: TypeAlias = Namespace | str | PathT | None

This allows a schema reference or schema object to be passed to any of:

• validate_bids_entities
• get_arrow_schema
• get_column_names
• index_dataset
• batch_index_dataset

These functions turn the schema spec into a BIDSSchemaAdapter object, which encapsulates the components that are used by bids2table, and should be extensible going forward:

@dataclass(frozen=True)
class BIDSSchemaAdapter:
    bids_version: str
    schema_version: str
    entity_schema: dict[str, dict[str, Any]] = field(hash=False)

The only current direct consumer is:

def entity_arrow_schema(adapter: BIDSSchemaAdapter) -> pa.Schema: ...

The only current consumer of pa.Schema is:

def _pyarrow_validate_entities(entities: dict[str, Any], *, pa_schema: pa.Schema) -> tuple[dict[str, BIDSValue], dict[str, Any]]: ...

Which is called by the dataset indexer and the public API function validate_bids_entities. The main reason for this indirection is that pa.Schema is passed to _index_dataset_subject_dir and I didn't want to refactor that more than necessary, but this seems like a good, future-thinking approach anyway: By pulling the validation metadata out of the pyarrow schema, a parquet file contains what is needed to validate itself, without needing to look up and load the original schema.

That said, that isn't done here, and I could refactor these functions to take a BIDSSchemaAdapter, which will save a round-trip of metadata into and out of pyarrow.Schema.

Closes #70.
Replaces #71.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.66%. Comparing base (c1d67b2) to head (e8464c1).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #74      +/-   ##
==========================================
+ Coverage   95.15%   95.66%   +0.51%     
==========================================
  Files           7        8       +1     
  Lines         495      531      +36     
==========================================
+ Hits          471      508      +37     
+ Misses         24       23       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[kaitj]

Generally looks great. I think there is minimal to no difference in performance, but I'd like to add / perform a quick benchmark with this before any merging.

@nx10, any additional thoughts, comments?

[effigies]

Yes, please, if you have benchmarks I would be happy to add them to my success criteria while contributing to this project.

[effigies]

The test failure is due to a misconfiguration of "Pytest coverage comment": https://github.com/childmindresearch/bids2table/actions/runs/25566684415/job/75051826576?pr=74

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	10	0	100%
__main__.py	69	8	88%	101, 110, 135, 137–138, 164, 168, 172
_entities.py	93	0	100%
_indexing.py	214	5	97%	149, 158–159, 418, 458
_logging.py	31	4	87%	30, 37, 39–40
_metadata.py	48	4	91%	39–40, 66, 71
_pathlib.py	21	5	76%	16–17, 19–20, 22
_schema.py	52	0	100%
_version.py	11	0	100%
pybids
__init__.py	4	0	100%
_bidsfile.py	38	13	65%	71–73, 77–79, 83–85, 89–91, 95
_layout.py	156	45	71%	63, 72, 81, 104, 114–115, 118, 140–141, 156–157, 173–174, 177–181, 186, 188–189, 192–193, 228, 233, 241, 322–324, 389–394, 396, 399–404, 406, 462, 482
_utils.py	13	5	61%	47–50, 52
TOTAL	760	89	88%

Tests	Skipped	Failures	Errors	Time
131	1 💤	0 ❌	0 🔥	13.845s ⏱️