fix(python): correct the asof and reader input annotations

[jonasdedden]

Two annotation bugs on the optional-dependency inputs. Each was hiding a runtime bug.

asof

ts_types was Union[datetime, pd.Timestamp, str], and was defined twice. The stubs pandas ships type Timestamp.__new__ as Self | NaTType, so this failed under mypy --strict and basedpyright:

lance.dataset(uri, asof=pd.Timestamp("2026-01-01"))

• Put NaTType in the union and drop pd.Timestamp, which datetime already covers. One definition, in lance.util.
• NaT is a datetime subclass, so it used to walk straight through sanitize_ts and then compare false against every version. You got "earlier than the first version". Now it is rejected up front.
• The pandas branch for strings was guarded by _check_for_pandas(ts), which reads the argument's MRO and so is always false for a str. It never ran. asof="2026-01-01" told you to install pandas when pandas was installed. Now guarded by _PANDAS_AVAILABLE.

Reader inputs

ReaderLike had pd.Timestamp where a dataframe belongs, and reached Arrow through pa.dataset.Dataset. Type checkers cannot resolve that, and a union with an unresolved member accepts anything, so nobody noticed since #3021. The union had also fallen behind _coerce_reader.

• List what _coerce_reader actually takes: pandas and Polars frames, Arrow table, batch, reader, dataset and scanner, HuggingFace datasets, column dicts, row dicts, Pydantic models, batch iterables. Import the Arrow classes directly.
• Dispatch Polars with _check_for_polars and a real isinstance instead of matching on __module__, so the branch narrows.
• Import LanceDataset inside the function. lance.dataset is both a module and a function, and the module-level form resolves to the function.
• Update the write_dataset docstring, and add the dict and row-dict cases to test_input_data.

Checks

uv run make lint-python is clean and 247 tests pass. Downstream with pandas-stubs and pyarrow-stubs, all 12 input shapes are accepted and object() is rejected for both data_obj and asof. asof is also checked against the stubs pandas ships, which disagree with pandas-stubs here.

The new typing test skips pytest, like test_fragment_typing.py, because the lint job installs pyright without the test dependencies.

Left for later

types.py is still not in the pyright target. Without pyarrow-stubs, isinstance(x, pa.Table) does not narrow and every branch of _coerce_reader errors. Adding the stubs and clearing what they turn up is its own PR. Until then CI cannot check ReaderLike, and only the asof cases are pinned in both directions.

A union that names optional dependencies only checks anything when the checker can resolve all of them. Miss one and it goes back to accepting anything. No false errors, but no checking. That is already the case for reader inputs today.

[lance-gatekeeper]

⚠️ Gate recommendation: approve with a non-blocking risk.

The timestamp contract and expanded reader union remain sound after the rebase. Relocating the runtime rejection assertions into the dataset suite keeps the typing target independent of pytest while preserving the exercised behavior.

A bounded typing risk remains: the repository's Pyright environment lacks PyArrow stubs, so the positive ReaderLike cases cannot reject invalid inputs, and Mapping/Sequence are broader than the concrete dict/list branches. Adding resolvable Arrow stubs and tightening those container shapes would make the regression contract enforceable.