a3s-code 8.0.1__tar.gz → 8.0.3__tar.gz

a3s_code-8.0.3/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: a3s-code
+Version: 8.0.3
+Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
+Author: A3S Lab
+License: MIT
+Project-URL: Homepage, https://github.com/A3S-Lab/Code
+Project-URL: Repository, https://github.com/A3S-Lab/Code
+Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# a3s-code (Python bootstrap)
+
+`pip install a3s-code` ships this small pure-Python package. On first
+`import a3s_code` it downloads the native extension matching your
+platform from the project's
+[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
+the wheel's sha256 against the release manifest, extracts the compiled
+extension into a per-user cache, and exposes the normal `a3s_code` API.
+
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
+
+## Why
+
+PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
+~17 MB native wheels per Python × platform tripped that limit. GitHub
+Releases is the canonical wheel host; this bootstrap keeps
+`pip install a3s-code` working without dragging the native wheels back
+through PyPI.
+
+## Supported platforms
+
+- macOS arm64 (Apple Silicon, macOS 11+)
+- macOS x86_64 (Intel, macOS 12+)
+- Linux x86_64 (glibc 2.28+)
+- Windows x86_64
+
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
+
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
+
+## Environment overrides
+
+| Variable | Effect |
+|---|---|
+| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
+| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
+| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
+
+## Manual install
+
+If you do not want the bootstrap to phone home, install the native
+wheel directly:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
+```
+
+For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
+```
+
+Replace `<VERSION>` with the release to install. The Intel asset is available
+from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

a3s_code-8.0.3/README.md

@@ -0,0 +1,78 @@
+# a3s-code (Python bootstrap)
+
+`pip install a3s-code` ships this small pure-Python package. On first
+`import a3s_code` it downloads the native extension matching your
+platform from the project's
+[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
+the wheel's sha256 against the release manifest, extracts the compiled
+extension into a per-user cache, and exposes the normal `a3s_code` API.
+
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
+
+## Why
+
+PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
+~17 MB native wheels per Python × platform tripped that limit. GitHub
+Releases is the canonical wheel host; this bootstrap keeps
+`pip install a3s-code` working without dragging the native wheels back
+through PyPI.
+
+## Supported platforms
+
+- macOS arm64 (Apple Silicon, macOS 11+)
+- macOS x86_64 (Intel, macOS 12+)
+- Linux x86_64 (glibc 2.28+)
+- Windows x86_64
+
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
+
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
+
+## Environment overrides
+
+| Variable | Effect |
+|---|---|
+| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
+| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
+| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
+
+## Manual install
+
+If you do not want the bootstrap to phone home, install the native
+wheel directly:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
+```
+
+For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
+```
+
+Replace `<VERSION>` with the release to install. The Intel asset is available
+from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

{a3s_code-8.0.1 → a3s_code-8.0.3}/pyproject.toml

@@ -7,7 +7,7 @@ name = "a3s-code"
 # Keep in sync with crates/code core release. The bootstrap loader fetches
 # the matching native wheel from `https://github.com/A3S-Lab/Code/releases/tag/v<version>`
 # at import time.
-version = "8.0.1"
+version = "8.0.3"
 description = "A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases"
 readme = "README.md"
 license = {text = "MIT"}
@@ -18,6 +18,11 @@ authors = [
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Topic :: Software Development",

{a3s_code-8.0.1 → a3s_code-8.0.3}/src/a3s_code/__init__.py

@@ -10,9 +10,8 @@ from . import _bootstrap as _bootstrap
 
 _bootstrap.ensure_native_loaded()
 
-# Re-import after the cache dir is on sys.path. The bootstrap extracted
-# `_native.<abi>.so` into a per-version cache; Python's import machinery
-# picks it up from there.
+# The bootstrap extracted `_native.<abi>.so` into a per-version cache and
+# registered it explicitly as `a3s_code._native` before returning.
 from ._native import *  # noqa: E402,F401,F403
 
 __version__ = _bootstrap.__version__

{a3s_code-8.0.1 → a3s_code-8.0.3}/src/a3s_code/_bootstrap.py

@@ -1,12 +1,12 @@
 """Lazy loader for the a3s-code native extension.
 
 This module is part of the pure-Python bootstrap published to PyPI under
-the `a3s-code` name. On first import it resolves the matching native
-wheel for the current interpreter/platform, downloads it from the
-project's GitHub Releases, verifies the wheel's sha256 against the
+the `a3s-code` name. On first import it resolves a compatible native
+wheel for the current platform, downloads it from the project's GitHub
+Releases, verifies the wheel's sha256 against the
 release manifest, extracts the compiled `_native` extension into a
-per-user cache, and prepends the cache to `sys.path` so the rest of
-`a3s_code/__init__.py` can `from ._native import *` normally.
+per-user cache, and registers it explicitly as `a3s_code._native` because it
+lives outside the installed package directory.
 
 Override the cache location via `A3S_CODE_CACHE_DIR`. Override the
 release source via `A3S_CODE_RELEASES_BASE_URL` (default points at the
@@ -31,11 +31,13 @@ from typing import Optional
 
 # Version is the bootstrap's own version, which equals the matching native
 # wheel version on GH Releases. Bumped by the release workflow.
-__version__ = "8.0.1"
+__version__ = "8.0.3"
 
 _DEFAULT_BASE_URL = "https://github.com/A3S-Lab/Code/releases/download"
 _REQUEST_TIMEOUT_S = 120
 _USER_AGENT = f"a3s-code-bootstrap/{__version__}"
+_MIN_PYTHON = (3, 10)
+_ABI3_PYTHON_TAG = "cp310-abi3"
 _LOAD_LOCK = threading.Lock()
 _LOADED = False
 
@@ -44,6 +46,15 @@ class BootstrapError(RuntimeError):
     """Raised when the native extension cannot be located, downloaded, or verified."""
 
 
+class BootstrapHttpError(BootstrapError):
+    """HTTP failure with a status code that callers can safely classify."""
+
+    def __init__(self, url: str, status_code: int):
+        self.url = url
+        self.status_code = status_code
+        super().__init__(f"GET {url} failed: HTTP {status_code}")
+
+
 def _base_url() -> str:
     return os.environ.get("A3S_CODE_RELEASES_BASE_URL", _DEFAULT_BASE_URL).rstrip("/")
 
@@ -51,9 +62,18 @@ def _base_url() -> str:
 def _cache_root() -> Path:
     override = os.environ.get("A3S_CODE_CACHE_DIR")
     if override:
-        return Path(override).expanduser() / __version__
-    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
-    return Path(base) / "a3s-code" / __version__
+        base = Path(override).expanduser() / __version__
+    else:
+        base = (
+            Path(os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache"))
+            / "a3s-code"
+            / __version__
+        )
+    # Keep native binaries for different architectures/OS baselines isolated.
+    # This matters when an Apple Silicon and an Intel interpreter share a home
+    # directory (for example, under Rosetta); a cached arm64 extension must
+    # never be handed to an x86_64 process.
+    return base / _platform_tag()
 
 
 def _platform_tag() -> str:
@@ -68,6 +88,10 @@ def _platform_tag() -> str:
     if sys_plat == "darwin":
         if machine in ("arm64", "aarch64"):
             return "macosx_11_0_arm64"
+        if machine in ("x86_64", "amd64"):
+            # Intel wheels are built with MACOSX_DEPLOYMENT_TARGET=12.0 so
+            # they can run on supported Intel Macs back to macOS 12.
+            return "macosx_12_0_x86_64"
     elif sys_plat == "linux":
         if machine in ("x86_64", "amd64"):
             return "manylinux_2_28_x86_64"
@@ -76,15 +100,56 @@ def _platform_tag() -> str:
             return "win_amd64"
     raise BootstrapError(
         f"a3s-code: no native wheel published for {sys_plat}/{machine}. "
-        "Supported platforms: macOS arm64, Linux x86_64 (glibc 2.28+), Windows x86_64."
+        "Supported platforms: macOS arm64 (11+), macOS Intel (12+), "
+        "Linux x86_64 (glibc 2.28+), Windows x86_64."
     )
 
 
 def _wheel_filename(version: str = __version__) -> str:
+    if platform.python_implementation() != "CPython":
+        raise BootstrapError(
+            "a3s-code publishes native wheels for CPython only; "
+            f"found {platform.python_implementation()}"
+        )
+    if (sys.version_info.major, sys.version_info.minor) < _MIN_PYTHON:
+        raise BootstrapError(
+            "a3s-code requires CPython 3.10 or newer; "
+            f"found {sys.version_info.major}.{sys.version_info.minor}"
+        )
     py_tag = f"cp{sys.version_info.major}{sys.version_info.minor}"
     return f"a3s_code-{version}-{py_tag}-{py_tag}-{_platform_tag()}.whl"
 
 
+def _abi3_wheel_filename(version: str = __version__) -> str:
+    """Return the stable-ABI wheel name used by current releases."""
+    if platform.python_implementation() != "CPython":
+        raise BootstrapError(
+            "a3s-code publishes native wheels for CPython only; "
+            f"found {platform.python_implementation()}"
+        )
+    if (sys.version_info.major, sys.version_info.minor) < _MIN_PYTHON:
+        raise BootstrapError(
+            "a3s-code requires CPython 3.10 or newer; "
+            f"found {sys.version_info.major}.{sys.version_info.minor}"
+        )
+    return f"a3s_code-{version}-{_ABI3_PYTHON_TAG}-{_platform_tag()}.whl"
+
+
+def _wheel_candidates(version: str = __version__) -> tuple[str, ...]:
+    """Return compatible wheel names in migration-safe preference order.
+
+    Existing releases contain one wheel per CPython minor, so Python 3.10–3.13
+    keep using those exact assets first.  New releases publish a single
+    ``cp310-abi3`` wheel; Python 3.14+ prefers that asset and all interpreters
+    fall back to it when an older release has no exact match.
+    """
+    exact = _wheel_filename(version)
+    abi3 = _abi3_wheel_filename(version)
+    if sys.version_info.minor >= 14:
+        return (abi3, exact)
+    return (exact, abi3)
+
+
 def _release_url(filename: str, version: str = __version__) -> str:
     return f"{_base_url()}/v{version}/{filename}"
 
@@ -95,7 +160,7 @@ def _http_get(url: str) -> bytes:
         with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
             return resp.read()
     except urllib.error.HTTPError as exc:
-        raise BootstrapError(f"GET {url} failed: HTTP {exc.code}") from exc
+        raise BootstrapHttpError(url, exc.code) from exc
     except urllib.error.URLError as exc:
         raise BootstrapError(f"GET {url} failed: {exc.reason}") from exc
 
@@ -121,6 +186,27 @@ def _expected_sha256(wheel_name: str, version: str = __version__) -> Optional[st
     return None
 
 
+def _download_wheel(version: str) -> tuple[str, bytes]:
+    """Download the first compatible wheel, retaining old-release fallback."""
+    candidates = _wheel_candidates(version)
+    not_found: list[str] = []
+    for wheel_name in candidates:
+        try:
+            return wheel_name, _http_get(_release_url(wheel_name, version))
+        except BootstrapHttpError as exc:
+            if exc.status_code == 404:
+                not_found.append(wheel_name)
+                continue
+            raise
+
+    tried = ", ".join(not_found)
+    raise BootstrapError(
+        "a3s-code: no compatible native wheel was published for "
+        f"CPython {sys.version_info.major}.{sys.version_info.minor} on "
+        f"{sys.platform}/{platform.machine()}. Tried: {tried}"
+    )
+
+
 def _extract_native(wheel_bytes: bytes, target_dir: Path) -> Path:
     """Extract the compiled `_native.*` extension from `wheel_bytes` into
     `target_dir`. Returns the path to the extracted file.
@@ -144,9 +230,23 @@ def _extract_native(wheel_bytes: bytes, target_dir: Path) -> Path:
 def _find_cached_native(cache_dir: Path) -> Optional[Path]:
     if not cache_dir.is_dir():
         return None
-    for child in cache_dir.iterdir():
-        if child.is_file() and child.name.startswith("_native."):
-            return child
+    exact_tag = f"cp{sys.version_info.major}{sys.version_info.minor}"
+    cpython_tag = f"cpython-{sys.version_info.major}{sys.version_info.minor}"
+    exact: list[Path] = []
+    abi3: list[Path] = []
+    for child in sorted(cache_dir.iterdir()):
+        if not child.is_file() or not child.name.startswith("_native."):
+            continue
+        name = child.name.lower()
+        if f".{exact_tag}" in name or cpython_tag in name:
+            exact.append(child)
+        elif ".abi3." in name or name.endswith(".abi3"):
+            abi3.append(child)
+    # Prefer a native build tied to this interpreter, then the stable ABI.
+    if exact:
+        return exact[0]
+    if abi3:
+        return abi3[0]
     return None
 
 
@@ -188,13 +288,12 @@ def ensure_native_loaded(version: str = __version__) -> Path:
 
         native = _find_cached_native(cache)
         if native is None:
-            wheel_name = _wheel_filename(version)
+            wheel_name, wheel_bytes = _download_wheel(version)
             url = _release_url(wheel_name, version)
             sys.stderr.write(
                 f"a3s-code: fetching native wheel {wheel_name} "
                 f"from {url} (first import only)...\n"
             )
-            wheel_bytes = _http_get(url)
 
             if os.environ.get("A3S_CODE_SKIP_HASH_CHECK") != "1":
                 expected = _expected_sha256(wheel_name, version)

a3s_code-8.0.3/src/a3s_code.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: a3s-code
+Version: 8.0.3
+Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
+Author: A3S Lab
+License: MIT
+Project-URL: Homepage, https://github.com/A3S-Lab/Code
+Project-URL: Repository, https://github.com/A3S-Lab/Code
+Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# a3s-code (Python bootstrap)
+
+`pip install a3s-code` ships this small pure-Python package. On first
+`import a3s_code` it downloads the native extension matching your
+platform from the project's
+[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
+the wheel's sha256 against the release manifest, extracts the compiled
+extension into a per-user cache, and exposes the normal `a3s_code` API.
+
+The v8.0.3 release uses one CPython 3.10 stable-ABI (`cp310-abi3`) wheel per
+platform. That wheel is installable by CPython 3.10, 3.11, 3.12, 3.13, and
+3.14. The published `v8.0.2` assets predate this workflow and still use exact
+CPython 3.10–3.13 wheel names; upgrade the bootstrap to v8.0.3 for Python
+3.14. The loader falls back to the exact per-minor names used by older
+releases, so upgrading the bootstrap does not invalidate an older release
+asset.
+
+Subsequent imports use the cached extension. Cache lives under a
+platform-specific directory, `~/.cache/a3s-code/<version>/<platform-tag>/`
+(or `$A3S_CODE_CACHE_DIR/<version>/<platform-tag>/` when overridden).
+
+## Why
+
+PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
+~17 MB native wheels per Python × platform tripped that limit. GitHub
+Releases is the canonical wheel host; this bootstrap keeps
+`pip install a3s-code` working without dragging the native wheels back
+through PyPI.
+
+## Supported platforms
+
+- macOS arm64 (Apple Silicon, macOS 11+)
+- macOS x86_64 (Intel, macOS 12+)
+- Linux x86_64 (glibc 2.28+)
+- Windows x86_64
+
+CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
+
+The bootstrap itself needs a working pip in the interpreter that runs it. If
+`python3.14 -m pip` reports `No module named pip`, initialize pip and retry:
+
+```bash
+python3.14 -m ensurepip --upgrade
+python3.14 -m pip install --upgrade pip
+python3.14 -m pip install a3s-code
+```
+
+## Environment overrides
+
+| Variable | Effect |
+|---|---|
+| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
+| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
+| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
+
+## Manual install
+
+If you do not want the bootstrap to phone home, install the native
+wheel directly:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-manylinux_2_28_x86_64.whl'
+```
+
+For an Intel Mac on macOS 12 or later, use the `macosx_12_0_x86_64` asset:
+
+```bash
+pip install \
+  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp310-abi3-macosx_12_0_x86_64.whl'
+```
+
+Replace `<VERSION>` with the release to install. The Intel asset is available
+from the first release produced with the Intel build matrix.
+
+The Intel macOS 12 build does not ship the optional local ONNX embedding
+adapter. Keep retrieval model-free or configure an explicitly authorized
+remote embedding provider when using that platform.

{a3s_code-8.0.1 → a3s_code-8.0.3}/tests/test_bootstrap.py

@@ -75,6 +75,61 @@ class WheelFilenameTests(unittest.TestCase):
             "a3s_code-3.2.1-cp311-cp311-macosx_11_0_arm64.whl",
         )
 
+    def test_macos_intel_cp312(self):
+        self.assertEqual(
+            self._filename_for("darwin", "x86_64", 12),
+            "a3s_code-3.2.1-cp312-cp312-macosx_12_0_x86_64.whl",
+        )
+
+    def test_macos_intel_abi3(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)),
+        ):
+            self.assertEqual(
+                _bootstrap._abi3_wheel_filename("3.2.1"),
+                "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+            )
+
+    def test_new_python_prefers_abi3_then_exact_fallback(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)),
+        ):
+            self.assertEqual(
+                _bootstrap._wheel_candidates("3.2.1"),
+                (
+                    "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+                    "a3s_code-3.2.1-cp314-cp314-macosx_12_0_x86_64.whl",
+                ),
+            )
+
+    def test_existing_python_prefers_exact_then_abi3(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 12)),
+        ):
+            self.assertEqual(
+                _bootstrap._wheel_candidates("3.2.1"),
+                (
+                    "a3s_code-3.2.1-cp312-cp312-macosx_12_0_x86_64.whl",
+                    "a3s_code-3.2.1-cp310-abi3-macosx_12_0_x86_64.whl",
+                ),
+            )
+
+    def test_python_below_abi3_floor_raises(self):
+        with (
+            mock.patch.object(sys, "platform", "darwin"),
+            mock.patch.object(_bootstrap.platform, "machine", return_value="x86_64"),
+            mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 9)),
+        ):
+            with self.assertRaises(_bootstrap.BootstrapError) as cm:
+                _bootstrap._wheel_candidates("3.2.1")
+        self.assertIn("CPython 3.10 or newer", str(cm.exception))
+
     def test_windows_amd64_cp313(self):
         self.assertEqual(
             self._filename_for("win32", "AMD64", 13),
@@ -108,18 +163,31 @@ class CacheDirTests(unittest.TestCase):
 
     def test_default_uses_xdg_or_home(self):
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache.parts[-2:], ("a3s-code", _bootstrap.__version__))
+        self.assertEqual(cache.parts[-3:-1], ("a3s-code", _bootstrap.__version__))
+        self.assertEqual(cache.name, _bootstrap._platform_tag())
 
     def test_xdg_cache_home_honored(self):
         os.environ["XDG_CACHE_HOME"] = "/tmp/xdg-test"
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache, Path(f"/tmp/xdg-test/a3s-code/{_bootstrap.__version__}"))
+        self.assertEqual(
+            cache,
+            Path(
+                f"/tmp/xdg-test/a3s-code/{_bootstrap.__version__}/"
+                f"{_bootstrap._platform_tag()}"
+            ),
+        )
 
     def test_explicit_override_wins(self):
         os.environ["XDG_CACHE_HOME"] = "/tmp/xdg-test"
         os.environ["A3S_CODE_CACHE_DIR"] = "/var/a3s-cache"
         cache = _bootstrap._cache_root()
-        self.assertEqual(cache, Path(f"/var/a3s-cache/{_bootstrap.__version__}"))
+        self.assertEqual(
+            cache,
+            Path(
+                f"/var/a3s-cache/{_bootstrap.__version__}/"
+                f"{_bootstrap._platform_tag()}"
+            ),
+        )
 
 
 class ExtractNativeTests(unittest.TestCase):
@@ -141,11 +209,50 @@ class ExtractNativeTests(unittest.TestCase):
                 _bootstrap._extract_native(buf.getvalue(), Path(tmp) / "pkg")
 
 
+class CachedNativeSelectionTests(unittest.TestCase):
+    def test_selects_exact_interpreter_before_abi3(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.abi3.so").write_bytes(b"abi3")
+            (cache / "_native.cpython-312-darwin.so").write_bytes(b"exact")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 12)):
+                selected = _bootstrap._find_cached_native(cache)
+            self.assertIsNotNone(selected)
+            self.assertEqual(selected.name, "_native.cpython-312-darwin.so")
+
+    def test_does_not_reuse_another_python_minor(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.cpython-313-darwin.so").write_bytes(b"wrong")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+                self.assertIsNone(_bootstrap._find_cached_native(cache))
+
+    def test_uses_abi3_when_exact_is_absent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = Path(tmp)
+            (cache / "_native.abi3.so").write_bytes(b"abi3")
+            with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+                selected = _bootstrap._find_cached_native(cache)
+            self.assertIsNotNone(selected)
+            self.assertEqual(selected.name, "_native.abi3.so")
+
+
 class EnsureNativeLoadedTests(unittest.TestCase):
     def setUp(self):
         self._tmp = tempfile.mkdtemp(prefix="a3s-bootstrap-test-")
         self._prev_cache = os.environ.get("A3S_CODE_CACHE_DIR")
         os.environ["A3S_CODE_CACHE_DIR"] = self._tmp
+        # The product intentionally rejects CPython < 3.10.  macOS ships a
+        # system Python 3.9 on some runners, though, and these tests exercise
+        # download/cache behavior rather than the version-floor error path.
+        # Run the fixture under a supported simulated minor in that case so
+        # the suite remains useful when invoked with the system interpreter.
+        self._supported_version_patch = None
+        if (sys.version_info.major, sys.version_info.minor) < _bootstrap._MIN_PYTHON:
+            self._supported_version_patch = mock.patch.object(
+                sys, "version_info", _FakeVersionInfo(3, 12)
+            )
+            self._supported_version_patch.start()
         # Reset the module-level latch so each test starts clean.
         _bootstrap._LOADED = False
 
@@ -154,6 +261,8 @@ class EnsureNativeLoadedTests(unittest.TestCase):
             os.environ.pop("A3S_CODE_CACHE_DIR", None)
         else:
             os.environ["A3S_CODE_CACHE_DIR"] = self._prev_cache
+        if self._supported_version_patch is not None:
+            self._supported_version_patch.stop()
         shutil.rmtree(self._tmp, ignore_errors=True)
         _bootstrap._LOADED = False
 
@@ -166,7 +275,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": expected_sha,
                     }
                 ],
@@ -186,12 +295,15 @@ class EnsureNativeLoadedTests(unittest.TestCase):
         ):
             cache = _bootstrap.ensure_native_loaded("3.2.1")
 
-        # `_cache_root()` keys the cache dir on the module's own __version__,
-        # not the version arg passed to `ensure_native_loaded`. Reference it
-        # directly so this assertion can't go stale on a version bump (the
-        # sibling CacheDirTests follow the same pattern).
-        self.assertEqual(cache, Path(self._tmp) / _bootstrap.__version__)
-        # Native file extracted at cache root, not under a subdirectory.
+        # `_cache_root()` keys the cache dir on the module's own version and
+        # current platform, not the version arg passed to `ensure_native_loaded`.
+        self.assertEqual(
+            cache,
+            Path(self._tmp)
+            / _bootstrap.__version__
+            / _bootstrap._platform_tag(),
+        )
+        # Native file is extracted directly into the platform-scoped cache.
         extracted = list(cache.glob("_native.*"))
         self.assertEqual(len(extracted), 1)
         register_mock.assert_called_once_with(extracted[0])
@@ -203,7 +315,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": "0" * 64,
                     }
                 ],
@@ -230,7 +342,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": "0" * 64,
                     }
                 ],
@@ -259,7 +371,7 @@ class EnsureNativeLoadedTests(unittest.TestCase):
                 "version": "3.2.1",
                 "assets": [
                     {
-                        "filename": _bootstrap._wheel_filename("3.2.1"),
+                        "filename": _bootstrap._wheel_candidates("3.2.1")[0],
                         "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
                     }
                 ],
@@ -284,6 +396,76 @@ class EnsureNativeLoadedTests(unittest.TestCase):
             self.assertEqual(call_count["n"], calls_after_first,
                              "second call must not re-download")
 
+    def test_python314_selects_abi3_wheel(self):
+        wheel_bytes = _make_wheel()
+        with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+            abi3_name = _bootstrap._abi3_wheel_filename("3.2.1")
+            manifest = json.dumps(
+                {
+                    "version": "3.2.1",
+                    "assets": [
+                        {
+                            "filename": abi3_name,
+                            "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
+                        }
+                    ],
+                }
+            ).encode()
+
+            calls: list[str] = []
+
+            def fake_get(url: str) -> bytes:
+                calls.append(url)
+                if url.endswith("python-native-manifest.json"):
+                    return manifest
+                return wheel_bytes
+
+            with (
+                mock.patch.object(_bootstrap, "_http_get", side_effect=fake_get),
+                mock.patch.object(_bootstrap, "_register_native") as register_mock,
+            ):
+                _bootstrap.ensure_native_loaded("3.2.1")
+
+        self.assertIn(abi3_name, calls[0])
+        register_mock.assert_called_once()
+
+    def test_python314_falls_back_to_exact_wheel_on_404(self):
+        wheel_bytes = _make_wheel()
+        with mock.patch.object(sys, "version_info", _FakeVersionInfo(3, 14)):
+            abi3_name = _bootstrap._abi3_wheel_filename("3.2.1")
+            exact_name = _bootstrap._wheel_filename("3.2.1")
+            manifest = json.dumps(
+                {
+                    "version": "3.2.1",
+                    "assets": [
+                        {
+                            "filename": exact_name,
+                            "sha256": hashlib.sha256(wheel_bytes).hexdigest(),
+                        }
+                    ],
+                }
+            ).encode()
+
+            calls: list[str] = []
+
+            def fake_get(url: str) -> bytes:
+                calls.append(url)
+                if url.endswith("python-native-manifest.json"):
+                    return manifest
+                if abi3_name in url:
+                    raise _bootstrap.BootstrapHttpError(url, 404)
+                return wheel_bytes
+
+            with (
+                mock.patch.object(_bootstrap, "_http_get", side_effect=fake_get),
+                mock.patch.object(_bootstrap, "_register_native") as register_mock,
+            ):
+                _bootstrap.ensure_native_loaded("3.2.1")
+
+        self.assertIn(abi3_name, calls[0])
+        self.assertIn(exact_name, calls[1])
+        register_mock.assert_called_once()
+
 
 @unittest.skipUnless(
     os.environ.get("A3S_CODE_BOOTSTRAP_LIVE") == "1",
@@ -291,11 +473,12 @@ class EnsureNativeLoadedTests(unittest.TestCase):
 )
 class LiveDownloadTests(unittest.TestCase):
     def test_live_fetch_v3_2_0(self):
-        # 3.2.0 has 12 wheels on GH Release — pick whichever matches the
-        # current runner's platform/interpreter. Skip if the runner isn't
-        # one of the supported triplets.
+        # 3.2.0 has native wheels on GH Release — pick whichever compatible
+        # asset is available for the current runner. Older releases predate
+        # the stable-ABI migration, so a newer interpreter may legitimately
+        # have no matching asset and should be reported as a skip.
         try:
-            _bootstrap._wheel_filename("3.2.0")
+            _bootstrap._wheel_candidates("3.2.0")
         except _bootstrap.BootstrapError as exc:
             self.skipTest(str(exc))
         tmp = Path(tempfile.mkdtemp(prefix="a3s-live-"))
@@ -303,7 +486,10 @@ class LiveDownloadTests(unittest.TestCase):
             os.environ["A3S_CODE_CACHE_DIR"] = str(tmp)
             _bootstrap._LOADED = False
             with mock.patch.object(_bootstrap, "_register_native"):
-                cache = _bootstrap.ensure_native_loaded("3.2.0")
+                try:
+                    cache = _bootstrap.ensure_native_loaded("3.2.0")
+                except _bootstrap.BootstrapError as exc:
+                    self.skipTest(str(exc))
             self.assertTrue(any(cache.glob("_native.*")))
         finally:
             os.environ.pop("A3S_CODE_CACHE_DIR", None)

a3s_code-8.0.1/PKG-INFO

@@ -1,64 +0,0 @@
-Metadata-Version: 2.4
-Name: a3s-code
-Version: 8.0.1
-Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
-Author: A3S Lab
-License: MIT
-Project-URL: Homepage, https://github.com/A3S-Lab/Code
-Project-URL: Repository, https://github.com/A3S-Lab/Code
-Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: Software Development
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# a3s-code (Python bootstrap)
-
-`pip install a3s-code` ships this small pure-Python package. On first
-`import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
-[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
-the wheel's sha256 against the release manifest, extracts the compiled
-extension into a per-user cache, and exposes the normal `a3s_code` API.
-
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
-
-## Why
-
-PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
-~17 MB native wheels per Python × platform tripped that limit. GitHub
-Releases is the canonical wheel host; this bootstrap keeps
-`pip install a3s-code` working without dragging the native wheels back
-through PyPI.
-
-## Supported platforms
-
-- macOS arm64 (Apple Silicon)
-- Linux x86_64 (glibc 2.28+)
-- Windows x86_64
-
-CPython 3.10, 3.11, 3.12, 3.13.
-
-## Environment overrides
-
-| Variable | Effect |
-|---|---|
-| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
-| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
-| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
-
-## Manual install
-
-If you do not want the bootstrap to phone home, install the native
-wheel directly:
-
-```bash
-pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
-```
-
-Replace `<VERSION>` with the release to install, for example `6.4.0`.

a3s_code-8.0.1/README.md

@@ -1,47 +0,0 @@
-# a3s-code (Python bootstrap)
-
-`pip install a3s-code` ships this small pure-Python package. On first
-`import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
-[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
-the wheel's sha256 against the release manifest, extracts the compiled
-extension into a per-user cache, and exposes the normal `a3s_code` API.
-
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
-
-## Why
-
-PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
-~17 MB native wheels per Python × platform tripped that limit. GitHub
-Releases is the canonical wheel host; this bootstrap keeps
-`pip install a3s-code` working without dragging the native wheels back
-through PyPI.
-
-## Supported platforms
-
-- macOS arm64 (Apple Silicon)
-- Linux x86_64 (glibc 2.28+)
-- Windows x86_64
-
-CPython 3.10, 3.11, 3.12, 3.13.
-
-## Environment overrides
-
-| Variable | Effect |
-|---|---|
-| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
-| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
-| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
-
-## Manual install
-
-If you do not want the bootstrap to phone home, install the native
-wheel directly:
-
-```bash
-pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
-```
-
-Replace `<VERSION>` with the release to install, for example `6.4.0`.

a3s_code-8.0.1/src/a3s_code.egg-info/PKG-INFO

@@ -1,64 +0,0 @@
-Metadata-Version: 2.4
-Name: a3s-code
-Version: 8.0.1
-Summary: A3S Code Python SDK — pure-Python bootstrap that fetches the native wheel from GitHub Releases
-Author: A3S Lab
-License: MIT
-Project-URL: Homepage, https://github.com/A3S-Lab/Code
-Project-URL: Repository, https://github.com/A3S-Lab/Code
-Project-URL: Issues, https://github.com/A3S-Lab/Code/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: Software Development
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# a3s-code (Python bootstrap)
-
-`pip install a3s-code` ships this small pure-Python package. On first
-`import a3s_code` it downloads the native extension matching your
-interpreter and platform from the project's
-[GitHub Releases](https://github.com/A3S-Lab/Code/releases), verifies
-the wheel's sha256 against the release manifest, extracts the compiled
-extension into a per-user cache, and exposes the normal `a3s_code` API.
-
-Subsequent imports use the cached extension. Cache lives under
-`~/.cache/a3s-code/<version>/` (or `$XDG_CACHE_HOME/a3s-code/<version>/`).
-
-## Why
-
-PyPI imposes a default 10 GB per-project storage cap. A Rust SDK with
-~17 MB native wheels per Python × platform tripped that limit. GitHub
-Releases is the canonical wheel host; this bootstrap keeps
-`pip install a3s-code` working without dragging the native wheels back
-through PyPI.
-
-## Supported platforms
-
-- macOS arm64 (Apple Silicon)
-- Linux x86_64 (glibc 2.28+)
-- Windows x86_64
-
-CPython 3.10, 3.11, 3.12, 3.13.
-
-## Environment overrides
-
-| Variable | Effect |
-|---|---|
-| `A3S_CODE_CACHE_DIR` | Cache root (defaults to `$XDG_CACHE_HOME/a3s-code` or `~/.cache/a3s-code`) |
-| `A3S_CODE_RELEASES_BASE_URL` | Override the release base URL — useful for air-gapped mirrors |
-| `A3S_CODE_SKIP_HASH_CHECK` | `1` skips sha256 verification (do not use in production) |
-
-## Manual install
-
-If you do not want the bootstrap to phone home, install the native
-wheel directly:
-
-```bash
-pip install \
-  'https://github.com/A3S-Lab/Code/releases/download/v<VERSION>/a3s_code-<VERSION>-cp312-cp312-manylinux_2_28_x86_64.whl'
-```
-
-Replace `<VERSION>` with the release to install, for example `6.4.0`.