feat(bst): Defer type imports (#2269)

* feat: Add _lazytypes

* rf: Move version loading into submodule

* type: Use lazytypes throughout

* chore: Add type checking dependency group

* type: Improve type annotations for __main__

* [DATALAD RUNCMD] uv lock

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "uv lock",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [
  "pyproject.toml",
  "tools/schemacode/pyproject.toml",
  "uv.lock"
 ],
 "outputs": [
  "uv.lock"
 ],
 "pwd": "."
}
^^^ Do not change lines above ^^^

* chore: Use Python 3.13 to build docs

Author: effigies

readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    python: latest
+    python: '3.13'
   jobs:
     # The *create_environment steps replace RTD's virtual environment
     # steps with uv, a much faster alternative to virtualenv+pip.

tools/schemacode/.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    python: latest
+    python: '3.13'
   jobs:
     create_environment:
       - asdf plugin add uv https://github.com/asdf-community/asdf-uv.git

tools/schemacode/pyproject.toml

@@ -155,3 +155,13 @@ select = [
 
 [tool.ruff.lint.extend-per-file-ignores]
 "*/__init__.py" = ["F401"]
+
+[dependency-groups]
+types = [
+  "lxml>=6.0.2",
+  "mypy>=1.18.2",
+  "pandas-stubs>=2.2.2.240807",
+  "types-jsonschema>=4.25.1.20251009",
+  "types-pyyaml>=6.0.12.20250915",
+  "types-tabulate>=0.9.0.20241207",
+]

tools/schemacode/src/bidsschematools/__init__.py

@@ -11,43 +11,10 @@
 
 
 def __getattr__(attr: str) -> str:
-    """Lazily load the schema version and BIDS version from the filesystem."""
-    from typing import TypeVar
+    if attr in __all__:
+        from . import _version
 
-    from .data import load
-
-    T = TypeVar("T")
-
-    def document(obj: T, docstring: str) -> T:
-        tp = type(obj)
-        return type(tp.__name__, (tp,), {"__doc__": docstring})(obj)
-
-    versions = {
-        "__version__": (
-            "schema/SCHEMA_VERSION",
-            "schema_version",
-            "Schema version",
-        ),
-        "__bids_version__": (
-            "schema/BIDS_VERSION",
-            "bids_version",
-            "BIDS specification version",
-        ),
-    }
-
-    if attr in versions:
-        dir_path, schema_path, docstring = versions[attr]
-
-        # Fast path if the schema directory is present (editable mode)
-        if (version_file := load.readable(dir_path)).is_file():
-            version = version_file.read_text().strip()
-        else:
-            # If version files are absent, the schema.json has been packaged.
-            # If we're going to read it, we might as well cache it with load_schema().
-            from .schema import load_schema
-
-            version = load_schema()[schema_path]
-        globals()[attr] = document(version, docstring)
+        globals()[attr] = getattr(_version, attr)
         return globals()[attr]
 
     raise AttributeError(f"module {__spec__.name!r} has no attribute {attr!r}")

tools/schemacode/src/bidsschematools/__main__.py

@@ -4,6 +4,7 @@
 import re
 import sys
 from itertools import chain
+from pathlib import Path
 
 import click
 
@@ -18,19 +19,19 @@
 @click.group()
 @click.option("-v", "--verbose", count=True)
 @click.option("-q", "--quiet", count=True)
-def cli(verbose, quiet):
+def cli(verbose: int, quiet: int) -> None:
     """BIDS Schema Tools"""
     verbose = verbose - quiet
     configure_logger(get_logger(level=logging.WARNING - verbose * 10))
 
 
 @cli.command()
-@click.option("--schema")
+@click.option("--schema", "-s", "schema_path", type=click.Path(), help="Path to the BIDS schema")
 @click.option("--output", default="-")
 @click.pass_context
-def export(ctx, schema, output):
+def export(ctx: click.Context, schema_path: Path | None, output: Path | str) -> None:
     """Export BIDS schema to JSON document"""
-    schema = load_schema(schema)
+    schema = load_schema(schema_path)
     text = schema.to_json()
     if output == "-":
         lgr.debug("Writing to stdout")
@@ -45,7 +46,7 @@ def export(ctx, schema, output):
 @cli.command()
 @click.option("--output", default="-")
 @click.pass_context
-def export_metaschema(ctx, output):
+def export_metaschema(ctx: click.Context, output: Path | str) -> None:
     """Export BIDS schema to JSON document"""
     from .data import load
 
@@ -59,7 +60,7 @@ def export_metaschema(ctx, output):
 
 
 @cli.command("pre-receive-hook")
-@click.option("--schema", "-s", type=click.Path(), help="Path to the BIDS schema")
+@click.option("--schema", "-s", "schema_path", type=click.Path(), help="Path to the BIDS schema")
 @click.option(
     "--input", "-i", "input_", default="-", type=click.Path(), help="Input file (default: stdin)"
 )
@@ -71,7 +72,7 @@ def export_metaschema(ctx, output):
     type=click.Path(),
     help="Output file (default: stdout)",
 )
