docs(python): declare and enforce 64-bit-only Python support (#576)

CONTRIBUTING.md

@@ -15,7 +15,8 @@ By participating, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md
 > **Linux** is the recommended environment for development and performance benchmarking.
 
 ### Prerequisites
-- Python 3.10 - 3.14
+
+- Python 3.10 - 3.14 (64-bit only)
 - CMake ≥ 3.26, < 4.0 (`cmake --version`)
 - A C++17-compatible compiler (e.g., `g++-11+`, `clang++`, Apple Clang on macOS)
 

README_CN.md

@@ -59,7 +59,7 @@
 
 Zvec 提供多语言官方 SDK：
 
-- **[Python](https://pypi.org/project/zvec/)**：`pip install zvec`（需 Python 3.10–3.14）
+- **[Python](https://pypi.org/project/zvec/)**：`pip install zvec`（需 64 位 Python 3.10–3.14）
 - **[Node.js](https://www.npmjs.com/package/@zvec/zvec)**：`npm install @zvec/zvec`
 - **[Go](https://github.com/zvec-ai/zvec-go)**：高性能的 Go 绑定。
 - **[Rust](https://github.com/zvec-ai/zvec-rust)**：高性能的 Rust 绑定。

pyproject.toml

@@ -13,7 +13,7 @@ authors = [
 maintainers = [
     { name = "Zvec Core Team", email = "zvec@alibaba-inc.com" },
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.9" # NOTE: Only 64-bit Python interpreters are supported. 
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

python/zvec/__init__.py

@@ -20,6 +20,15 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from importlib.metadata import PackageNotFoundError
 
+# zvec ships a native C++ extension that is only built and tested for 64-bit
+# CPython. A 32-bit interpreter would fail to load the extension with an
+# obscure error, so fail fast here with an actionable message.
+if sys.maxsize <= 2**32:
+    raise ImportError(
+        "zvec requires a 64-bit Python interpreter; "
+        "the current interpreter is 32-bit and is not supported."
+    )
+
 
 # Register the wheel-bundled jieba dict dir so `import zvec` alone makes
 # the jieba FTS tokenizer usable. Users can still override via