scythe-sql 0.13.0__tar.gz

scythe_sql-0.13.0/.gitignore

@@ -0,0 +1,60 @@
+# Rust build artifacts
+/target/
+**/*.rs.bk
+site/
+.playwright-mcp/
+.ruff_cache/
+.mcp.json
+# IDE
+.idea/
+.claude/
+.rumdl_cache/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# Ruby
+.bundle/
+
+# Generated output (except integration test fixtures)
+**/generated/
+generated/
+output/
+!integration_tests/**/generated/
+!crates/scythe-cli/tests/generated/
+!crates/scythe-cli/tests/generated/*.rs
+
+# Environment
+.env
+.env.*
+!.env.example
+
+
+# poly cache
+.polylint/
+
+# BEGIN ai-rulez (DO NOT EDIT - managed by ai-rulez)
+.ai-rulez/.generated-manifest.json
+.codex/
+AGENTS.md
+CLAUDE.md
+# END ai-rulez
+poly.local.toml
+
+# Astro docs site
+website/node_modules/
+website/dist/
+website/.astro/
+
+# snowflake-sdk writes this on every run
+snowflake.log

scythe_sql-0.13.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: scythe-sql
+Version: 0.13.0
+Summary: SQL compilation and code generation CLI -- PyPI wrapper that downloads the prebuilt scythe binary
+Project-URL: Homepage, https://goldziher.github.io/scythe
+Project-URL: Repository, https://github.com/Goldziher/scythe
+Project-URL: Issues, https://github.com/Goldziher/scythe/issues
+Author: Na'aman Hirschfeld
+License-Expression: MIT
+Keywords: cli,codegen,database,sql,sqlc
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# scythe-sql
+
+PyPI wrapper for [scythe](https://github.com/Goldziher/scythe), the polyglot SQL-to-code generator.
+Installs a pinned `scythe` binary without requiring a Rust toolchain.
+
+```bash
+pip install scythe-sql
+scythe --version
+```
+
+`pip install` does not run any code for a wheel install, so there is no download-on-install step.
+Instead, the installed `scythe` console script downloads the matching prebuilt binary for your
+platform on first run (verifying its SHA-256 checksum) and caches it under
+`~/.cache/scythe/<version>/` (`%LOCALAPPDATA%\scythe\cache` on Windows). Every subsequent invocation
+execs the cached binary directly. The script never writes into `site-packages`, so it works under
+read-only installs, containers, and `pip install --user`.
+
+## Warming the cache in a Dockerfile
+
+```dockerfile
+RUN pip install scythe-sql && scythe --version
+```
+
+## Supported platforms
+
+- Linux x64 / arm64 (glibc only -- musl/Alpine is not supported; use `cargo install scythe-cli`)
+- macOS x64 / arm64
+- Windows x64 (Windows on ARM64 falls back to the x64 binary via emulation)
+
+## Environment variables
+
+- `SCYTHE_BINARY` -- absolute path to a `scythe` binary to use instead of downloading.
+- `SCYTHE_SKIP_DOWNLOAD=1` -- never download; fail if no cached or PATH binary is available.
+- `SCYTHE_CACHE_DIR` -- override the cache root directory.
+- `PIP_CERT` / `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` -- custom CA bundle.
+
+Proxy configuration (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`) is honoured natively via
+`urllib.request`.

scythe_sql-0.13.0/README.md

@@ -0,0 +1,38 @@
+# scythe-sql
+
+PyPI wrapper for [scythe](https://github.com/Goldziher/scythe), the polyglot SQL-to-code generator.
+Installs a pinned `scythe` binary without requiring a Rust toolchain.
+
+```bash
+pip install scythe-sql
+scythe --version
+```
+
+`pip install` does not run any code for a wheel install, so there is no download-on-install step.
+Instead, the installed `scythe` console script downloads the matching prebuilt binary for your
+platform on first run (verifying its SHA-256 checksum) and caches it under
+`~/.cache/scythe/<version>/` (`%LOCALAPPDATA%\scythe\cache` on Windows). Every subsequent invocation
+execs the cached binary directly. The script never writes into `site-packages`, so it works under
+read-only installs, containers, and `pip install --user`.
+
+## Warming the cache in a Dockerfile
+
+```dockerfile
+RUN pip install scythe-sql && scythe --version
+```
+
+## Supported platforms
+
+- Linux x64 / arm64 (glibc only -- musl/Alpine is not supported; use `cargo install scythe-cli`)
+- macOS x64 / arm64
+- Windows x64 (Windows on ARM64 falls back to the x64 binary via emulation)
+
+## Environment variables
+
+- `SCYTHE_BINARY` -- absolute path to a `scythe` binary to use instead of downloading.
+- `SCYTHE_SKIP_DOWNLOAD=1` -- never download; fail if no cached or PATH binary is available.
+- `SCYTHE_CACHE_DIR` -- override the cache root directory.
+- `PIP_CERT` / `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` -- custom CA bundle.
+
+Proxy configuration (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`) is honoured natively via
+`urllib.request`.

scythe_sql-0.13.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "scythe-sql"
+version = "0.13.0"
+description = "SQL compilation and code generation CLI -- PyPI wrapper that downloads the prebuilt scythe binary"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Na'aman Hirschfeld" }]
+keywords = ["sql", "codegen", "cli", "database", "sqlc"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Database",
+  "Topic :: Software Development :: Code Generators",
+]
+
+[project.urls]
+Homepage = "https://goldziher.github.io/scythe"
+Repository = "https://github.com/Goldziher/scythe"
+Issues = "https://github.com/Goldziher/scythe/issues"
+
+[project.scripts]
+scythe = "scythe_sql.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scythe_sql"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md"]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0"]

scythe_sql-0.13.0/src/scythe_sql/__init__.py

@@ -0,0 +1,7 @@
+"""PyPI wrapper for the scythe CLI.
+
+Downloads and execs the prebuilt ``scythe`` binary for the current platform;
+see :mod:`scythe_sql.cli` for the entry point.
+"""
+
+__version__ = "0.13.0"

scythe_sql-0.13.0/src/scythe_sql/cache.py

@@ -0,0 +1,34 @@
+"""Cache directory resolution for the downloaded scythe binary."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def resolve_cache_root(*, env: dict[str, str], sys_platform: str, home: Path) -> Path:
+    """Resolves the root cache directory, honouring `SCYTHE_CACHE_DIR` and XDG conventions."""
+    override = env.get("SCYTHE_CACHE_DIR")
+    if override:
+        return Path(override)
+
+    if sys_platform.startswith("win"):
+        base = env.get("LOCALAPPDATA")
+        base_path = Path(base) if base else home / "AppData" / "Local"
+        return base_path / "scythe" / "cache"
+
+    xdg_cache_home = env.get("XDG_CACHE_HOME")
+    if xdg_cache_home:
+        return Path(xdg_cache_home) / "scythe"
+
+    return home / ".cache" / "scythe"
+
+
+def cached_binary_path(*, env: dict[str, str], sys_platform: str, home: Path, version: str, binary_name: str) -> Path:
+    """Resolves the cached binary path for a given version."""
+    return resolve_cache_root(env=env, sys_platform=sys_platform, home=home) / version / binary_name
+
+
+def default_home() -> Path:
+    """Returns the current user's home directory."""
+    return Path(os.path.expanduser("~"))

scythe_sql-0.13.0/src/scythe_sql/checksum.py

@@ -0,0 +1,67 @@
+"""Checksum parsing and verification for goreleaser checksum files."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from scythe_sql.errors import ScytheSqlError
+
+_ROW_RE = re.compile(r"^([0-9a-fA-F]{64})\s+\*?(\S+)$")
+
+
+def parse_checksums(contents: str) -> dict[str, str]:
+    """Parses a `scythe_<version>_checksums.txt` file into filename -> lowercase hex sha256."""
+    result: dict[str, str] = {}
+    for raw_line in contents.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        match = _ROW_RE.match(line)
+        if not match:
+            continue
+        digest, filename = match.groups()
+        result[filename] = digest.lower()
+    return result
+
+
+class MissingChecksumError(ScytheSqlError):
+    """Raised when the checksums file has no row for the requested asset."""
+
+
+def expected_checksum(checksums: dict[str, str], asset_filename: str, checksums_url: str) -> str:
+    """Looks up the expected checksum for `asset_filename`.
+
+    Raises :class:`MissingChecksumError` when the row is missing -- a
+    missing row means the release is malformed and verification must not be
+    silently skipped.
+    """
+    expected = checksums.get(asset_filename)
+    if expected is None:
+        raise MissingChecksumError(
+            f"scythe-sql: no checksum entry for '{asset_filename}' in {checksums_url}. "
+            "The release appears malformed; refusing to install without verification."
+        )
+    return expected
+
+
+def sha256_hex(data: bytes) -> str:
+    """Computes the lowercase hex sha256 digest of `data`."""
+    return hashlib.sha256(data).hexdigest()
+
+
+class ChecksumMismatchError(ScytheSqlError):
+    """Raised when a downloaded asset's checksum does not match the expected value."""
+
+
+def verify_checksum(data: bytes, expected_hex: str, asset_url: str) -> None:
+    """Verifies `data` against `expected_hex`, case-insensitively.
+
+    Raises :class:`ChecksumMismatchError` naming both hashes and the source
+    URL on mismatch.
+    """
+    actual = sha256_hex(data)
+    if actual.lower() != expected_hex.lower():
+        raise ChecksumMismatchError(
+            f"scythe-sql: checksum mismatch for {asset_url}\n  expected: {expected_hex.lower()}\n  actual:   {actual}"
+        )

scythe_sql-0.13.0/src/scythe_sql/cli.py

@@ -0,0 +1,62 @@
+"""Entry point installed as the `scythe` console script.
+
+`pip install` does not run post-install code for a wheel, so there is no way
+to download the binary at install time. Instead, each invocation ensures the
+cached binary is present (downloading + verifying on first run only, which
+prints one line to stderr) and then execs it, forwarding argv and letting the
+kernel propagate the exit code. Never writes into site-packages at runtime --
+that breaks read-only installs, containers, and `pip install --user`.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from scythe_sql import __version__
+from scythe_sql.download import ensure_binary
+from scythe_sql.errors import ScytheSqlError
+
+
+def main() -> int:
+    """Resolves the pinned scythe binary and execs it with the current argv."""
+    try:
+        binary_path = ensure_binary(__version__)
+    except ScytheSqlError as exc:
+        # Every error in this hierarchy already carries the `scythe-sql:` prefix
+        # and its own remediation advice; re-wrapping it below would double the
+        # prefix. Catching the shared base rather than naming subclasses is what
+        # keeps checksum and platform failures on this branch as they are added.
+        print(str(exc), file=sys.stderr)
+        return 1
+    except Exception as exc:  # noqa: BLE001 -- surface any unexpected failure with context
+        print(f"scythe-sql: failed to resolve the scythe binary: {exc}", file=sys.stderr)
+        return 1
+
+    argv = [str(binary_path), *sys.argv[1:]]
+
+    # Windows has no real exec: its `os.execv` spawns a new process and kills
+    # this one, so the shell regains control immediately with exit code 0 while
+    # scythe is still running. Every failure would be reported as success --
+    # `scythe check` could never fail a Windows CI job. Wait on a child instead
+    # and hand back its status.
+    if os.name == "nt":
+        import subprocess  # noqa: PLC0415 -- POSIX execs and never needs this
+
+        try:
+            return subprocess.run(argv, check=False).returncode  # noqa: S603 -- resolved via our own cache logic
+        except OSError as exc:
+            print(f"scythe-sql: failed to execute {binary_path}: {exc}", file=sys.stderr)
+            return 1
+
+    # POSIX: exec is strictly better than spawning -- no extra process sits in
+    # the tree, and signals reach scythe directly rather than this wrapper.
+    try:
+        os.execv(str(binary_path), argv)  # noqa: S606 -- resolved via our own cache/PATH logic
+    except OSError as exc:
+        print(f"scythe-sql: failed to execute {binary_path}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scythe_sql-0.13.0/src/scythe_sql/download.py

@@ -0,0 +1,128 @@
+"""Download and cache the platform-specific scythe binary."""
+
+from __future__ import annotations
+
+import os
+import platform
+import stat
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from scythe_sql.cache import cached_binary_path, default_home
+from scythe_sql.checksum import expected_checksum, parse_checksums, verify_checksum
+from scythe_sql.errors import ScytheSqlError
+from scythe_sql.extract import extract_tar_gz, extract_zip
+from scythe_sql.platform_resolver import UnsupportedPlatformError, is_musl_linux, resolve_target
+from scythe_sql.proxy import resolve_ca_file
+from scythe_sql.version_utils import assert_real_version
+
+REPO = "https://github.com/Goldziher/scythe"
+
+
+class DownloadError(ScytheSqlError):
+    """Raised when fetching a release asset fails."""
+
+
+def _fetch(url: str) -> bytes:
+    ca_file = resolve_ca_file(dict(os.environ))
+    context = None
+    if ca_file:
+        import ssl
+
+        context = ssl.create_default_context(cafile=ca_file)
+
+    # urllib.request honours HTTPS_PROXY/HTTP_PROXY/NO_PROXY natively via
+    # the environment (ProxyHandler is installed by default in build_opener()).
+    request = urllib.request.Request(url, headers={"User-Agent": "scythe-sql-installer"})  # noqa: S310
+    try:
+        with urllib.request.urlopen(request, context=context) as response:  # noqa: S310
+            if response.status != 200:
+                raise DownloadError(f"scythe-sql: failed to download {url}: HTTP {response.status}")
+            return response.read()
+    except urllib.error.URLError as exc:
+        raise DownloadError(f"scythe-sql: failed to download {url}: {exc}") from exc
+
+
+def is_usable_cached_binary(path: Path) -> bool:
+    """Reports whether `path` holds a complete, runnable cached binary.
+
+    Existence is not enough. A cache entry written by an older, non-atomic
+    version of this package -- or by any interrupted write -- can be an empty or
+    truncated file, and returning it would fail at exec time with an opaque
+    error on every subsequent run. A zero-length file is never a valid binary,
+    so treat it as absent and re-download over it.
+    """
+    try:
+        stat_result = path.stat()
+    except OSError:
+        return False
+    return stat.S_ISREG(stat_result.st_mode) and stat_result.st_size > 0
+
+
+def ensure_binary(version: str, *, env: dict[str, str] | None = None) -> Path:
+    """Ensures the pinned scythe binary is present locally, downloading it if needed.
+
+    Returns the path to a usable `scythe` binary.
+    """
+    env = dict(os.environ) if env is None else env
+    assert_real_version(version)
+
+    if env.get("SCYTHE_BINARY"):
+        return Path(env["SCYTHE_BINARY"])
+
+    resolved = resolve_target(
+        sys_platform=sys.platform,
+        machine=platform.machine(),
+        is_musl=sys.platform.startswith("linux") and is_musl_linux(platform.libc_ver()),
+    )
+
+    dest_path = cached_binary_path(
+        env=env,
+        sys_platform=sys.platform,
+        home=default_home(),
+        version=version,
+        binary_name=resolved.binary_name,
+    )
+
+    if is_usable_cached_binary(dest_path):
+        return dest_path
+
+    from scythe_sql.preinstalled import has_matching_path_binary
+
+    if has_matching_path_binary(version):
+        return Path("scythe")
+
+    if env.get("SCYTHE_SKIP_DOWNLOAD") == "1":
+        raise DownloadError(
+            f"scythe-sql: SCYTHE_SKIP_DOWNLOAD=1 set but no cached or PATH binary matching {version} found."
+        )
+
+    asset_name = f"scythe-{resolved.target}.{resolved.archive_ext}"
+    checksums_name = f"scythe_{version}_checksums.txt"
+    base_url = f"{REPO}/releases/download/v{version}"
+    asset_url = f"{base_url}/{asset_name}"
+    checksums_url = f"{base_url}/{checksums_name}"
+
+    print(f"scythe-sql: downloading scythe {version} for {resolved.target}...", file=sys.stderr)  # noqa: T201
+
+    checksums_text = _fetch(checksums_url).decode("utf-8")
+    checksums = parse_checksums(checksums_text)
+    expected = expected_checksum(checksums, asset_name, checksums_url)
+
+    asset_bytes = _fetch(asset_url)
+    verify_checksum(asset_bytes, expected, asset_url)
+
+    # Both extractors stage into a temp file, set the mode, then rename, so
+    # dest_path only ever appears complete and executable.
+    if resolved.archive_ext == "zip":
+        extract_zip(asset_bytes, resolved.binary_name, dest_path)
+    else:
+        extract_tar_gz(asset_bytes, resolved.binary_name, dest_path)
+
+    print(f"scythe-sql: installed scythe {version} to {dest_path}", file=sys.stderr)  # noqa: T201
+    return dest_path
+
+
+__all__ = ["DownloadError", "ScytheSqlError", "UnsupportedPlatformError", "ensure_binary", "is_usable_cached_binary"]

scythe_sql-0.13.0/src/scythe_sql/errors.py

@@ -0,0 +1,16 @@
+"""Shared base exception for every failure this wrapper raises."""
+
+from __future__ import annotations
+
+
+class ScytheSqlError(RuntimeError):
+    """Base class for all scythe-sql wrapper failures.
+
+    Every message in this hierarchy is already prefixed with ``scythe-sql:`` and
+    is written to be printed verbatim, so :mod:`scythe_sql.cli` can catch this
+    one type instead of enumerating subclasses -- an enumeration that silently
+    fell out of date and double-prefixed the security-relevant checksum errors.
+
+    Subclasses :class:`RuntimeError` so any caller already catching
+    ``RuntimeError`` keeps working.
+    """

scythe_sql-0.13.0/src/scythe_sql/extract.py

@@ -0,0 +1,89 @@
+"""Archive extraction: locate and unpack the scythe binary by basename.
+
+The archive also contains LICENSE/README (goreleaser default), so callers
+must not assume a fixed path inside the archive -- search by basename.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import stat
+import tarfile
+import zipfile
+from pathlib import Path
+
+from scythe_sql.errors import ScytheSqlError
+
+
+class BinaryNotFoundError(ScytheSqlError):
+    """Raised when the archive does not contain an entry matching the binary name."""
+
+
+def find_binary_entry(entry_names: list[str], binary_name: str) -> str:
+    """Finds the archive entry whose basename matches `binary_name`."""
+    for name in entry_names:
+        if name.rstrip("/").split("/")[-1] == binary_name:
+            return name
+    listing = ", ".join(entry_names) if entry_names else "(empty)"
+    raise BinaryNotFoundError(
+        f"scythe-sql: could not find '{binary_name}' inside the downloaded archive. Archive contained: {listing}"
+    )
+
+
+def write_binary_atomically(dest_path: Path, data: bytes) -> None:
+    """Writes `data` to `dest_path` atomically, already marked executable.
+
+    Writing straight to the cached path is not safe: a process killed mid-write,
+    an OOM kill, or a full disk leaves a truncated file that the cache -- which
+    keys only on the path -- then trusts forever, so every later run fails with
+    an opaque exec error. Two concurrent installs sharing a cache can also
+    interleave their writes into the same file.
+
+    Staging into a sibling temp file and renaming makes the cached path either
+    absent or complete, never partial, because `os.replace` is atomic within a
+    filesystem (a sibling guarantees the same filesystem). The pid in the temp
+    name keeps concurrent writers off each other's staging file; the rename
+    itself makes the last writer win harmlessly, since both wrote verified
+    bytes. The mode is set on the temp file so the binary is never observable
+    at its final path without the executable bit.
+    """
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = dest_path.with_name(f".{dest_path.name}.{os.getpid()}.tmp")
+    try:
+        with tmp_path.open("wb") as handle:
+            handle.write(data)
+            handle.flush()
+            # Without fsync the rename can land before the data on a crash,
+            # recreating the truncated-file problem the staging file prevents.
+            os.fsync(handle.fileno())
+        if os.name != "nt":
+            make_executable(tmp_path)
+        os.replace(tmp_path, dest_path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def extract_tar_gz(data: bytes, binary_name: str, dest_path: Path) -> None:
+    """Extracts the scythe binary from a `.tar.gz` archive to `dest_path`."""
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
+        names = [member.name for member in tar.getmembers() if member.isfile()]
+        entry_name = find_binary_entry(names, binary_name)
+        member = tar.getmember(entry_name)
+        extracted = tar.extractfile(member)
+        if extracted is None:
+            raise BinaryNotFoundError(f"scythe-sql: archive entry '{entry_name}' is not a regular file")
+        write_binary_atomically(dest_path, extracted.read())
+
+
+def extract_zip(data: bytes, binary_name: str, dest_path: Path) -> None:
+    """Extracts the scythe binary from a `.zip` archive to `dest_path`."""
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        names = [info.filename for info in zf.infolist() if not info.is_dir()]
+        entry_name = find_binary_entry(names, binary_name)
+        write_binary_atomically(dest_path, zf.read(entry_name))
+
+
+def make_executable(path: Path) -> None:
+    """chmod 0o755 on POSIX; a no-op is not needed on Windows since .exe requires no bit."""
+    path.chmod(stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | stat.S_IROTH | stat.S_IXOTH)

scythe_sql-0.13.0/src/scythe_sql/platform_resolver.py

@@ -0,0 +1,146 @@
+"""Platform+arch -> Rust target triple resolution for scythe release assets.
+
+Release assets published by goreleaser (verified against the v0.12.0 release):
+    scythe-x86_64-unknown-linux-gnu.tar.gz
+    scythe-aarch64-unknown-linux-gnu.tar.gz
+    scythe-x86_64-apple-darwin.tar.gz
+    scythe-aarch64-apple-darwin.tar.gz
+    scythe-x86_64-pc-windows-gnu.zip
+
+There is no musl target and no aarch64 Windows asset.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from scythe_sql.errors import ScytheSqlError
+
+TRIPLES: dict[tuple[str, str], str] = {
+    ("linux", "x64"): "x86_64-unknown-linux-gnu",
+    ("linux", "arm64"): "aarch64-unknown-linux-gnu",
+    ("darwin", "x64"): "x86_64-apple-darwin",
+    ("darwin", "arm64"): "aarch64-apple-darwin",
+    ("win32", "x64"): "x86_64-pc-windows-gnu",
+}
+
+_MACHINE_ALIASES: dict[str, str] = {
+    "x86_64": "x64",
+    "amd64": "x64",
+    "aarch64": "arm64",
+    "arm64": "arm64",
+}
+
+
+@dataclass(frozen=True)
+class ResolvedTarget:
+    """Resolved Rust target triple, archive extension, and binary filename."""
+
+    target: str
+    archive_ext: str
+    binary_name: str
+
+
+class UnsupportedPlatformError(ScytheSqlError):
+    """Raised when no release asset exists for the current platform/arch."""
+
+
+def normalize_platform(sys_platform: str) -> str:
+    """Maps ``sys.platform`` values to the npm-style keys used by ``TRIPLES``."""
+    if sys_platform.startswith("linux"):
+        return "linux"
+    if sys_platform == "darwin":
+        return "darwin"
+    if sys_platform.startswith("win"):
+        return "win32"
+    return sys_platform
+
+
+def normalize_machine(machine: str) -> str:
+    """Maps ``platform.machine()`` values to the npm-style arch keys."""
+    return _MACHINE_ALIASES.get(machine.lower(), machine.lower())
+
+
+_MUSL_LOADER_DIRS: tuple[str, ...] = ("/lib", "/usr/lib")
+_MUSL_LOADER_GLOB = "ld-musl-*.so.1"
+
+
+def musl_loader_present(loader_dirs: Iterable[str] = _MUSL_LOADER_DIRS) -> bool:
+    """Reports whether a musl dynamic loader (``ld-musl-<arch>.so.1``) exists on disk."""
+    return any(any(Path(directory).glob(_MUSL_LOADER_GLOB)) for directory in loader_dirs)
+
+
+def is_musl_linux(
+    libc_ver: tuple[str, str],
+    *,
+    loader_present: Callable[[], bool] = musl_loader_present,
+) -> bool:
+    """Detects musl libc (e.g. Alpine) from :func:`platform.libc_ver` output.
+
+    ``platform.libc_ver()`` alone cannot answer this across the supported
+    interpreter range. CPython only taught it to recognize musl in 3.14, where a
+    musl host reports ``("musl", "1.2.x")``; on 3.9 through 3.13 the same host
+    reports ``("", "")``. Treating ``("", "")`` as proof of musl is therefore
+    wrong in both directions: it misses musl on 3.14+, and it misfires on glibc
+    whenever the lookup merely fails -- ``sys.executable`` is unset (embedded
+    interpreters), or the binary is statically linked or stripped of the symbols
+    the function scans for. The docs describe it as a heuristic with "intimate
+    knowledge of how different libc versions add symbols", not a contract.
+
+    So: trust an explicit answer in either direction, and fall back to positive
+    on-disk evidence of a musl loader when the tuple is empty and thus tells us
+    nothing.
+    """
+    reported_lib = libc_ver[0].lower()
+    if reported_lib == "musl":
+        return True
+    if reported_lib:
+        return False
+    return loader_present()
+
+
+def resolve_target(
+    *,
+    sys_platform: str = sys.platform,
+    machine: str,
+    is_musl: bool = False,
+    warn: Callable[[str], None] | None = None,
+) -> ResolvedTarget:
+    """Resolves the release target for the current platform/arch.
+
+    Raises :class:`UnsupportedPlatformError` naming the platform and arch,
+    or the musl-specific guidance, when no asset is published.
+    """
+    platform_key = normalize_platform(sys_platform)
+    arch_key = normalize_machine(machine)
+    warn_fn = warn or (lambda message: print(message, file=sys.stderr))  # noqa: T201
+
+    if platform_key == "linux" and is_musl:
+        raise UnsupportedPlatformError(
+            f"scythe-sql: unsupported platform 'linux/{arch_key}' (musl libc, e.g. Alpine). "
+            "No musl build is published. Install a glibc-based image, or install scythe via "
+            "'cargo install scythe-cli' instead."
+        )
+
+    if platform_key == "win32" and arch_key == "arm64":
+        warn_fn(
+            "scythe-sql: no native Windows ARM64 build is published; falling back to the "
+            "x86_64-pc-windows-gnu binary, which runs under Windows 11 ARM64 x64 emulation."
+        )
+        return ResolvedTarget(target=TRIPLES[("win32", "x64")], archive_ext="zip", binary_name="scythe.exe")
+
+    target = TRIPLES.get((platform_key, arch_key))
+    if target is None:
+        supported = ", ".join(f"{p}/{a}" for p, a in TRIPLES)
+        raise UnsupportedPlatformError(
+            f"scythe-sql: unsupported platform '{platform_key}/{arch_key}'. Supported platforms: "
+            f"{supported} (plus win32/arm64 via x64 emulation). Install scythe via "
+            "'cargo install scythe-cli' instead."
+        )
+
+    archive_ext = "zip" if platform_key == "win32" else "tar.gz"
+    binary_name = "scythe.exe" if platform_key == "win32" else "scythe"
+    return ResolvedTarget(target=target, archive_ext=archive_ext, binary_name=binary_name)

scythe_sql-0.13.0/src/scythe_sql/preinstalled.py

@@ -0,0 +1,33 @@
+"""Detects a matching scythe binary already on PATH."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+
+from scythe_sql.version_utils import extract_version
+
+_ExecFn = Callable[[], str]
+
+
+def _default_exec() -> str:
+    result = subprocess.run(  # noqa: S603
+        ["scythe", "--version"],  # noqa: S607
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout
+
+
+def has_matching_path_binary(want_version: str, exec_fn: _ExecFn = _default_exec) -> bool:
+    """Checks whether a `scythe` binary already on PATH matches `want_version` exactly.
+
+    Exact equality only: a newer binary on PATH does not satisfy a pin, since
+    silently upgrading defeats the point of pinning the dependency version.
+    """
+    try:
+        output = exec_fn()
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return extract_version(output) == want_version

scythe_sql-0.13.0/src/scythe_sql/proxy.py

@@ -0,0 +1,22 @@
+"""CA bundle resolution.
+
+Proxy handling itself is not reimplemented here: `urllib.request` honours
+`HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` natively via `urllib.request.getproxies`
+and `ProxyHandler`, unlike Node's `fetch`. Only the CA bundle path needs
+explicit resolution, since Python has no single standard env var for it.
+"""
+
+from __future__ import annotations
+
+
+def resolve_ca_file(env: dict[str, str]) -> str | None:
+    """Resolves the CA bundle file path to trust, honouring pip's and requests' conventions.
+
+    An exported-but-empty variable counts as unset, and yields ``None`` rather
+    than the empty string an ``or`` chain would otherwise fall through to.
+    """
+    for variable in ("PIP_CERT", "REQUESTS_CA_BUNDLE", "SSL_CERT_FILE"):
+        value = env.get(variable)
+        if value:
+            return value
+    return None

scythe_sql-0.13.0/src/scythe_sql/version_utils.py

@@ -0,0 +1,38 @@
+"""Version string parsing and the 0.0.0 placeholder guard."""
+
+from __future__ import annotations
+
+import re
+
+from scythe_sql.errors import ScytheSqlError
+
+_VERSION_RE = re.compile(r"(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)")
+
+
+def extract_version(output: str) -> str | None:
+    """Permissively extracts a semver-ish version token from CLI output.
+
+    The exact output format of the real ``scythe --version`` binary is not
+    pinned by design, so this finds the first ``MAJOR.MINOR.PATCH[-pre][+build]``
+    token rather than anchoring to the full line.
+    """
+    match = _VERSION_RE.search(output)
+    return match.group(1) if match else None
+
+
+class PlaceholderVersionError(ScytheSqlError):
+    """Raised when the package still carries the unbuilt 0.0.0 placeholder version."""
+
+
+def assert_real_version(version: str) -> None:
+    """Refuses to proceed when `version` is the unbuilt `0.0.0` placeholder.
+
+    A wrapper built from a dirty/unversioned checkout would otherwise
+    construct a nonsense download URL.
+    """
+    if version == "0.0.0":
+        raise PlaceholderVersionError(
+            "scythe-sql: this package was built incorrectly -- it still carries the placeholder "
+            "version '0.0.0'. The publish workflow must inject the real release version (RELEASE_VERSION) "
+            "before building. Please report this at https://github.com/Goldziher/scythe/issues."
+        )