feat: add sanity check to make sure Python and engine version consistent (#1323)

Author: georgeh0

.github/scripts/update_version.sh

@@ -20,3 +20,4 @@ fi
 
 # Update Cargo.toml
 sed "${SED_INLINE[@]}" "s/^version = .*/version = \"$VERSION\"/" Cargo.toml
+echo "__version__ = \"$VERSION\"" > python/cocoindex/_version.py

.github/workflows/release.yml

@@ -15,28 +15,13 @@ permissions:
   pages: write
 
 jobs:
-  create-versioned-toml:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-      - run: ./.github/scripts/update_version.sh
-      - uses: actions/upload-artifact@v4
-        with:
-          name: Cargo.toml
-          path: Cargo.toml
-
   generate-3p-notices:
     runs-on: ubuntu-latest
-    needs: [create-versioned-toml]
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - uses: actions/download-artifact@v4
-        with:
-          name: Cargo.toml
+      - run: ./.github/scripts/update_version.sh
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
       - uses: taiki-e/install-action@v2
@@ -54,7 +39,7 @@ jobs:
 
   build:
     runs-on: ${{ matrix.platform.runner }}
-    needs: [create-versioned-toml, generate-3p-notices]
+    needs: [generate-3p-notices]
     strategy:
       matrix:
         platform:
@@ -67,9 +52,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - uses: actions/download-artifact@v4
-        with:
-          name: Cargo.toml
+      - run: ./.github/scripts/update_version.sh
       - uses: actions/download-artifact@v4
         with:
           name: THIRD_PARTY_NOTICES.html
@@ -110,14 +93,12 @@ jobs:
 
   sdist:
     runs-on: ubuntu-latest
-    needs: [create-versioned-toml, generate-3p-notices]
+    needs: [generate-3p-notices]
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - uses: actions/download-artifact@v4
-        with:
-          name: Cargo.toml
+      - run: ./.github/scripts/update_version.sh
       - uses: actions/download-artifact@v4
         with:
           name: THIRD_PARTY_NOTICES.html
@@ -135,7 +116,7 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
-    needs: [create-versioned-toml, build, test-abi3, sdist, generate-3p-notices]
+    needs: [build, test-abi3, sdist, generate-3p-notices]
     permissions:
       # Use to sign the release artifacts
       id-token: write
@@ -148,9 +129,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - uses: actions/download-artifact@v4
-        with:
-          name: Cargo.toml
+      - run: ./.github/scripts/update_version.sh
       - uses: actions/download-artifact@v4
         with:
           name: THIRD_PARTY_NOTICES.html

python/cocoindex/__init__.py

@@ -2,6 +2,10 @@
 Cocoindex is a framework for building and running indexing pipelines.
 """
 
+from ._version import __version__
+
+from . import _version_check
+
 from . import _engine  # type: ignore
 from . import functions, sources, targets, cli, utils
 
@@ -46,6 +50,7 @@
 _engine.init_pyo3_runtime()
 
 __all__ = [
+    "__version__",
     # Submodules
     "_engine",
     "functions",

python/cocoindex/_version.py

@@ -0,0 +1,3 @@
+# This file will be rewritten by the release workflow.
+# DO NOT ADD ANYTHING ELSE TO THIS FILE.
+__version__ = "999.0.0"

python/cocoindex/_version_check.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import sys
+from . import _engine
+from . import __version__
+
+
+def _sanity_check_engine() -> None:
+    engine_file = getattr(_engine, "__file__", "<unknown>")
+    engine_version = getattr(_engine, "__version__", None)
+
+    problems: list[str] = []
+
+    # Version mismatch (if the engine exposes its own version)
+    if engine_version is not None and engine_version != __version__:
+        problems.append(
+            f"Version mismatch: Python package is {__version__!r}, "
+            f"but cocoindex._engine reports {engine_version!r}."
+        )
+
+    if problems:
+        # Helpful diagnostic message for users
+        msg_lines = [
+            "Inconsistent cocoindex installation detected:",
+            *[f"  - {p}" for p in problems],
+            "",
+            f"Python executable: {sys.executable}",
+            f"cocoindex package file: {__file__}",
+            f"cocoindex._engine file: {engine_file}",
+            "",
+            "This usually happens when:",
+            "  * An old 'cocoindex._engine' .pyd is still present in the",
+            "    package directory, or",
+            "  * Multiple 'cocoindex' copies exist on sys.path",
+            "    (e.g. a local checkout + an installed wheel).",
+            "",
+            "Suggested fix:",
+            "  1. Uninstall cocoindex completely:",
+            "       pip uninstall cocoindex",
+            "  2. Reinstall it cleanly:",
+            "       pip install --no-cache-dir cocoindex",
+            "  3. Ensure there is no local 'cocoindex' directory or old",
+            "     .pyd shadowing the installed package.",
+        ]
+        raise RuntimeError("\n".join(msg_lines))
+
+
+_sanity_check_engine()
+del _sanity_check_engine

rust/cocoindex/src/py/mod.rs

@@ -606,6 +606,8 @@ fn seder_roundtrip<'py>(
 #[pymodule]
 #[pyo3(name = "_engine")]
 fn cocoindex_engine(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
+
     m.add_function(wrap_pyfunction!(init_pyo3_runtime, m)?)?;
     m.add_function(wrap_pyfunction!(init, m)?)?;
     m.add_function(wrap_pyfunction!(set_settings_fn, m)?)?;