feat(python): workflow to build and upload the pypi package

Author: Daniele Briggi

.github/workflows/main.yml

@@ -1,4 +1,4 @@
-name: build, test and release sqlite-ai
+name: Build, Test and Release SQLite AI
 on:
   push:
   workflow_dispatch:

.github/workflows/python-package.yml

@@ -0,0 +1,90 @@
+name: Build and Publish Python Package
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to use for the Python package (e.g. 0.5.9)"
+        required: true
+        type: string
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux
+            python-version: "3.10"
+            arch: x86_64
+            plat_name: linux_x86_64
+          - os: ubuntu-latest
+            platform: linux
+            python-version: "3.10"
+            arch: arm64
+            plat_name: linux_aarch64
+          - os: windows-latest
+            platform: windows
+            python-version: "3.10"
+            arch: x86_64
+            plat_name: win_amd64
+          - os: macos-latest
+            platform: macos
+            python-version: "3.10"
+            arch: x86_64
+            plat_name: macosx_10_9_x86_64
+          - os: macos-latest
+            platform: macos
+            python-version: "3.10"
+            arch: arm64
+            plat_name: macosx_11_0_arm64    
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build dependencies
+        run: |
+          cd python-package
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r requirements-dev.txt
+
+      - name: Get version
+        id: get_version
+        run: |
+          if [[ "${{ github.event_name }}" == "release" ]]; then
+            VERSION="${{ github.event.release.tag_name }}"
+          else
+            VERSION="${{ github.event.inputs.version }}"
+          fi
+          VERSION=${VERSION#v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Download artifacts for current platform
+        run: |
+          cd python-package
+          python3 download_artifacts.py "${{ matrix.plat_name }}" "${{ steps.get_version.outputs.version }}"
+
+      - name: Build wheel
+        env:
+          PACKAGE_VERSION: ${{ steps.get_version.outputs.version }}
+        run: |
+          cd python-package
+          python setup.py clean --all bdist_wheel --plat-name "${{ matrix.plat_name }}"
+
+      - name: Publish to PyPI
+        if: github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: python-package/dist

python-package/.gitignore

@@ -0,0 +1,23 @@
+# Build directories
+build/
+dist/
+*.egg-info/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Package files
+*.whl
+*.tar.gz
+
+# Temporary files
+*.tmp
+*.log

python-package/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src/sqliteai/binaries *

python-package/README.md

@@ -0,0 +1,39 @@
+## SQLite AI Python package
+
+This package provides the sqlite-ai extension prebuilt binaries for multiple platforms and architectures.
+
+## Usage
+
+```python
+import importlib.resources
+import sqlite3
+
+# Connect to your SQLite database
+conn = sqlite3.connect("example.db")
+
+# Load the sqlite-ai extension
+# Pip will download the package for your platform/architecture
+ext_path = importlib.resources.files("sqliteai.binaries.cpu") / "ai"
+
+conn.enable_load_extension(True)
+conn.load_extension(str(ext_path))
+conn.enable_load_extension(False)
+
+
+# Now you can use sqlite-ai features in your SQL queries
+```
+
+
+### Extension paths
+
+The sqlite-ai extension binary is included in a subpackage based on your platform and architecture.
+Use the following subpackage names to locate the extension:
+
+| Platform      | Arch         | Subpackage name         | Binary name |
+| ------------- | ------------ | ----------------------- | ----------- |
+| Linux (CPU)   | x86_64/arm64 | sqliteai.binaries.cpu   | ai.so       |
+| Linux (GPU)   | x86_64/arm64 | sqliteai.binaries.gpu   | ai.so       |
+| Windows (CPU) | x86_64       | sqliteai.binaries.cpu   | ai.dll      |
+| Windows (GPU) | x86_64       | sqliteai.binaries.gpu   | ai.dll      |
+| macOS (CPU)   | x86_64/arm64 | sqliteai.binaries.cpu   | ai.dylib    |
+

python-package/download_artifacts.py

@@ -0,0 +1,99 @@
+import sys
+import zipfile
+import requests
+from pathlib import Path
+import shutil
+
+
+# == USAGE ==
+# python3 download_artifacts.py PLATFORM VERSION
+#   eg: python3 download_artifacts.py linux_x86_64 "0.5.9"
+
+REPO = "sqliteai/sqlite-ai"
+RELEASE_URL = f"https://github.com/{REPO}/releases/download"
+
+# Map Python plat_name to artifact names
+ARTIFACTS = {
+    "linux_x86_64": ["ai-linux-cpu-x86_64", "ai-linux-gpu-x86_64"],
+    "linux_aarch64": [
+        "ai-linux-cpu-arm64",
+        "ai-linux-gpu-arm64",
+    ],
+    "win_amd64": ["ai-windows-cpu-x86_64", "ai-windows-gpu-x86_64"],
+    "macosx_10_9_x86_64": ["ai-macos"],
+    "macosx_11_0_arm64": ["ai-macos"],
+}
+
+BINARY_NAME = {
+    "linux_x86_64": "ai.so",
+    "linux_aarch64": "ai.so",
+    "win_amd64": "ai.dll",
+    "macosx_10_9_x86_64": "ai.dylib",
+    "macosx_11_0_arm64": "ai.dylib",
+}
+
+BINARIES_DIR = Path(__file__).parent / "src/sqliteai/binaries"
+
+
+def download_and_extract(artifact_name, bin_name, version):
+    artifact = f"{artifact_name}-{version}.zip"
+    url = f"{RELEASE_URL}/{version}/{artifact}"
+    print(f"Downloading {url}")
+
+    r = requests.get(url)
+    if r.status_code != 200:
+        print(f"Failed to download {artifact}: {r.status_code}")
+        sys.exit(1)
+
+    zip_path = BINARIES_DIR / artifact
+    with open(zip_path, "wb") as f:
+        f.write(r.content)
+
+    subdir = "gpu" if "gpu" in artifact_name else "cpu"
+    out_dir = BINARIES_DIR / subdir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(zip_path, "r") as zip_ref:
+        for member in zip_ref.namelist():
+            if member.endswith(bin_name):
+                zip_ref.extract(member, out_dir)
+
+                # Move to expected name/location
+                src = out_dir / member
+                dst = out_dir / bin_name
+                src.rename(dst)
+
+                print(f"Extracted {dst}")
+
+    zip_path.unlink()
+
+
+def main():
+    version = None
+    platform = None
+    if len(sys.argv) > 2:
+        platform = sys.argv[1].lower()
+        version = sys.argv[2]
+
+    if not version or not platform:
+        print(
+            'Error: Version is not specified.\nUsage: \n   python3 download_artifacts.py linux_x86_64 "0.5.9"'
+        )
+        sys.exit(1)
+
+    print(BINARIES_DIR)
+    if BINARIES_DIR.exists():
+        shutil.rmtree(BINARIES_DIR)
+    BINARIES_DIR.mkdir(parents=True, exist_ok=True)
+
+    platform_artifacts = ARTIFACTS.get(platform, [])
+    if not platform_artifacts:
+        print(f"Error: Unknown platform '{platform}'")
+        sys.exit(1)
+
+    for artifact_name in platform_artifacts:
+        download_and_extract(artifact_name, BINARY_NAME[platform], version)
+
+
+if __name__ == "__main__":
+    main()

python-package/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "toml"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlite-ai"
+dynamic = ["version"]
+description = "Python bindings and prebuilt binaries for SQLite AI extension."
+authors = [
+    { name = "SQLite AI Team" }
+]
+readme = "README.md"
+requires-python = ">=3"
+classifiers = []
+
+[project.urls]
+Homepage = "https://sqlite.ai"
+Documentation = "https://github.com/sqliteai/sqlite-ai/blob/main/API.md"
+Repository = "https://github.com/sqliteai/sqlite-ai"
+Issues = "https://github.com/sqliteai/sqlite-ai/issues"

python-package/requirements-dev.txt

@@ -0,0 +1,2 @@
+requests
+toml

python-package/setup.py

@@ -0,0 +1,73 @@
+import setuptools
+import toml
+import os
+import sys
+
+usage = """
+Usage: python setup.py bdist_wheel --plat-name <platform>
+The PACKAGE_VERSION environment variable must be set to the desired version.
+
+Example:
+  PACKAGE_VERSION=0.5.9 python setup.py bdist_wheel --plat-name linux_x86_64
+"""
+
+# Read pyproject.toml for metadata
+with open("pyproject.toml", "r") as f:
+    pyproject = toml.load(f)
+
+project = pyproject["project"]
+
+# Get version from environment or default
+version = os.environ.get("PACKAGE_VERSION", "")
+if not version:
+    print("PACKAGE_VERSION environment variable is not set.")
+    print(usage)
+    exit(1)
+
+# Get Python platform name from --plat-name argument
+plat_name = None
+for i, arg in enumerate(sys.argv):
+    if arg == "--plat-name" and i + 1 < len(sys.argv):
+        plat_name = sys.argv[i + 1]
+        break
+
+if not plat_name:
+    print("Error: --plat-name argument is required")
+    print(usage)
+    sys.exit(1)
+
+# Map plat_name to classifier
+classifier_map = {
+    "linux_x86_64": "Operating System :: POSIX :: Linux",
+    "linux_aarch64": "Operating System :: POSIX :: Linux",
+    "win_amd64": "Operating System :: Microsoft :: Windows",
+    "macosx_10_9_x86_64": "Operating System :: MacOS",
+    "macosx_11_0_arm64": "Operating System :: MacOS",
+}
+
+classifier = classifier_map.get(plat_name)
+if not classifier:
+    print(f"Unknown plat_name: {plat_name}")
+    sys.exit(1)
+
+with open("README.md", "r", encoding="utf-8") as f:
+    long_description = f.read()
+
+setuptools.setup(
+    name=project["name"],
+    version=version,
+    description=project.get("description", ""),
+    author=project["authors"][0]["name"] if project.get("authors") else "",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url=project["urls"]["Homepage"],
+    packages=setuptools.find_packages(where="src"),
+    package_dir={"": "src"},
+    include_package_data=True,
+    python_requires=project.get("requires-python", ">=3"),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        classifier
+    ],
+)