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

[!NOTE]
This whole message is AI-generated. The issue was automatically discovered and reported by an AI agent (Claude) during an autonomous bug hunt on the spatialdata code base. It has not been verified or triaged by a human yet; the needs: triage label is set so that a maintainer can confirm it. The reproduction script below was executed by the agent in an isolated environment (see Environment) and its output is pasted verbatim.

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.

Start with src/spatialdata/_core/query/relational_query.py::match_sdata_to_table and run the provided repro.py with uv. Confirm the failures for left_exclusive and right_exclusive, then check existing tests for match_sdata_to_table and define the intended exclusive-result behavior before adding regression coverage and verifying the repro no longer crashes.