match_sdata_to_table / filter_by_table_query crash for how='left_exclusive' and how='right_exclusive' #1227

Summary

left_exclusive returns table=None by design and right_exclusive returns None elements; match_sdata_to_table then fails with AttributeError: 'NoneType' object has no attribute 'obs' and TypeError: Unsupported type <class 'NoneType'> respectively.

Severity (agent's assessment): medium — both values are documented as valid for how

Where: src/spatialdata/_core/query/relational_query.py::match_sdata_to_table (unconditional TableModel.parse(filtered_table, ...), init_from_elements receives None elements)

Expected behaviour

Either a SpatialData with the exclusive elements and no table (left_exclusive) / the exclusive table and no elements (right_exclusive), or a clear ValueError and removal of the two values from the Literal type and docstring.

Reproduction

Save as repro.py and run uv run repro.py (the PEP 723 header pins spatialdata to the commit the bug was found on; replace the URL fragment with @main to test the current main branch).

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "spatialdata @ git+https://github.com/scverse/spatialdata.git@ccf1ea048d054b6624214bf618008a9f9ae223e0",
# ]
# ///
"""match_sdata_to_table / filter_by_table_query crash for how='left_exclusive' and how='right_exclusive'."""
import warnings
import numpy as np
import pandas as pd
import geopandas as gpd
from anndata import AnnData
from shapely.geometry import Point
from spatialdata import SpatialData, match_sdata_to_table
from spatialdata.models import ShapesModel, TableModel

warnings.simplefilter("ignore")
shapes = ShapesModel.parse(gpd.GeoDataFrame({"geometry": [Point(0, 0), Point(1, 1)], "radius": [1.0, 1.0]}, index=[0, 1]))
obs = pd.DataFrame({"region": pd.Categorical(["shp"] * 2), "instance_id": [0, 5]})
table = TableModel.parse(AnnData(X=np.zeros((2, 1)), obs=obs), region="shp", region_key="region", instance_key="instance_id")
sdata = SpatialData(shapes={"shp": shapes}, tables={"t": table})
bug = False
for how in ["left", "left_exclusive", "inner", "right", "right_exclusive"]:
    try:
        out = match_sdata_to_table(sdata, table_name="t", how=how)
        print(f"how={how:15s}: OK -> shapes {list(out.shapes)}, tables {list(out.tables)}")
    except Exception as e:  # noqa: BLE001
        print(f"how={how:15s}: {type(e).__name__}: {str(e)[:90]}")
        bug = True
print("VERDICT:", "BUG REPRODUCED" if bug else "NOT REPRODUCED")

Observed output

how=left           : OK -> shapes ['shp'], tables ['t']
how=left_exclusive : AttributeError: 'NoneType' object has no attribute 'obs'
how=inner          : OK -> shapes ['shp'], tables ['t']
how=right          : OK -> shapes ['shp'], tables ['t']
how=right_exclusive: TypeError: Unsupported type <class 'NoneType'>
VERDICT: BUG REPRODUCED

Possible fix direction (unverified)

Handle None table/elements in match_sdata_to_table (skip TableModel.parse, drop None elements before init_from_elements).

Environment

uv run repro.py with the PEP 723 metadata in the script (fresh, isolated environment; spatialdata built from main @ ccf1ea0 (2026-08-28); Python 3.13, latest releases of the dependencies at run time: pandas 3.0, anndata 0.13, zarr 3.3, dask 2026.8, numpy 2.5, geopandas 1.1, shapely 2.1). macOS (arm64). Also reproduced in a second environment with pandas 2.3.3 / anndata 0.12.11 / numpy 2.4.4 / zarr 3.2.1.

Automatically generated; discovered by an AI agent (Claude) and not yet reviewed by a human.