-def pre_receive_hook(schema, input_, output):
+def pre_receive_hook(schema_path: Path | None, input_: Path | str, output: Path | str) -> None:
     """Validate filenames from a list of files against the BIDS schema
 
     The expected input takes the following form:
@@ -101,7 +102,7 @@ def pre_receive_hook(schema, input_, output):
 
     This is intended to be used in a git pre-receive hook.
     """
-    schema = load_schema(schema)
+    schema = load_schema(schema_path)
 
     # Slurp inputs for now; we can think about streaming later
     if input_ == "-":
@@ -151,12 +152,12 @@ def pre_receive_hook(schema, input_, output):
 
     regexes = [rule["regex"] for rule in all_rules]
 
-    output = sys.stdout if output == "-" else open(output, "w")
+    out_stream = sys.stdout if output == "-" else open(output, "w")
 
     rc = 0
     any_files = False
     valid_files = 0
-    with output:
+    with out_stream:
         for filename in stream:
             if not any_files:
                 lgr.debug("Validating files, first file: %s", filename)
@@ -167,7 +168,7 @@ def pre_receive_hook(schema, input_, output):
             ):
                 continue
             if not any(re.match(regex, filename) for regex in regexes):
-                print(filename, file=output)
+                print(filename, file=out_stream)
                 rc = 1
             else:
                 valid_files += 1

tools/schemacode/src/bidsschematools/_lazytypes.py

@@ -0,0 +1,102 @@
+"""Typing symbols for the bidsschematools package.
+
+This module aims to make the types used by the bidsschematools package available for
+type checking without requiring the original packages to be imported at runtime.
+
+The expected usage is::
+
+    from __future__ import annotations
+
+    import bidsschematools._lazytypes as lt
+
+    def func(arg: lt.Any) -> ReturnType:
+        ...
+
+
+If used outside of type annotations, for example, in an ``isinstance()`` check,
+the attribute will trigger an import.
+"""
+
+import sys
+
+__all__ = (
+    # typing
+    "Any",
+    "Callable",
+    "Literal",
+    "NotRequired",
+    "Protocol",
+    "Self",
+    "TYPE_CHECKING",
+    "TypeVar",
+    "TypedDict",
+    # collections.abc
+    "Iterator",
+    "Mapping",
+    # contextlib
+    "AbstractContextManager",
+    # third-party
+    "FormatChecker",
+    "JsonschemaValidator",
+    "Traversable",
+)
+
+_type_map = {
+    "AbstractContextManager": ("contextlib", "AbstractContextManager"),
+    "Iterator": ("collections.abc", "Iterator"),
+    "Mapping": ("collections.abc", "Mapping"),
+    "Traversable": ("acres.typ", "Traversable"),
+    "FormatChecker": ("jsonschema", "FormatChecker"),
+    "JsonschemaValidator": ("jsonschema.protocols", "JsonschemaValidator"),
+}
+
+RUNTIME_IMPORT: bool
+
+TYPE_CHECKING = False
+if TYPE_CHECKING or "sphinx.ext.autodoc" in sys.modules:  # pragma: no cover
+    from typing import Any, Callable, Literal, NotRequired, Protocol, Self, TypeVar, TypedDict
+
+    from collections.abc import Iterator, Mapping
+    from contextlib import AbstractContextManager
+
+    from acres.typ import Traversable
+    from jsonschema import FormatChecker
+    from jsonschema.protocols import Validator as JsonschemaValidator
+
+    # Helpful TypeVars for generic classes and functions.
+    # These should never be accessed at runtime, only for type checking, so exclude from __all__.
+    T = TypeVar("T")
+    T_co = TypeVar("T_co", covariant=True)
+    T_contra = TypeVar("T_contra", contravariant=True)
+else:  # pragma: no cover
+
+    def __getattr__(name: str):
+        # Set the BIDSSCHEMATOOLS_DISABLE_RUNTIME_TYPES environment variable to
+        # crash out if attributes are ever accessed at runtime.
+        # Currently, we do not use this feature.
+        global RUNTIME_IMPORT
+        try:
+            throw = not RUNTIME_IMPORT
+        except NameError:
+            import os
+
+            RUNTIME_IMPORT = not os.getenv("BIDSSCHEMATOOLS_DISABLE_RUNTIME_TYPES", "")
+            if name == "RUNTIME_IMPORT":
+                return RUNTIME_IMPORT
+            throw = not RUNTIME_IMPORT
+
+        if throw:
+            raise AttributeError(
+                f"Attribute {name!r} in module {__name__!r} should only be used for type checking."
+            )
+
+        if name in __all__:
+            if name in _type_map:
+                mod, attr = _type_map[name]
+            else:
+                mod, attr = "typing", name
+            globals()[name] = getattr(__import__(mod), attr)
+            return globals()[name]
+
+        msg = f"Module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)

