From 600ea78cacaaee1b440c3597aa44b6f0e850d6e6 Mon Sep 17 00:00:00 2001 From: Gatefixer <313497061+lancedb-gatefixer[bot]@users.noreply.github.com> Date: Wed, 5 Aug 2026 23:29:37 +0000 Subject: [PATCH] fix(python): preserve pylance distribution variant --- docs/src/python/python.md | 17 ++++++++++++++--- python/README.md | 17 ++++++++++++++--- python/python/lancedb/table.py | 18 ++++++++++-------- python/python/tests/test_table.py | 16 ++++++++++++++-- 4 files changed, 52 insertions(+), 16 deletions(-) diff --git a/docs/src/python/python.md b/docs/src/python/python.md index 143fe891c..15685e166 100644 --- a/docs/src/python/python.md +++ b/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). diff --git a/python/README.md b/python/README.md index f81e5a5e3..df843206c 100644 --- a/python/README.md +++ b/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`. diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py index 0a8dfd83f..e49a9b942 100644 --- a/python/python/lancedb/table.py +++ b/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). diff --git a/python/python/tests/test_table.py b/python/python/tests/test_table.py index cf24a5d6f..76f6ca40e 100644 --- a/python/python/tests/test_table.py +++ b/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):