fix(python): preserve pylance distribution variant

<!-- lance-gatekeeper-fix:v1 agent=5c80c44c083b3b8ad0da595419d468fc
generation=1 -->

## Root cause

The legacy synchronous Python table called `delete` on a shared, mutable
`lance.Dataset`. Concurrent table operations could hold a PyO3 borrow
while delete requested an exclusive borrow, producing `RuntimeError:
Already borrowed`. The current async-backed binding fixes this by
cloning its thread-safe Rust table handle before awaiting, but that
concurrency contract had no regression coverage.

## Fix

- Document why delete must clone the Rust table handle before entering
its async future.
- Add a barrier-synchronized regression test that deletes distinct rows
through one shared table from eight Python threads.
- Verify every delete commits exactly one row, every commit gets a
distinct version, and no rows remain.

## Validation

- `cargo check --quiet --features remote --tests --examples`
- `cargo fmt --all -- --check`
- `uv run --extra tests --extra dev ruff format --check
python/tests/test_table.py`
- `uv run --extra tests --extra dev ruff check
python/tests/test_table.py`
- `uv run --extra tests --extra dev pytest
python/tests/test_table.py::test_concurrent_deletes_are_thread_safe
python/tests/test_table.py::test_delete
python/tests/test_table.py::test_delete_expr
python/tests/test_table.py::test_delete_expr_async -q` (4 passed)
- Manual stress reproduction: 100 concurrent deletes on one table
completed at versions 2–101 with zero rows remaining.

Fixes #530

Co-authored-by: Gatefixer <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>

docs/src/python/python.md

@@ -17,6 +17,25 @@ The general flow of using the API is:
 pip install lancedb
 ```
 
+The core package does not require PyLance. When you need access to the underlying
+Lance dataset or GPU-accelerated indexing, add the `pylance` extra to the
+distribution you already installed.
+
+For the standard distribution:
+
+```shell
+pip install "lancedb[pylance]"
+```
+
+For the pre-Haswell compatibility distribution:
+
+```shell
+pip install "lancedb-compat[pylance]"
+```
+
+Use only the extra matching your installed distribution. Do not install both
+distributions because they share the `lancedb` namespace.
+
 The following methods describe the synchronous API client. There
 is also an [asynchronous API client](#connections-asynchronous).
 

python/README.md

@@ -8,6 +8,25 @@ A Python library for [LanceDB](https://github.com/lancedb/lancedb).
 pip install lancedb
 ```
 
+The core package does not require PyLance. When you need access to the underlying
+Lance dataset or GPU-accelerated indexing, add the `pylance` extra to the
+distribution you already installed.
+
+For the standard distribution:
+
+```bash
+pip install "lancedb[pylance]"
+```
+
+For the pre-Haswell compatibility distribution:
+
+```bash
+pip install "lancedb-compat[pylance]"
+```
+
+Use only the extra matching your installed distribution. Do not install both
+distributions because they share the `lancedb` namespace.
+
 ### Pre-Haswell x86_64 hosts: `lancedb-compat`
 
 The default `lancedb` wheel targets `x86-64-haswell` (AVX2 + FMA + F16C) for full performance on modern hardware. Pre-Haswell hosts — Intel Sandy Bridge / Ivy Bridge / Westmere; AMD Bulldozer / Piledriver / Steamroller — don't have AVX2 and crash with `Illegal instruction` at `import lancedb`.

python/python/lancedb/db.py

@@ -707,6 +707,9 @@ class LanceDBConnection(DBConnection):
         self._namespace_client_properties = namespace_client_properties
         if _inner is not None:
             self._conn = _inner
+            # Native-derived wrappers resolve this in their async reconstruction
+            # path so construction never synchronously re-enters LOOP.
+            self._read_consistency_interval = read_consistency_interval
             self._cached_namespace_client = None
             return
 
@@ -756,11 +759,14 @@ class LanceDBConnection(DBConnection):
         # storage_options.  Also, this class really shouldn't be holding any state
         # beyond _conn.
         self._conn = AsyncConnection(LOOP.run(do_connect()))
+        # Keep property access synchronous so debugger introspection cannot wait on
+        # the background loop while that thread is suspended at a breakpoint.
+        self._read_consistency_interval = read_consistency_interval
         self._cached_namespace_client: Optional[LanceNamespace] = None
 
     @property
     def read_consistency_interval(self) -> Optional[timedelta]:
-        return LOOP.run(self._conn.get_read_consistency_interval())
+        return self._read_consistency_interval
 
     @property
     def session(self) -> Optional[Session]:
@@ -771,8 +777,16 @@ class LanceDBConnection(DBConnection):
         return self._conn.uri
 
     @classmethod