tools/schemacode/src/bidsschematools/_version.py

@@ -0,0 +1,54 @@
+"""Lazy version strings
+
+.. autodata:: __version__
+.. autodata:: __bids_version__
+"""
+
+from __future__ import annotations
+
+from . import _lazytypes as lt
+
+__version__: str
+__bids_version__: str
+
+__all__ = ("__version__", "__bids_version__")
+
+
+def document(obj: lt.T, docstring: str) -> lt.T:
+    tp = type(obj)
+    return type(tp.__name__, (tp,), {"__doc__": docstring})(obj)
+
+
+def __getattr__(attr: str) -> str:
+    """Lazily load the schema version and BIDS version from the filesystem."""
+    from .data import load
+
+    versions = {
+        "__version__": (
+            "schema/SCHEMA_VERSION",
+            "schema_version",
+            "Schema version",
+        ),
+        "__bids_version__": (
+            "schema/BIDS_VERSION",
+            "bids_version",
+            "BIDS specification version",
+        ),
+    }
+
+    if attr in versions:
+        dir_path, schema_path, docstring = versions[attr]
+
+        # Fast path if the schema directory is present (editable mode)
+        if (version_file := load.readable(dir_path)).is_file():
+            version = version_file.read_text().strip()
+        else:
+            # If version files are absent, the schema.json has been packaged.
+            # If we're going to read it, we might as well cache it with load_schema().
+            from .schema import load_schema
+
+            version = load_schema()[schema_path]
+        globals()[attr] = document(version, docstring)
+        return globals()[attr]
+
+    raise AttributeError(f"module {__spec__.name!r} has no attribute {attr!r}")

tools/schemacode/src/bidsschematools/schema.py

@@ -12,12 +12,7 @@
 from . import data, utils
 from .types import Namespace
 
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Any, Callable
-
-    from acres import typ as at
-    from jsonschema.protocols import Validator as JsonschemaValidator
+from . import _lazytypes as lt
 
 lgr = utils.get_logger()
 
@@ -26,7 +21,7 @@ class BIDSSchemaError(Exception):
     """Errors indicating invalid values in the schema itself"""
 
 
-def _get_schema_version(schema_dir: str | at.Traversable) -> str:
+def _get_schema_version(schema_dir: str | lt.Traversable) -> str:
     """
     Determine schema version for given schema directory, based on file specification.
     """
@@ -37,7 +32,7 @@ def _get_schema_version(schema_dir: str | at.Traversable) -> str:
     return schema_version_path.read_text().strip()
 
 
-def _get_bids_version(schema_dir: str | at.Traversable) -> str:
+def _get_bids_version(schema_dir: str | lt.Traversable) -> str:
     """
     Determine BIDS version for given schema directory, with directory name, file specification,
     and string fallback.
@@ -57,7 +52,7 @@ def _get_bids_version(schema_dir: str | at.Traversable) -> str:
     return str(schema_dir)
 
 
-def _find(obj: object, predicate: Callable[[Any], bool]) -> Iterable[object]:
+def _find(obj: object, predicate: lt.Callable[[lt.Any], bool]) -> Iterable[object]:
     """Find objects in an arbitrary object that satisfy a predicate.
 
     Note that this does not cut branches, so every iterable sub-object
@@ -106,7 +101,7 @@ def _dereference(namespace: MutableMapping, base_schema: Namespace) -> None:
 
 
 @cache
-def get_schema_validator() -> JsonschemaValidator:
+def get_schema_validator() -> lt.JsonschemaValidator:
     """Get the jsonschema validator for validating BIDS schemas."""
     metaschema = json.loads(data.load.readable("metaschema.json").read_text())
     return utils.jsonschema_validator(metaschema, check_format=True)
@@ -194,7 +189,7 @@ def flatten_enums(namespace: Namespace, inplace=True) -> Namespace:
 
 
 @lru_cache
-def load_schema(schema_path: at.Traversable | str | None = None) -> Namespace:
+def load_schema(schema_path: lt.Traversable | str | None = None) -> Namespace:
     """Load the schema into a dict-like structure.
 
     This function allows the schema, like BIDS itself, to be specified in