syq 0.0.1__tar.gz

syq-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grant Reaber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

syq-0.0.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: syq
+Version: 0.0.1
+Summary: Version-pinned Python adapter for the syq parallel file copier
+Author: Grant Reaber
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/greaber/syq
+Project-URL: Repository, https://github.com/greaber/syq
+Project-URL: Issues, https://github.com/greaber/syq/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# syq for Python
+
+`syq` is the official preview Python adapter for the
+[syq parallel file copier](https://github.com/greaber/syq). It invokes syq with
+an argument array and never constructs a shell command.
+
+```sh
+python -m pip install syq
+```
+
+Package installation does not download an executable. The first call that
+needs syq downloads the exact release pinned by this SDK into the user cache.
+For Python package `0.0.1`, that release is syq `0.1.5`.
+
+```python
+import syq
+
+print(syq.__version__)           # Python package version
+print(syq.PINNED_SYQ_VERSION)    # tested executable version
+print(syq.managed_executable())  # downloads once, then returns the cached path
+
+plan = syq.run([
+    "cp",
+    "project",
+    "--to",
+    "server",
+    "--into",
+    "/backup",
+    "--dry-run",
+])
+print(plan.stdout.decode())
+```
+
+The managed executable is stored below
+`$XDG_CACHE_HOME/syq/sdk/python/v0.1.5/` or, when `XDG_CACHE_HOME` is not an
+absolute path, `~/.cache/syq/sdk/python/v0.1.5/`. The SDK checks the complete
+cached binary against its embedded release manifest before every use. A corrupt
+or missing cache entry is replaced atomically with a freshly downloaded,
+verified binary.
+
+`run()` raises `SyqProcessError` for a nonzero process status by default. The
+exception retains the complete result, including stdout and stderr as bytes.
+Pass `check=False` when the caller wants to interpret the status directly.
+When `timeout` expires or the caller is interrupted, the SDK kills and reaps
+syq's local process group, including child processes such as SSH transports,
+before propagating the exception.
+
+## Custom executable override
+
+An explicit executable bypasses the managed version:
+
+```python
+result = syq.run(["--help"], executable="/opt/custom/bin/syq")
+custom_version = syq.version(executable="syq")  # intentional PATH lookup
+```
+
+The SDK makes no compatibility or provenance guarantee for an override. Use it
+for local development, controlled offline provisioning, or when deliberately
+testing a different syq release.
+
+The package targets Python 3.10 or newer on Linux and macOS and has no runtime
+Python dependencies. See the [SDK compatibility policy](../README.md) for the
+release mapping.

syq-0.0.1/README.md

@@ -0,0 +1,63 @@
+# syq for Python
+
+`syq` is the official preview Python adapter for the
+[syq parallel file copier](https://github.com/greaber/syq). It invokes syq with
+an argument array and never constructs a shell command.
+
+```sh
+python -m pip install syq
+```
+
+Package installation does not download an executable. The first call that
+needs syq downloads the exact release pinned by this SDK into the user cache.
+For Python package `0.0.1`, that release is syq `0.1.5`.
+
+```python
+import syq
+
+print(syq.__version__)           # Python package version
+print(syq.PINNED_SYQ_VERSION)    # tested executable version
+print(syq.managed_executable())  # downloads once, then returns the cached path
+
+plan = syq.run([
+    "cp",
+    "project",
+    "--to",
+    "server",
+    "--into",
+    "/backup",
+    "--dry-run",
+])
+print(plan.stdout.decode())
+```
+
+The managed executable is stored below
+`$XDG_CACHE_HOME/syq/sdk/python/v0.1.5/` or, when `XDG_CACHE_HOME` is not an
+absolute path, `~/.cache/syq/sdk/python/v0.1.5/`. The SDK checks the complete
+cached binary against its embedded release manifest before every use. A corrupt
+or missing cache entry is replaced atomically with a freshly downloaded,
+verified binary.
+
+`run()` raises `SyqProcessError` for a nonzero process status by default. The
+exception retains the complete result, including stdout and stderr as bytes.
+Pass `check=False` when the caller wants to interpret the status directly.
+When `timeout` expires or the caller is interrupted, the SDK kills and reaps
+syq's local process group, including child processes such as SSH transports,
+before propagating the exception.
+
+## Custom executable override
+
+An explicit executable bypasses the managed version:
+
+```python
+result = syq.run(["--help"], executable="/opt/custom/bin/syq")
+custom_version = syq.version(executable="syq")  # intentional PATH lookup
+```
+
+The SDK makes no compatibility or provenance guarantee for an override. Use it
+for local development, controlled offline provisioning, or when deliberately
+testing a different syq release.
+
+The package targets Python 3.10 or newer on Linux and macOS and has no runtime
+Python dependencies. See the [SDK compatibility policy](../README.md) for the
+release mapping.

syq-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools==80.9.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syq"
+version = "0.0.1"
+description = "Version-pinned Python adapter for the syq parallel file copier"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Grant Reaber" },
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Filesystems",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://github.com/greaber/syq"
+Repository = "https://github.com/greaber/syq"
+Issues = "https://github.com/greaber/syq/issues"
+
+[dependency-groups]
+dev = [
+    "build==1.3.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+syq = ["py.typed", "syq-release-manifest.json"]
+
+[tool.uv]
+required-version = "==0.11.6"

syq-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

syq-0.0.1/src/syq/__init__.py

@@ -0,0 +1,19 @@
+"""Safe subprocess access to the syq executable."""
+
+from importlib.metadata import version as distribution_version
+
+from .bootstrap import PINNED_SYQ_VERSION, SyqInstallError, managed_executable
+from .client import Result, SyqOutputError, SyqProcessError, run, version
+
+__all__ = [
+    "PINNED_SYQ_VERSION",
+    "Result",
+    "SyqInstallError",
+    "SyqOutputError",
+    "SyqProcessError",
+    "managed_executable",
+    "run",
+    "version",
+]
+
+__version__ = distribution_version("syq")

syq-0.0.1/src/syq/bootstrap.py

@@ -0,0 +1,331 @@
+"""Install the syq release pinned by this Python package."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import http.client
+import json
+import os
+import platform
+import stat
+import subprocess
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, BinaryIO
+
+
+_DOWNLOAD_TIMEOUT_SECONDS = 30
+_CHUNK_SIZE = 1024 * 1024
+_EXPECTED_REPOSITORY = "https://github.com/greaber/syq"
+
+
+class SyqInstallError(RuntimeError):
+    """The SDK could not install or validate its pinned syq executable."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Artifact:
+    target: str
+    archive_name: str
+    archive_sha256: str
+    archive_size: int
+    binary_sha256: str
+    binary_size: int
+
+
+@lru_cache(maxsize=1)
+def _load_release_manifest() -> dict[str, Any]:
+    try:
+        raw = files("syq").joinpath("syq-release-manifest.json").read_bytes()
+        manifest = json.loads(raw)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise SyqInstallError(
+            "the packaged syq release manifest is invalid"
+        ) from error
+    if not isinstance(manifest, dict):
+        raise SyqInstallError("the packaged syq release manifest is not an object")
+    if manifest.get("repository") != _EXPECTED_REPOSITORY:
+        raise SyqInstallError("the packaged syq release repository is unexpected")
+    version = manifest.get("version")
+    tag = manifest.get("tag")
+    if not isinstance(version, str) or tag != f"v{version}":
+        raise SyqInstallError("the packaged syq release version is invalid")
+    return manifest
+
+
+PINNED_SYQ_VERSION = str(_load_release_manifest()["version"])
+
+
+def _host_target() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    if system == "linux" and machine in {"x86_64", "amd64"}:
+        return "linux-x86_64"
+    if system == "linux" and machine in {"aarch64", "arm64"}:
+        return "linux-aarch64"
+    if system == "darwin" and machine in {"arm64", "aarch64"}:
+        return "macos-arm64"
+    if system == "darwin" and machine in {"x86_64", "amd64"}:
+        return "macos-x86_64"
+    raise SyqInstallError(
+        f"syq {PINNED_SYQ_VERSION} has no binary for {system or 'unknown'} "
+        f"{machine or 'unknown'}"
+    )
+
+
+def _positive_integer(value: Any, *, label: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise SyqInstallError(f"the packaged {label} is invalid")
+    return value
+
+
+def _digest(value: Any, *, label: str) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) != 64
+        or any(character not in "0123456789abcdef" for character in value)
+    ):
+        raise SyqInstallError(f"the packaged {label} is invalid")
+    return value
+
+
+def _artifact(manifest: dict[str, Any], target: str) -> _Artifact:
+    try:
+        entry = manifest["artifacts"][target]
+        archive = entry["archive"]
+        binary = entry["binary"]
+    except (KeyError, TypeError) as error:
+        raise SyqInstallError(f"the packaged metadata has no {target} artifact") from error
+    if not isinstance(archive, dict) or not isinstance(binary, dict):
+        raise SyqInstallError(f"the packaged metadata has an invalid {target} artifact")
+    archive_name = archive.get("name")
+    if (
+        not isinstance(archive_name, str)
+        or not archive_name.startswith("syq-")
+        or not archive_name.endswith(".gz")
+        or "/" in archive_name
+        or "\\" in archive_name
+    ):
+        raise SyqInstallError("the packaged archive name is invalid")
+    return _Artifact(
+        target=target,
+        archive_name=archive_name,
+        archive_sha256=_digest(archive.get("sha256"), label="archive digest"),
+        archive_size=_positive_integer(archive.get("size"), label="archive size"),
+        binary_sha256=_digest(binary.get("sha256"), label="binary digest"),
+        binary_size=_positive_integer(binary.get("size"), label="binary size"),
+    )
+
+
+def _default_cache_root() -> Path:
+    configured = os.environ.get("XDG_CACHE_HOME")
+    if configured and os.path.isabs(configured):
+        return Path(configured)
+    try:
+        return Path.home() / ".cache"
+    except RuntimeError as error:
+        raise SyqInstallError("could not locate the user cache directory") from error
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(_CHUNK_SIZE), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _matches(path: Path, *, size: int, sha256: str) -> bool:
+    try:
+        metadata = path.stat(follow_symlinks=False)
+        return (
+            stat.S_ISREG(metadata.st_mode)
+            and metadata.st_size == size
+            and _sha256_file(path) == sha256
+        )
+    except OSError:
+        return False
+
+
+def _copy_bounded(
+    source: BinaryIO,
+    destination: BinaryIO,
+    *,
+    expected_size: int,
+    label: str,
+) -> str:
+    digest = hashlib.sha256()
+    total = 0
+    while True:
+        chunk = source.read(min(_CHUNK_SIZE, expected_size + 1 - total))
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > expected_size:
+            raise SyqInstallError(f"the downloaded {label} is larger than expected")
+        digest.update(chunk)
+        destination.write(chunk)
+    if total != expected_size:
+        raise SyqInstallError(
+            f"the downloaded {label} has size {total}, expected {expected_size}"
+        )
+    return digest.hexdigest()
+
+
+def _download_archive(url: str, destination: Path, artifact: _Artifact) -> None:
+    request = urllib.request.Request(url, headers={"User-Agent": "syq-python-sdk"})
+    try:
+        with urllib.request.urlopen(
+            request, timeout=_DOWNLOAD_TIMEOUT_SECONDS
+        ) as response, destination.open("wb") as output:
+            final_url = response.geturl()
+            if urllib.parse.urlparse(final_url).scheme != "https":
+                raise SyqInstallError("the syq download redirected away from HTTPS")
+            actual_sha256 = _copy_bounded(
+                response,
+                output,
+                expected_size=artifact.archive_size,
+                label="archive",
+            )
+    except SyqInstallError:
+        raise
+    except (OSError, http.client.HTTPException, urllib.error.URLError) as error:
+        raise SyqInstallError(f"could not download pinned syq from {url}") from error
+    if actual_sha256 != artifact.archive_sha256:
+        raise SyqInstallError("the downloaded syq archive failed SHA-256 verification")
+
+
+def _decompress_archive(
+    archive_path: Path, binary_path: Path, artifact: _Artifact
+) -> None:
+    try:
+        with gzip.open(archive_path, "rb") as source, binary_path.open("wb") as output:
+            actual_sha256 = _copy_bounded(
+                source,
+                output,
+                expected_size=artifact.binary_size,
+                label="binary",
+            )
+    except SyqInstallError:
+        raise
+    except (EOFError, gzip.BadGzipFile, OSError) as error:
+        raise SyqInstallError("could not decompress the pinned syq archive") from error
+    if actual_sha256 != artifact.binary_sha256:
+        raise SyqInstallError("the downloaded syq binary failed SHA-256 verification")
+
+
+def _query_binary(path: Path, argument: str) -> str:
+    try:
+        completed = subprocess.run(
+            [os.fspath(path), argument],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=10,
+            check=False,
+            shell=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise SyqInstallError("the downloaded syq binary could not run") from error
+    try:
+        output = completed.stdout.decode("utf-8").strip()
+    except UnicodeDecodeError as error:
+        raise SyqInstallError(
+            "the downloaded syq binary returned invalid output"
+        ) from error
+    if completed.returncode != 0:
+        raise SyqInstallError(
+            f"the downloaded syq binary rejected {argument} with status "
+            f"{completed.returncode}"
+        )
+    return output
+
+
+def _validate_binary(path: Path, manifest: dict[str, Any]) -> None:
+    version = manifest["version"]
+    tag = manifest["tag"]
+    if _query_binary(path, "--version") != f"syq {version}":
+        raise SyqInstallError("the downloaded binary reports an unexpected version")
+    if _query_binary(path, "--build-identity") != tag:
+        raise SyqInstallError("the downloaded binary reports an unexpected build identity")
+
+
+def managed_executable(
+    *, cache_dir: str | os.PathLike[str] | None = None
+) -> Path:
+    """Return the verified executable pinned by this SDK, downloading if needed.
+
+    The executable is cached by syq release and host target. Its complete bytes
+    are checked against the manifest packaged in this SDK before every use.
+    """
+
+    manifest = _load_release_manifest()
+    target = _host_target()
+    artifact = _artifact(manifest, target)
+    cache_root = (
+        Path(cache_dir) if cache_dir is not None else _default_cache_root()
+    )
+    install_dir = (
+        cache_root
+        / "syq"
+        / "sdk"
+        / "python"
+        / f"v{manifest['version']}"
+        / target
+    )
+    try:
+        install_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    except OSError as error:
+        raise SyqInstallError(f"could not prepare syq SDK cache at {install_dir}") from error
+    executable = install_dir / "syq"
+    if _matches(
+        executable, size=artifact.binary_size, sha256=artifact.binary_sha256
+    ):
+        try:
+            executable.chmod(0o755)
+        except OSError as error:
+            raise SyqInstallError(
+                f"could not make cached syq executable: {executable}"
+            ) from error
+        return executable
+
+    base_url = f"{manifest['repository']}/releases/download/{manifest['tag']}"
+    url = f"{base_url}/{artifact.archive_name}"
+    archive_path: Path | None = None
+    binary_path: Path | None = None
+    try:
+        archive_file = tempfile.NamedTemporaryFile(
+            prefix=".syq-download-", suffix=".gz", dir=install_dir, delete=False
+        )
+        archive_path = Path(archive_file.name)
+        archive_file.close()
+        binary_file = tempfile.NamedTemporaryFile(
+            prefix=".syq-install-", dir=install_dir, delete=False
+        )
+        binary_path = Path(binary_file.name)
+        binary_file.close()
+        _download_archive(url, archive_path, artifact)
+        _decompress_archive(archive_path, binary_path, artifact)
+        binary_path.chmod(0o755)
+        _validate_binary(binary_path, manifest)
+        os.replace(binary_path, executable)
+        binary_path = None
+        return executable
+    except SyqInstallError:
+        raise
+    except OSError as error:
+        raise SyqInstallError(f"could not install pinned syq at {executable}") from error
+    finally:
+        for temporary_path in (archive_path, binary_path):
+            if temporary_path is not None:
+                try:
+                    temporary_path.unlink(missing_ok=True)
+                except OSError:
+                    pass

syq-0.0.1/src/syq/client.py

@@ -0,0 +1,114 @@
+"""Minimal process adapter for syq's command-line interface."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from .bootstrap import managed_executable
+
+
+@dataclass(frozen=True, slots=True)
+class Result:
+    """The complete result of one syq process."""
+
+    argv: tuple[str, ...]
+    returncode: int
+    stdout: bytes
+    stderr: bytes
+
+
+class SyqProcessError(RuntimeError):
+    """A syq process completed with a nonzero status."""
+
+    def __init__(self, result: Result) -> None:
+        self.result = result
+        super().__init__(f"syq exited with status {result.returncode}")
+
+
+class SyqOutputError(ValueError):
+    """syq returned output that the requested operation cannot interpret."""
+
+
+def _text_arg(value: str | os.PathLike[str], *, label: str) -> str:
+    result = os.fspath(value)
+    if not isinstance(result, str):
+        raise TypeError(f"{label} must resolve to text, not bytes")
+    return result
+
+
+def run(
+    args: Sequence[str | os.PathLike[str]],
+    *,
+    executable: str | os.PathLike[str] | None = None,
+    check: bool = True,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+) -> Result:
+    """Run syq without a shell and capture its complete byte output.
+
+    ``args`` contains only arguments after the executable name. By default the
+    SDK downloads and uses its pinned syq release. Passing ``executable`` opts
+    into an untested custom binary. A missing custom executable, timeout, or
+    other spawn failure is reported by ``subprocess``. A completed nonzero
+    process raises :class:`SyqProcessError` unless ``check`` is false.
+    """
+
+    if isinstance(args, (str, bytes, os.PathLike)):
+        raise TypeError("args must be a sequence of individual arguments")
+    executable_text = (
+        os.fspath(managed_executable())
+        if executable is None
+        else _text_arg(executable, label="executable")
+    )
+    argument_text = tuple(
+        _text_arg(argument, label=f"args[{index}]")
+        for index, argument in enumerate(args)
+    )
+    argv = (executable_text, *argument_text)
+    process = subprocess.Popen(
+        argv,
+        cwd=cwd,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        shell=False,
+        start_new_session=True,
+    )
+    try:
+        stdout, stderr = process.communicate(timeout=timeout)
+    except BaseException:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.communicate()
+        raise
+    result = Result(
+        argv=argv,
+        returncode=process.returncode,
+        stdout=stdout,
+        stderr=stderr,
+    )
+    if check and result.returncode != 0:
+        raise SyqProcessError(result)
+    return result
+
+
+def version(*, executable: str | os.PathLike[str] | None = None) -> str:
+    """Return the version of the pinned or explicitly overridden executable."""
+
+    result = run(["--version"], executable=executable)
+    try:
+        output = result.stdout.decode("utf-8").strip()
+    except UnicodeDecodeError as error:
+        raise SyqOutputError("syq --version did not return UTF-8") from error
+    prefix = "syq "
+    if not output.startswith(prefix) or len(output) == len(prefix):
+        raise SyqOutputError(f"unexpected syq --version output: {output!r}")
+    return output[len(prefix) :]

syq-0.0.1/src/syq/py.typed

@@ -0,0 +1 @@
+

syq-0.0.1/src/syq/syq-release-manifest.json

@@ -0,0 +1,69 @@
+{
+  "artifacts": {
+    "linux-aarch64": {
+      "archive": {
+        "name": "syq-linux-aarch64.gz",
+        "sha256": "949dc1d108ce9d659f9a35354e77afcc582170fc85d20fca20fd163c034e6c7e",
+        "size": 4232034
+      },
+      "binary": {
+        "name": "syq-linux-aarch64",
+        "sha256": "a8b6b0e7602d789668bdd433946144ffa67116f815ed1bf5bea8308f141d6b12",
+        "size": 8798640
+      }
+    },
+    "linux-x86_64": {
+      "archive": {
+        "name": "syq-linux-x86_64.gz",
+        "sha256": "a77c091e8a3d85f6c8d534f66e456ef2095efc7aba64acf1a8a747e3f7937e67",
+        "size": 4650527
+      },
+      "binary": {
+        "name": "syq-linux-x86_64",
+        "sha256": "eaf06c96e851ecd573313832607439a0c8033b6f5f6cca9c3c8b4b081556066d",
+        "size": 10683104
+      }
+    },
+    "macos-arm64": {
+      "archive": {
+        "name": "syq-macos-arm64.gz",
+        "sha256": "99379e50f8787391267b03cd84a0f30b541af8da7fc3bb3dd6b2585b877cd722",
+        "size": 3610717
+      },
+      "binary": {
+        "name": "syq-macos-arm64",
+        "sha256": "acd13c45729625d4ec994f4fbdf0c3b37d1e31ebca0d2e1639a9fa6f78b8aef7",
+        "size": 7858272
+      }
+    },
+    "macos-x86_64": {
+      "archive": {
+        "name": "syq-macos-x86_64.gz",
+        "sha256": "709d9fbb172dc01e4348da44e0af281fe7d03b2e7f2cf9c7fecb7bb95fcec3d4",
+        "size": 3951723
+      },
+      "binary": {
+        "name": "syq-macos-x86_64",
+        "sha256": "1b0c20ae5e213e726c13129c67a598393c2c63af7433b5fd44a2daae91401f2c",
+        "size": 8718620
+      }
+    }
+  },
+  "helper_id": "v0.1.5-p0",
+  "homebrew_formula": {
+    "name": "syq.rb",
+    "sha256": "13e3f5dc3640ada43f5d6c8d335b6ebfce4cedaea8a13e6dc77376b36f2f49a0",
+    "size": 1166
+  },
+  "installer": {
+    "name": "install.sh",
+    "sha256": "e5f083fe911d7b1c0fad1760f4bd0f0971796709e71bc45cce19b17debcf851f",
+    "size": 4931
+  },
+  "repository": "https://github.com/greaber/syq",
+  "schema": 1,
+  "signature": "rf6gNEhMqL93o7bUKQEBJ4U+YKhh19Opvy9yRLq75zJNqBfantuT0Web5WQK/ZLiMmCJUwTNj+O2Z+OEUMtqBA==",
+  "signature_scheme": "ed25519-jcs-v1",
+  "tag": "v0.1.5",
+  "version": "0.1.5"
+}

syq-0.0.1/src/syq.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: syq
+Version: 0.0.1
+Summary: Version-pinned Python adapter for the syq parallel file copier
+Author: Grant Reaber
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/greaber/syq
+Project-URL: Repository, https://github.com/greaber/syq
+Project-URL: Issues, https://github.com/greaber/syq/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# syq for Python
+
+`syq` is the official preview Python adapter for the
+[syq parallel file copier](https://github.com/greaber/syq). It invokes syq with
+an argument array and never constructs a shell command.
+
+```sh
+python -m pip install syq
+```
+
+Package installation does not download an executable. The first call that
+needs syq downloads the exact release pinned by this SDK into the user cache.
+For Python package `0.0.1`, that release is syq `0.1.5`.
+
+```python
+import syq
+
+print(syq.__version__)           # Python package version
+print(syq.PINNED_SYQ_VERSION)    # tested executable version
+print(syq.managed_executable())  # downloads once, then returns the cached path
+
+plan = syq.run([
+    "cp",
+    "project",
+    "--to",
+    "server",
+    "--into",
+    "/backup",
+    "--dry-run",
+])
+print(plan.stdout.decode())
+```
+
+The managed executable is stored below
+`$XDG_CACHE_HOME/syq/sdk/python/v0.1.5/` or, when `XDG_CACHE_HOME` is not an
+absolute path, `~/.cache/syq/sdk/python/v0.1.5/`. The SDK checks the complete
+cached binary against its embedded release manifest before every use. A corrupt
+or missing cache entry is replaced atomically with a freshly downloaded,
+verified binary.
+
+`run()` raises `SyqProcessError` for a nonzero process status by default. The
+exception retains the complete result, including stdout and stderr as bytes.
+Pass `check=False` when the caller wants to interpret the status directly.
+When `timeout` expires or the caller is interrupted, the SDK kills and reaps
+syq's local process group, including child processes such as SSH transports,
+before propagating the exception.
+
+## Custom executable override
+
+An explicit executable bypasses the managed version:
+
+```python
+result = syq.run(["--help"], executable="/opt/custom/bin/syq")
+custom_version = syq.version(executable="syq")  # intentional PATH lookup
+```
+
+The SDK makes no compatibility or provenance guarantee for an override. Use it
+for local development, controlled offline provisioning, or when deliberately
+testing a different syq release.
+
+The package targets Python 3.10 or newer on Linux and macOS and has no runtime
+Python dependencies. See the [SDK compatibility policy](../README.md) for the
+release mapping.

syq-0.0.1/src/syq.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/syq/__init__.py
+src/syq/bootstrap.py
+src/syq/client.py
+src/syq/py.typed
+src/syq/syq-release-manifest.json
+src/syq.egg-info/PKG-INFO
+src/syq.egg-info/SOURCES.txt
+src/syq.egg-info/dependency_links.txt
+src/syq.egg-info/top_level.txt
+tests/test_bootstrap.py
+tests/test_candidate.py
+tests/test_client.py

syq-0.0.1/src/syq.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

syq-0.0.1/src/syq.egg-info/top_level.txt

@@ -0,0 +1 @@
+syq

syq-0.0.1/tests/test_bootstrap.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import syq
+from syq import bootstrap
+
+
+FAKE_BINARY = b"""#!/bin/sh
+case "$1" in
+  --version) printf 'syq 9.8.7\\n' ;;
+  --build-identity) printf 'v9.8.7\\n' ;;
+  *) exit 2 ;;
+esac
+"""
+FAKE_ARCHIVE = gzip.compress(FAKE_BINARY, mtime=0)
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _release(binary_bytes: bytes = FAKE_BINARY) -> dict[str, object]:
+    archive_bytes = gzip.compress(binary_bytes, mtime=0)
+    return {
+        "repository": "https://github.com/greaber/syq",
+        "tag": "v9.8.7",
+        "version": "9.8.7",
+        "artifacts": {
+            "linux-x86_64": {
+                "archive": {
+                    "name": "syq-linux-x86_64.gz",
+                    "sha256": _sha256(archive_bytes),
+                    "size": len(archive_bytes),
+                },
+                "binary": {
+                    "name": "syq-linux-x86_64",
+                    "sha256": _sha256(binary_bytes),
+                    "size": len(binary_bytes),
+                },
+            }
+        },
+    }
+
+
+class _Response(io.BytesIO):
+    def geturl(self) -> str:
+        return "https://release-assets.githubusercontent.com/pinned"
+
+    def __enter__(self) -> _Response:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class BootstrapTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory()
+        self.cache = Path(self.temporary_directory.name)
+
+    def tearDown(self) -> None:
+        self.temporary_directory.cleanup()
+
+    def _patch_release(self) -> tuple[mock._patch, mock._patch]:
+        return (
+            mock.patch.object(
+                bootstrap, "_load_release_manifest", return_value=_release()
+            ),
+            mock.patch.object(bootstrap, "_host_target", return_value="linux-x86_64"),
+        )
+
+    def test_package_pin_matches_embedded_manifest(self) -> None:
+        manifest_path = Path(bootstrap.__file__).with_name("syq-release-manifest.json")
+        manifest = json.loads(manifest_path.read_bytes())
+        self.assertEqual(syq.PINNED_SYQ_VERSION, manifest["version"])
+
+    def test_downloads_validates_and_reuses_the_exact_binary(self) -> None:
+        manifest_patch, target_patch = self._patch_release()
+        download = mock.Mock(side_effect=lambda *args, **kwargs: _Response(FAKE_ARCHIVE))
+        with manifest_patch, target_patch, mock.patch.object(
+            bootstrap.urllib.request, "urlopen", download
+        ):
+            first = bootstrap.managed_executable(cache_dir=self.cache)
+            second = bootstrap.managed_executable(cache_dir=self.cache)
+
+        self.assertEqual(first, second)
+        self.assertEqual(first.read_bytes(), FAKE_BINARY)
+        self.assertTrue(first.stat().st_mode & 0o100)
+        self.assertEqual(download.call_count, 1)
+
+    def test_corrupt_cached_binary_is_replaced(self) -> None:
+        manifest_patch, target_patch = self._patch_release()
+        download = mock.Mock(side_effect=lambda *args, **kwargs: _Response(FAKE_ARCHIVE))
+        with manifest_patch, target_patch, mock.patch.object(
+            bootstrap.urllib.request, "urlopen", download
+        ):
+            executable = bootstrap.managed_executable(cache_dir=self.cache)
+            executable.write_bytes(b"tampered")
+            repaired = bootstrap.managed_executable(cache_dir=self.cache)
+
+        self.assertEqual(repaired.read_bytes(), FAKE_BINARY)
+        self.assertEqual(download.call_count, 2)
+
+    def test_corrupt_download_is_rejected_without_installing(self) -> None:
+        manifest_patch, target_patch = self._patch_release()
+        corrupted = bytes([FAKE_ARCHIVE[0] ^ 1]) + FAKE_ARCHIVE[1:]
+        with manifest_patch, target_patch, mock.patch.object(
+            bootstrap.urllib.request,
+            "urlopen",
+            return_value=_Response(corrupted),
+        ):
+            with self.assertRaisesRegex(syq.SyqInstallError, "SHA-256"):
+                bootstrap.managed_executable(cache_dir=self.cache)
+
+        install_dir = (
+            self.cache / "syq" / "sdk" / "python" / "v9.8.7" / "linux-x86_64"
+        )
+        self.assertEqual(list(install_dir.iterdir()), [])
+
+    def test_hash_valid_binary_with_wrong_release_identity_is_rejected(self) -> None:
+        wrong_binary = FAKE_BINARY.replace(b"v9.8.7", b"source-build")
+        wrong_archive = gzip.compress(wrong_binary, mtime=0)
+        with mock.patch.object(
+            bootstrap, "_load_release_manifest", return_value=_release(wrong_binary)
+        ), mock.patch.object(
+            bootstrap, "_host_target", return_value="linux-x86_64"
+        ), mock.patch.object(
+            bootstrap.urllib.request,
+            "urlopen",
+            return_value=_Response(wrong_archive),
+        ):
+            with self.assertRaisesRegex(syq.SyqInstallError, "build identity"):
+                bootstrap.managed_executable(cache_dir=self.cache)
+
+    def test_supported_host_aliases_select_release_targets(self) -> None:
+        cases = [
+            ("Linux", "x86_64", "linux-x86_64"),
+            ("Linux", "arm64", "linux-aarch64"),
+            ("Darwin", "arm64", "macos-arm64"),
+            ("Darwin", "amd64", "macos-x86_64"),
+        ]
+        for system, machine, expected in cases:
+            with self.subTest(system=system, machine=machine), mock.patch.object(
+                bootstrap.platform, "system", return_value=system
+            ), mock.patch.object(
+                bootstrap.platform, "machine", return_value=machine
+            ):
+                self.assertEqual(bootstrap._host_target(), expected)
+
+    def test_unsupported_host_fails_before_downloading(self) -> None:
+        with mock.patch.object(
+            bootstrap.platform, "system", return_value="Windows"
+        ), mock.patch.object(
+            bootstrap.platform, "machine", return_value="x86_64"
+        ), self.assertRaisesRegex(syq.SyqInstallError, "no binary"):
+            bootstrap.managed_executable(cache_dir=self.cache)
+
+
+if __name__ == "__main__":
+    unittest.main()

syq-0.0.1/tests/test_candidate.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+import syq
+
+
+EXECUTABLE = os.environ.get("SYQ_CANDIDATE_EXECUTABLE")
+EXPECTED_VERSION = os.environ.get("SYQ_CANDIDATE_VERSION")
+
+
+@unittest.skipUnless(
+    EXECUTABLE and EXPECTED_VERSION,
+    "candidate compatibility requires SYQ_CANDIDATE_EXECUTABLE and version",
+)
+class CandidateCompatibilityTests(unittest.TestCase):
+    def test_candidate_version_and_local_copy(self) -> None:
+        assert EXECUTABLE is not None
+        assert EXPECTED_VERSION is not None
+        executable = Path(EXECUTABLE)
+        self.assertEqual(syq.version(executable=executable), EXPECTED_VERSION)
+
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            root = Path(temporary_directory)
+            source = root / "source; $(not-a-command)"
+            destination = root / "destination"
+            source.write_bytes(b"candidate compatibility\n")
+
+            result = syq.run(
+                ["cp", source, "--as-new", destination, "--quiet"],
+                executable=executable,
+            )
+
+            self.assertEqual(result.returncode, 0)
+            self.assertEqual(destination.read_bytes(), source.read_bytes())
+
+    def test_candidate_failure_is_retained(self) -> None:
+        assert EXECUTABLE is not None
+        result = syq.run(
+            ["not-a-syq-command"],
+            executable=EXECUTABLE,
+            check=False,
+        )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertTrue(result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

syq-0.0.1/tests/test_client.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import syq
+
+
+FAKE_SYQ = """#!/bin/sh
+case "$1" in
+  --version)
+    printf 'syq 9.8.7\\n'
+    ;;
+  emit)
+    printf '%s' "$2"
+    printf 'diagnostic' >&2
+    ;;
+  fail)
+    printf 'partial'
+    printf 'failed' >&2
+    exit 23
+    ;;
+  spawn-descendant)
+    (
+      printf 'ready' > "$2.ready"
+      sleep 1
+      printf 'survived' > "$2"
+    ) &
+    while [ ! -f "$2.ready" ]; do
+      sleep 0.01
+    done
+    sleep 30
+    ;;
+  interrupt)
+    printf '%s' "$$" > "$2.pid"
+    (
+      printf 'ready' > "$2.ready"
+      sleep 1
+      printf 'survived' > "$2"
+    ) &
+    while [ ! -f "$2.ready" ]; do
+      sleep 0.01
+    done
+    sleep 3
+    ;;
+  *)
+    exit 2
+    ;;
+esac
+"""
+
+
+class ClientTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory()
+        self.executable = Path(self.temporary_directory.name) / "syq"
+        self.executable.write_text(FAKE_SYQ, encoding="utf-8")
+        self.executable.chmod(0o755)
+
+    def tearDown(self) -> None:
+        self.temporary_directory.cleanup()
+
+    def test_custom_executable_version_can_differ_from_package(self) -> None:
+        self.assertRegex(syq.__version__, r"^\d+\.\d+\.\d+$")
+        self.assertEqual(syq.version(executable=self.executable), "9.8.7")
+
+    def test_run_preserves_one_argument_with_shell_metacharacters(self) -> None:
+        argument = "a path; $(not-a-command)"
+        result = syq.run(["emit", argument], executable=self.executable)
+        self.assertEqual(result.argv, (os.fspath(self.executable), "emit", argument))
+        self.assertEqual(result.stdout, argument.encode())
+        self.assertEqual(result.stderr, b"diagnostic")
+
+    def test_default_run_uses_the_managed_executable(self) -> None:
+        with mock.patch(
+            "syq.client.managed_executable", return_value=self.executable
+        ) as managed:
+            result = syq.run(["emit", "managed"])
+
+        managed.assert_called_once_with()
+        self.assertEqual(result.stdout, b"managed")
+
+    def test_explicit_executable_bypasses_the_managed_install(self) -> None:
+        with mock.patch(
+            "syq.client.managed_executable",
+            side_effect=AssertionError("managed install should not run"),
+        ):
+            result = syq.run(["emit", "custom"], executable=self.executable)
+
+        self.assertEqual(result.stdout, b"custom")
+
+    def test_nonzero_result_is_retained(self) -> None:
+        with self.assertRaises(syq.SyqProcessError) as caught:
+            syq.run(["fail"], executable=self.executable)
+
+        self.assertEqual(caught.exception.result.returncode, 23)
+        self.assertEqual(caught.exception.result.stdout, b"partial")
+        self.assertEqual(caught.exception.result.stderr, b"failed")
+
+    def test_nonzero_result_can_be_returned(self) -> None:
+        result = syq.run(["fail"], executable=self.executable, check=False)
+        self.assertEqual(result.returncode, 23)
+
+    def test_timeout_stops_spawned_descendants(self) -> None:
+        marker = Path(self.temporary_directory.name) / "descendant-marker"
+
+        with self.assertRaises(subprocess.TimeoutExpired):
+            syq.run(
+                ["spawn-descendant", marker],
+                executable=self.executable,
+                timeout=0.5,
+            )
+
+        self.assertTrue(marker.with_suffix(".ready").exists())
+        time.sleep(0.75)
+        self.assertFalse(marker.exists())
+
+    def test_keyboard_interrupt_stops_spawned_descendants(self) -> None:
+        marker = Path(self.temporary_directory.name) / "interrupt-marker"
+        ready = marker.with_suffix(".ready")
+        pid_file = marker.with_suffix(".pid")
+        script = (
+            "from pathlib import Path\n"
+            "import sys\n"
+            "import syq\n"
+            "syq.run(['interrupt', Path(sys.argv[2])], "
+            "executable=Path(sys.argv[1]))\n"
+        )
+        wrapper = subprocess.Popen(
+            [
+                sys.executable,
+                "-c",
+                script,
+                os.fspath(self.executable),
+                os.fspath(marker),
+            ],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+
+        try:
+            deadline = time.monotonic() + 3
+            while not ready.exists() and wrapper.poll() is None:
+                if time.monotonic() >= deadline:
+                    self.fail(
+                        "timed out waiting for the interrupt fixture; "
+                        f"wrapper status is {wrapper.returncode}"
+                    )
+                time.sleep(0.01)
+            self.assertIsNone(wrapper.poll())
+
+            wrapper.send_signal(signal.SIGINT)
+            wrapper.communicate(timeout=3)
+
+            self.assertNotEqual(wrapper.returncode, 0)
+            time.sleep(1.1)
+            self.assertFalse(marker.exists())
+        finally:
+            if wrapper.poll() is None:
+                wrapper.kill()
+                wrapper.communicate()
+            if pid_file.exists():
+                try:
+                    os.killpg(int(pid_file.read_text(encoding="utf-8")), signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+
+    def test_one_string_is_not_treated_as_an_argument_sequence(self) -> None:
+        with self.assertRaisesRegex(TypeError, "individual arguments"):
+            syq.run("emit", executable=self.executable)
+
+
+if __name__ == "__main__":
+    unittest.main()