-    def from_inner(cls, inner: LanceDbConnection):
-        return cls(None, _inner=inner)
+    def from_inner(
+        cls,
+        inner: LanceDbConnection,
+        read_consistency_interval: Optional[timedelta],
+    ):
+        return cls(
+            None,
+            read_consistency_interval=read_consistency_interval,
+            _inner=inner,
+        )
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(uri={self._conn.uri!r})"

python/python/lancedb/permutation.py

@@ -226,7 +226,7 @@ class PermutationBuilder:
 
         async def do_execute():
             inner_tbl = await self._async.execute()
-            return LanceTable.from_inner(inner_tbl)
+            return await LanceTable.from_inner(inner_tbl)
 
         return LOOP.run(do_execute())
 

python/python/lancedb/table.py

@@ -117,6 +117,14 @@ _MODEL_BACKED_TOKENIZER_ERRORS = (
     "Failed to initialize default tokenizer",
 )
 
+_PYLANCE_INSTALL_ERROR = (
+    "The lance library is required to use this function. Install the PyLance "
+    "extra for the distribution already installed: "
+    '`pip install "lancedb[pylance]"` for `lancedb`, or '
+    '`pip install "lancedb-compat[pylance]"` for `lancedb-compat`. '
+    "Do not install both distributions because they share the `lancedb` namespace."
+)
+
 
 def _add_unique_note(exception: BaseException, note: str) -> None:
     existing_notes = getattr(exception, "__notes__", ()) or ()
@@ -2182,11 +2190,15 @@ class LanceTable(Table):
         return self.name
 
     @classmethod
-    def from_inner(cls, tbl: LanceDBTable):
-        from .db import LanceDBConnection
+    async def from_inner(cls, tbl: LanceDBTable):
+        from .db import AsyncConnection, LanceDBConnection
 
         async_tbl = AsyncTable(tbl)
