fix(python): preserve pylance distribution variant

docs/src/python/python.md

@@ -17,14 +17,25 @@ The general flow of using the API is:
 pip install lancedb
 ```
 
-The core package does not require PyLance. Install LanceDB's optional PyLance
-dependency when you need access to the underlying Lance dataset or
-GPU-accelerated indexing:
+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,14 +8,25 @@ A Python library for [LanceDB](https://github.com/lancedb/lancedb).
 pip install lancedb
 ```
 
-The core package does not require PyLance. Install LanceDB's optional PyLance
-dependency when you need access to the underlying Lance dataset or
-GPU-accelerated indexing:
+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/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 ()
@@ -2249,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 "lancedb[pylance]"`.'
-            )
+            raise ImportError(_PYLANCE_INSTALL_ERROR)
 
         branch = self.current_branch()
         version = None if branch is not None else self.version
@@ -4757,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 "lancedb[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_table.py

@@ -1258,13 +1258,23 @@ 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, match=r"lancedb\[pylance\]"):
+        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):
@@ -1283,9 +1293,11 @@ async def test_async_to_lance_recommends_pylance_extra(tmp_path):
     table = await db.create_table("t", [{"i": 1}])
 
     with patch("builtins.__import__", side_effect=ImportError):
-        with pytest.raises(ImportError, match=r"lancedb\[pylance\]"):
+        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):