Merge remote-tracking branch 'upstream/maint/1.10.1'

effigies · effigies · commit ae7fd3a387ad · 2025-10-30T12:23:46.000-04:00
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -51,6 +51,9 @@ nav:
       - Website: https://bids.neuroimaging.io/getting_started/
       - Tutorials: https://bids.neuroimaging.io/getting_started/tutorials/
       - GitHub repository: https://github.com/bids-standard/bids-starter-kit
+exclude_docs: |
+  README.md
+  pregh-changes.md
 theme:
   name: material
   favicon: images/favicon.png
diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,7 @@ dependencies = [
   "bidsschematools[render]",
   "mkdocs>=1.1.0",
   "mkdocs-material>=5.4",
-  "pymdown-extensions>=7.0.0",
+  "pymdown-extensions>=9.2.0",
   "mkdocs-branchcustomization-plugin~=0.1.3",
   "mkdocs-macros-plugin",
   "mkdocs-redirects",
@@ -60,3 +60,7 @@ replace = """NEXT_VERSION_HERE
 - '{new_version}'
 - """
 include_bumps = ['pre_label']
+
+[[tool.mypy.overrides]]
+module = ["pymdownx.*"]
+ignore_missing_imports = true
diff --git a/src/common-principles.md b/src/common-principles.md
@@ -591,7 +591,7 @@ Example:
 ```
 
 Each level can be described with a string as in the example above,
-or with an object containing the fields [`Description`](./glossary.md#description-metadata)
+or with an object containing the fields [`Description`](./glossary.md#description-sense-1-metadata)
 and [`TermURL`](./glossary.md#termurl-metadata)
 like in the example below.
 
diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
@@ -548,9 +548,9 @@ standard BIDS labels:
 
 ```tsv
 index	name	abbreviation
-137	pars	opercularis	IFGop
-138	pars	triangularis	IFGtr
-139	pars	orbitalis	IFGor
+137	pars opercularis	IFGop
+138	pars triangularis	IFGtr
+139	pars orbitalis	IFGor
 ```
 
 <!-- Link Definitions -->
diff --git a/src/modality-specific-files/microscopy.md b/src/modality-specific-files/microscopy.md
@@ -420,8 +420,8 @@ Additional optional columns MAY be used to describe other subjects' attributes.
 `participants.tsv` example:
 ```tsv
 participant_id	species	strain	strain_rrid
-sub-01	mus	musculus	C57BL/6J	RRID:IMSR_JAX:000664
-sub-02	mus	musculus	C57BL/6J	RRID:IMSR_JAX:000664
+sub-01	mus musculus	C57BL/6J	RRID:IMSR_JAX:000664
+sub-02	mus musculus	C57BL/6J	RRID:IMSR_JAX:000664
 ```
 
 `participants.json` example:
diff --git a/src/modality-specific-files/positron-emission-tomography.md b/src/modality-specific-files/positron-emission-tomography.md
@@ -314,7 +314,7 @@ Knudsen et al. 2020
 recommends recording participant body weight.
 If recorded once per participant, these data SHOULD be included in the
 [Participants file](../modality-agnostic-files/data-summary-files.md#participants-file) or as
-[Phenotypic and assessment data](../modality-agnostic-files/data-summary-files.md#phenotypic-and-assessment-data).
+[Phenotypic and assessment data](../modality-agnostic-files/phenotypic-and-assessment-data.md#phenotypic-and-assessment-data).
 
 For example:
 
diff --git a/tools/schemacode/pyproject.toml b/tools/schemacode/pyproject.toml
@@ -43,6 +43,7 @@ render = [
   "tabulate",
   "pandas",
   "markdown-it-py",
+  "pymdown-extensions>=9.2",
 ]
 tests = [
   "bidsschematools[validation,render,expressions]",
diff --git a/tools/schemacode/src/bidsschematools/render/tables.py b/tools/schemacode/src/bidsschematools/render/tables.py
@@ -73,7 +73,8 @@ def _make_object_table(
         # except for subobjects (if table_type) and
         # "additional columns" (field_name.startswith("**"))
         if table_type and not field_name.startswith("**"):
-            field_name = f"[{field_name}]({GLOSSARY_PATH}.md#objects.{table_type}.{element})"
+            sub = table_type if table_type != "subobject" else "metadata"
+            field_name = f"[{field_name}]({GLOSSARY_PATH}.md#objects.{sub}.{element})"
 
         # Grab any requirement level information and text to be added to the description string
         requirement_info, description_addendum = field_info[element]["table_info"]
@@ -297,6 +298,10 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
     formats = ["Format"]
     table = [formats]
 
+    suffix_map = {
+        obj.value: key for key, obj in schema.objects.suffixes.items()
+    }
+
     # Compose header and formats first
     for long_name in schema.rules.entities:
         entity = schema.objects.entities[long_name]
@@ -320,7 +325,7 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
 
     for (dtype, entities), suffixes in rows.items():
         suf_str = " ".join(
-            f"[{suffix}]({GLOSSARY_PATH}.md#objects.suffixes.{suffix})" for suffix in suffixes
+            f"[{suffix}]({GLOSSARY_PATH}.md#objects.suffixes.{suffix_map[suffix]})" for suffix in suffixes
         )
         # TODO: <br> is specific for html form
         fmt_str = f"[{dtype}]({GLOSSARY_PATH}.md#objects.datatypes.{dtype})<br>({suf_str})"
diff --git a/tools/schemacode/src/bidsschematools/render/text.py b/tools/schemacode/src/bidsschematools/render/text.py
@@ -152,6 +152,8 @@ def make_glossary(schema, src_path=None):
         if obj_desc is None:
             raise ValueError(f"{obj_marker} has no description.")
 
+        if "sense 1" in obj_key:
+            text += f'\n<a name="{obj_marker.split("__", 1)[0]}"></a>'
         text += f'\n<a name="{obj_marker}"></a>'
         text += f"\n## {obj_key}\n\n"
         text += f"**Name**: {obj_def['display_name']}\n\n"
diff --git a/tools/schemacode/src/bidsschematools/render/tsv.py b/tools/schemacode/src/bidsschematools/render/tsv.py
@@ -7,7 +7,12 @@
 from markdown_it import MarkdownIt
 from tabulate import tabulate
 
+from ..utils import filter_warnings, in_context
+from .utils import propagate_fence_exception
 
+
+@in_context(filter_warnings(["error"]))
+@propagate_fence_exception
 def fence(
     source: str,
     language: str,
@@ -27,32 +32,26 @@ def fence(
 
     classes[:0] = ["tsv-table", "index" if linenums else "noindex"]
 
-    try:
-        df = pd.read_csv(
-            io.StringIO(source),
-            sep="\t",
-            dtype=str,
-            index_col=False,
-            keep_default_na=False,
-            header=None if "noheader" in attrs else "infer",
-        )
-        md_table = tabulate(
-            df,  # type: ignore
-            tablefmt="github",
-            showindex=linenums,
-            headers="keys",
-            numalign="right",
-        )
-        html = MarkdownIt("commonmark").enable("table").render(md_table)
-        if "noheader" in attrs:
-            html = re.sub("<thead>.+</thead>", "", html, flags=re.DOTALL)
-
-        html = html.replace("<table>", f'<table class="{" ".join(classes)}">')
-
-        # Remove newlines from HTML to prevent copy-paste from inserting spaces
-        return html.replace("\n", "")
-    except Exception:
-        import traceback
-
-        exc = traceback.format_exc()
-        return f"<pre>{exc}</pre>"
+    df = pd.read_csv(
+        io.StringIO(source),
+        sep="\t",
+        dtype=str,
+        index_col=False,
+        keep_default_na=False,
+        header=None if "noheader" in attrs else "infer",
+    )
+    md_table = tabulate(
+        df,  # type: ignore
+        tablefmt="github",
+        showindex=linenums,
+        headers="keys",
+        numalign="right",
+    )
+    html = MarkdownIt("commonmark").enable("table").render(md_table)
+    if "noheader" in attrs:
+        html = re.sub("<thead>.+</thead>", "", html, flags=re.DOTALL)
+
+    html = html.replace("<table>", f'<table class="{" ".join(classes)}">')
+
+    # Remove newlines from HTML to prevent copy-paste from inserting spaces
+    return html.replace("\n", "")
diff --git a/tools/schemacode/src/bidsschematools/render/utils.py b/tools/schemacode/src/bidsschematools/render/utils.py
@@ -3,6 +3,47 @@
 import math
 import posixpath
 import re
+from functools import cache, wraps
+
+import pandas as pd
+
+from ..utils import in_context
+
+
+def _pandas_3_0():
+    """Silence pandas warnings and opt in to future behavior.
+
+    This sets pandas behavior to 3.0+ defaults.
+    Prior to pandas 3.0, the fillna() and replace() methods would convert
+    object columns to float64 if the resulting series was all float64.
+    In 3.0+, you need to use infer_objects() to do this.
+
+    This also opts-in to copy-on-write, which previously required `copy=False`
+    to be set.
+    """
+    if args := _pandas_3_0_options():
+        return pd.option_context(*args)
+
+    import contextlib
+
+    return contextlib.nullcontext()
+
+
+@cache
+def _pandas_3_0_options():
+    options = [
+        ("future.no_silent_downcasting", True),
+        ("mode.copy_on_write", True),
+    ]
+
+    args = []
+    for option in options:
+        try:
+            pd.get_option(option[0])
+        except KeyError:
+            continue
+        args.extend(option)
+    return args
 
 
 def _link_with_html(string, html_path=None, heading=None, pdf_format=False):
@@ -113,6 +154,7 @@ def combine_extensions(lst, html_path=None, heading_lst=None, pdf_format=True):
     return new_lst
 
 
+@in_context(_pandas_3_0())
 def drop_unused_entities(df):
     """Remove columns from a dataframe where all values in the column are NaNs.
 
@@ -130,8 +172,7 @@ def drop_unused_entities(df):
     df : pandas.DataFrame
         DataFrame with columns associated with unused entities removed.
     """
-    df = df.replace("", math.nan).dropna(axis=1, how="all").fillna("")
-    return df
+    return df.replace("", math.nan).dropna(axis=1, how="all").fillna("")
 
 
 def flatten_multiindexed_columns(df):
@@ -412,3 +453,18 @@ def num2words(integer, to="ordinal"):
         return mapper[integer]
     except KeyError:
         raise ValueError(f"Input {integer} is not supported.")
+
+
+def propagate_fence_exception(func):
+    """Decorator to prevent superfences from swallowing exceptions."""
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            from pymdownx.superfences import SuperFencesException
+
+            raise SuperFencesException from e
+
+    return wrapper
diff --git a/tools/schemacode/src/bidsschematools/utils.py b/tools/schemacode/src/bidsschematools/utils.py
@@ -5,6 +5,9 @@
 import logging
 import os
 import sys
+import warnings
+from contextlib import contextmanager
+from functools import wraps
 
 from . import data
 
@@ -149,3 +152,41 @@ def jsonschema_validator(
     validator_kwargs: ValidatorKwargs
     validator_kwargs = {"format_checker": validator_cls.FORMAT_CHECKER} if check_format else {}
     return validator_cls(schema, **validator_kwargs)  # type: ignore[call-arg]
+
+
+def in_context(context_manager):
+    """Convert a context manager into a function decorator.
+
+    Parameters
+    ----------
+    context_manager : context manager
+        The context manager to use.
+
+    Returns
+    -------
+    Callable
+        The function decorator.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            with context_manager:
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+@contextmanager
+def filter_warnings(*filters):
+    """Context manager to apply warning filters.
+
+    Arguments are lists of positional arguments to :func:`warnings.filterwarnings`.
+    """
+
+    with warnings.catch_warnings():
+        for filt in filters:
+            warnings.filterwarnings(*filt)
+        yield
diff --git a/tools/schemacode/src/bidsschematools/validator.py b/tools/schemacode/src/bidsschematools/validator.py
@@ -495,7 +495,7 @@ def write_report(
     """
 
     report_path = report_path.format(
-        datetime=datetime.datetime.utcnow().strftime(datetime_format),
+        datetime=datetime.datetime.now(datetime.timezone.utc).strftime(datetime_format),
         pid=os.getpid(),
     )
     report_path = os.path.abspath(os.path.expanduser(report_path))
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,7 @@ render = [`
`43`	`43`	`"tabulate",`
`44`	`44`	`"pandas",`
`45`	`45`	`"markdown-it-py",`
	`46`	`+ "pymdown-extensions>=9.2",`
`46`	`47`	`]`
`47`	`48`	`tests = [`
`48`	`49`	`"bidsschematools[validation,render,expressions]",`