-        conn = LanceDBConnection.from_inner(tbl.database())
+        inner_conn = tbl.database()
+        read_consistency_interval = await AsyncConnection(
+            inner_conn
+        ).get_read_consistency_interval()
+        conn = LanceDBConnection.from_inner(inner_conn, read_consistency_interval)
         return cls(
             conn,
             async_tbl.name,
@@ -2245,10 +2257,7 @@ class LanceTable(Table):
         try:
             import lance
         except ImportError:
-            raise ImportError(
-                "The lance library is required to use this function. "
-                "Please install with `pip install pylance`."
-            )
+            raise ImportError(_PYLANCE_INSTALL_ERROR)
 
         branch = self.current_branch()
         version = None if branch is not None else self.version
@@ -4753,10 +4762,7 @@ class AsyncTable:
         try:
             import lance
         except ImportError:
-            raise ImportError(
-                "The lance library is required to use this function. "
-                "Please install with `pip install pylance`."
-            )
+            raise ImportError(_PYLANCE_INSTALL_ERROR)
 
         # lance.dataset() can't open a branch directly, so open the base table
         # and check out the branch ref (a None branch resolves to main).

python/python/tests/test_db.py

@@ -77,6 +77,23 @@ def test_sync_repr_does_not_use_background_loop(tmp_path, monkeypatch):
     assert repr(table) == f"LanceTable(name='test', _conn={db!r})"
 
 
+def test_read_consistency_interval_does_not_use_background_loop(tmp_path, monkeypatch):
+    from lancedb.background_loop import LOOP
+    from lancedb.db import LanceDBConnection
+
+    consistency_interval = timedelta(seconds=5)
+    db = lancedb.connect(tmp_path, read_consistency_interval=consistency_interval)
+    db_from_inner = LanceDBConnection.from_inner(db._inner, consistency_interval)
+
+    def fail_run(*args, **kwargs):
+        raise AssertionError("properties should not use the Python background loop")
+
+    monkeypatch.setattr(LOOP, "run", fail_run)
+
+    assert db.read_consistency_interval == consistency_interval
+    assert db_from_inner.read_consistency_interval == consistency_interval
+
+
 def test_ingest_pd(tmp_path):
     db = lancedb.connect(tmp_path)
 

python/python/tests/test_import.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import subprocess
+import sys
+
+
+def test_import_lancedb_without_pylance():
+    script = """
+import sys
+
+
+class BlockLanceImports:
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname == "lance" or fullname.startswith("lance."):
+            raise ModuleNotFoundError(f"blocked optional dependency: {fullname}")
+        return None
+
+
+sys.meta_path.insert(0, BlockLanceImports())
+import lancedb
+"""
+
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, result.stderr

python/python/tests/test_permutation.py

@@ -6,6 +6,7 @@ import math
 import pytest
 
 from lancedb import DBConnection, Table, connect
+from lancedb.background_loop import LOOP
 from lancedb.permutation import Permutation, Permutations, permutation_builder
 
 
@@ -31,6 +32,25 @@ def test_split_random_ratios(mem_db):
     assert 65 <= split_1_count <= 75  # ~70% ± tolerance
 
 
+def test_execute_does_not_reenter_background_loop(tmp_path, monkeypatch):
+    import threading
+
+    db = connect(tmp_path)
+    tbl = db.create_table("test_table", pa.table({"x": range(10)}))
+    original_run = LOOP.run
+
+    def fail_on_reentry(future):
+        assert threading.current_thread() is not LOOP.thread
+        return original_run(future)
+
+    monkeypatch.setattr(LOOP, "run", fail_on_reentry)
+
+    permutation_tbl = permutation_builder(tbl).execute()
+
+    assert permutation_tbl.count_rows() == 10
+    assert permutation_tbl._conn.read_consistency_interval is None
+
+
 def test_split_random_counts(mem_db):
     """Test random splitting with absolute counts."""
     tbl = mem_db.create_table(

python/python/tests/test_table.py

@@ -6,6 +6,7 @@ import os
 import sys
 import threading
 import warnings
+from concurrent.futures import ThreadPoolExecutor
 from datetime import date, datetime, timedelta
 from time import sleep
 from typing import List
@@ -1257,6 +1258,24 @@ def test_branch_to_lance_targets_branch(tmp_path):
     assert table.to_lance().count_rows() == 1
 
 
+def _assert_pylance_install_error(error: ImportError):
+    message = str(error)
+    assert 'pip install "lancedb[pylance]"' in message
+    assert 'pip install "lancedb-compat[pylance]"' in message
+    assert "distribution already installed" in message
+    assert "Do not install both distributions" in message
+
+
+def test_to_lance_recommends_pylance_extra(tmp_db):
+    table = tmp_db.create_table("t", [{"i": 1}])
+
+    with patch("builtins.__import__", side_effect=ImportError):
+        with pytest.raises(ImportError) as exc_info:
+            table.to_lance()
+
+    _assert_pylance_install_error(exc_info.value)
+
+
 @pytest.mark.asyncio
 async def test_async_to_lance(tmp_path):
     pytest.importorskip("lance")
@@ -1268,6 +1287,18 @@ async def test_async_to_lance(tmp_path):
     assert dataset.count_rows() == 1
 
 
+@pytest.mark.asyncio
+async def test_async_to_lance_recommends_pylance_extra(tmp_path):
+    db = await lancedb.connect_async(tmp_path)
+    table = await db.create_table("t", [{"i": 1}])
+
+    with patch("builtins.__import__", side_effect=ImportError):
+        with pytest.raises(ImportError) as exc_info:
+            await table.to_lance()
+
+    _assert_pylance_install_error(exc_info.value)
+
+
 @pytest.mark.asyncio
 async def test_async_branch_to_lance_targets_branch(tmp_path):
     pytest.importorskip("lance")
@@ -2124,6 +2155,27 @@ def test_delete(mem_db: DBConnection):
     assert table.to_arrow()["id"].to_pylist() == [1]
 
 
+def test_concurrent_deletes_are_thread_safe(mem_db: DBConnection):
+    num_workers = 8
+    table = mem_db.create_table(
+        "my_table", data=[{"id": row_id} for row_id in range(num_workers)]
+    )
+    barrier = threading.Barrier(num_workers)
+
+    def delete(row_id: int):
+        barrier.wait()
+        return table.delete(f"id = {row_id}")
+
+    with ThreadPoolExecutor(max_workers=num_workers) as pool:
+        results = list(pool.map(delete, range(num_workers)))
+
+    assert all(result.num_deleted_rows == 1 for result in results)
+    assert sorted(result.version for result in results) == list(
+        range(2, num_workers + 2)
+    )
+    assert table.count_rows() == 0
+
+
 def test_delete_expr(mem_db: DBConnection):
     table = mem_db.create_table(
         "my_table",

python/src/table.rs

@@ -745,6 +745,9 @@ impl Table {
 
     #[allow(private_interfaces)]
     pub fn delete(self_: PyRef<'_, Self>, condition: PredicateArg) -> PyResult<Bound<'_, PyAny>> {
+        // Do not hold the Python borrow across the await.  The cloned Rust table
+        // handle is thread-safe and allows deletes on the same Python table to
+        // run concurrently without PyO3 reporting "Already borrowed".
         let inner = self_.inner_ref()?.clone();
         future_into_py(self_.py(), async move {
             let result = match &condition {