pypilot-cli 1.3.0__py3-none-win_amd64.whl

pypilot/__init__.py

@@ -0,0 +1,34 @@
+"""
+PyPilot — Deterministic Python environment doctor and dependency manager.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.3.0"
+
+from .api import RunResult, arun, run  # noqa: E402
+from .engine import (  # noqa: E402
+    EngineDownloadError,
+    EngineError,
+    EngineInfo,
+    EngineNotFoundError,
+    EngineVerificationError,
+    ensure_binary,
+    get_cache_dir,
+    locate_engine,
+)
+
+__all__ = [
+    "EngineDownloadError",
+    "EngineError",
+    "EngineInfo",
+    "EngineNotFoundError",
+    "EngineVerificationError",
+    "RunResult",
+    "__version__",
+    "arun",
+    "ensure_binary",
+    "get_cache_dir",
+    "locate_engine",
+    "run",
+]

pypilot/api.py

@@ -0,0 +1,151 @@
+"""
+pypilot.api: run the engine from Python.
+
+`run` keeps its old behaviour: it returns a `subprocess.CompletedProcess`
+(now the `RunResult` subclass, which adds `.ok` and `.json()`), never raises
+for a non-zero exit unless `check=True`, and leaves output on the terminal
+unless `capture_output=True`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json as _json
+import subprocess
+from typing import TYPE_CHECKING, Any, List, Mapping, Optional, Sequence
+
+from .engine import StrPath, ensure_binary
+
+if TYPE_CHECKING:
+    _CompletedProcess = subprocess.CompletedProcess[str]
+else:
+    # Not subscriptable at runtime before Python 3.9.
+    _CompletedProcess = subprocess.CompletedProcess
+
+# The engine always writes UTF-8, whatever the locale says.
+_ENCODING = "utf-8"
+_ERRORS = "replace"
+
+
+class RunResult(_CompletedProcess):
+    """The outcome of one engine invocation.
+
+    A `subprocess.CompletedProcess`, so existing code using `.returncode`,
+    `.stdout`, `.stderr`, `.args` or `.check_returncode()` keeps working.
+    """
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    def json(self) -> Any:
+        """Parse the `--json` output of a command.
+
+        Every command's JSON has the shape
+        `{"pypilot": ..., "command": ..., "ok": ..., ...}`. Requires
+        `capture_output=True`.
+        """
+        if self.stdout is None:
+            raise ValueError("stdout was not captured; call run(..., capture_output=True)")
+        return _json.loads(self.stdout)
+
+
+def _command(args: Optional[Sequence[str]]) -> List[str]:
+    if isinstance(args, str):
+        raise TypeError("args must be a list of strings, e.g. ['doctor', '--json']")
+    return [str(ensure_binary()), *(args or [])]
+
+
+async def _kill(proc: asyncio.subprocess.Process) -> None:
+    if proc.returncode is None:
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+    # Read the pipes to EOF, not just wait(): otherwise the loop can close
+    # with their transports still open (a ResourceWarning on Windows 3.8).
+    await proc.communicate()
+
+
+def run(
+    args: Optional[Sequence[str]] = None,
+    capture_output: bool = False,
+    check: bool = False,
+    *,
+    cwd: Optional[StrPath] = None,
+    env: Optional[Mapping[str, str]] = None,
+    input: Optional[str] = None,
+    timeout: Optional[float] = None,
+) -> RunResult:
+    """
+    Run PyPilot programmatically.
+
+    Example:
+        import pypilot
+        res = pypilot.run(["doctor", "--json"], capture_output=True)
+        report = res.json()
+
+    `check=True` raises `subprocess.CalledProcessError` on a non-zero exit.
+    """
+    cmd = _command(args)
+    proc = subprocess.run(
+        cmd,
+        capture_output=capture_output,
+        encoding=_ENCODING,
+        errors=_ERRORS,
+        check=False,
+        cwd=cwd,
+        env=dict(env) if env is not None else None,
+        input=input,
+        timeout=timeout,
+    )
+    result = RunResult(proc.args, proc.returncode, proc.stdout, proc.stderr)
+    if check:
+        result.check_returncode()
+    return result
+
+
+async def arun(
+    args: Optional[Sequence[str]] = None,
+    capture_output: bool = False,
+    check: bool = False,
+    *,
+    cwd: Optional[StrPath] = None,
+    env: Optional[Mapping[str, str]] = None,
+    input: Optional[str] = None,
+    timeout: Optional[float] = None,
+) -> RunResult:
+    """`run`, without blocking the event loop.
+
+    Locating (and possibly downloading) the engine happens in a worker thread.
+    On timeout the engine is killed and `subprocess.TimeoutExpired` raised.
+    """
+    loop = asyncio.get_running_loop()
+    cmd = await loop.run_in_executor(None, _command, args)
+    pipe = asyncio.subprocess.PIPE if capture_output else None
+    proc = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdin=asyncio.subprocess.PIPE if input is not None else None,
+        stdout=pipe,
+        stderr=pipe,
+        cwd=cwd,
+        env=dict(env) if env is not None else None,
+    )
+    data = input.encode(_ENCODING) if input is not None else None
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(data), timeout)
+    except asyncio.TimeoutError:
+        await _kill(proc)
+        raise subprocess.TimeoutExpired(cmd, timeout or 0) from None
+    except asyncio.CancelledError:
+        await _kill(proc)
+        raise
+
+    def decode(raw: Optional[bytes]) -> Optional[str]:
+        return raw.decode(_ENCODING, _ERRORS) if raw is not None else None
+
+    assert proc.returncode is not None
+    result = RunResult(cmd, proc.returncode, decode(out), decode(err))
+    if check:
+        result.check_returncode()
+    return result

pypilot/binary.py

@@ -0,0 +1,90 @@
+"""
+pypilot.binary: the engine pin, plus the names this module used to define.
+
+`DEFAULT_TAG` and `ENGINE_SHA256` are a contract with the release-coordination
+workflow, which bumps exactly these two assignments in this file when a new
+engine ships. Keep them literal, one asset per line, so a plain text edit can
+update them.
+
+The locate/download code moved to `pypilot.engine`; the old names stay
+importable from here (`from pypilot.binary import ensure_binary` still works).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Tuple
+
+GITHUB_REPO = "pypilot-dev/pypilot"
+
+# The engine release this package is pinned to.
+DEFAULT_TAG = "v1.3.0"
+
+# SHA-256 of every release asset of DEFAULT_TAG. A download is checked against
+# this before it is extracted or run.
+ENGINE_SHA256: Dict[str, str] = {
+    "pypilot-darwin-arm64.tar.gz": "7e8c76180d704b3f887a078e8225ee9c9b26720607234afe4cdaab637a8b8ba7",
+    "pypilot-darwin-x64.tar.gz": "0ea5d56780500ba19edb94c992629bed5304d4bc53084434e98ed4747d6a4432",
+    "pypilot-linux-x64.tar.gz": "9b225dd1015ce32f329413e455f593b6090eb0e6f6a2d85ef8edd597bf1afe32",
+    "pypilot-windows-x64.zip": "aab0efddd8abf984696055a8608624c68309909e8aaddd21784a8dc4f3db5a58",
+}
+
+# Oldest helper accepted from ~/.cargo/bin or PATH.
+MIN_VERSION: Tuple[int, int, int] = (1, 0, 2)
+
+# The release this package ships with. A cached download older than this is
+# replaced, so upgrading the pip package also upgrades the engine.
+_major, _minor, _patch = (int(p) for p in DEFAULT_TAG.lstrip("v").split("."))
+BUNDLED_VERSION: Tuple[int, int, int] = (_major, _minor, _patch)
+
+_MOVED = (
+    "binary_name",
+    "download_binary",
+    "ensure_binary",
+    "extract_archive",
+    "get_cache_dir",
+    "get_platform_slug",
+    "install_binary",
+    "parse_version",
+    "probe_binary",
+)
+
+if TYPE_CHECKING:
+    from .engine import (
+        binary_name,
+        download_binary,
+        ensure_binary,
+        extract_archive,
+        get_cache_dir,
+        get_platform_slug,
+        install_binary,
+        parse_version,
+        probe_binary,
+    )
+
+
+def __getattr__(name: str) -> Any:
+    # Resolved lazily: `pypilot.engine` imports the pin from this module, so an
+    # eager import here would be circular.
+    if name in _MOVED:
+        from . import engine
+
+        return getattr(engine, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "BUNDLED_VERSION",
+    "DEFAULT_TAG",
+    "ENGINE_SHA256",
+    "GITHUB_REPO",
+    "MIN_VERSION",
+    "binary_name",
+    "download_binary",
+    "ensure_binary",
+    "extract_archive",
+    "get_cache_dir",
+    "get_platform_slug",
+    "install_binary",
+    "parse_version",
+    "probe_binary",
+]

pypilot/cli.py

@@ -0,0 +1,117 @@
+"""
+pypilot.cli: the `pypilot` command.
+
+Every argument is passed to the native engine unchanged (including
+`pypilot completions <shell>`), except a lone `--version` / `-V`, which the
+wrapper answers itself so it can also report its own version and any skew
+between the wrapper and the engine it found.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .binary import BUNDLED_VERSION, DEFAULT_TAG
+from .engine import (
+    SOURCE_CARGO,
+    SOURCE_OVERRIDE,
+    SOURCE_PATH,
+    EngineInfo,
+    Version,
+    ensure_binary,
+    locate_engine,
+    parse_version,
+)
+
+_VERSION_FLAGS = (["--version"], ["-V"])
+
+
+def _fmt(version: Version) -> str:
+    return ".".join(map(str, version))
+
+
+def skew_warnings(info: EngineInfo, version: Optional[Version]) -> List[str]:
+    """Why the engine in use may not be the one this package was released with."""
+    if info.source == SOURCE_OVERRIDE:
+        return []
+    if version is None:
+        return [f"could not read a version from the engine at {info.path}"]
+    where = {SOURCE_CARGO: "~/.cargo/bin", SOURCE_PATH: "PATH"}.get(info.source)
+    warnings: List[str] = []
+    if version < BUNDLED_VERSION:
+        warnings.append(
+            f"engine {_fmt(version)} is older than {DEFAULT_TAG}, the release "
+            f"pypilot-cli {__version__} pins; newer commands may be missing"
+        )
+    if where is not None and version != BUNDLED_VERSION:
+        warnings.append(
+            f"using the engine from {where} ({info.path}) instead of the pinned "
+            f"{DEFAULT_TAG}; update or remove it to use the pinned engine"
+        )
+    return warnings
+
+
+def print_version() -> int:
+    """`pypilot --version`.
+
+    stdout carries only the engine's own `pypilot X.Y.Z` line, because editor
+    extensions run `pypilot --version` and parse exactly that. The wrapper's
+    version and any warnings go to stderr.
+    """
+    try:
+        info = locate_engine()
+    except Exception as e:
+        print(f"pypilot-cli {__version__}", file=sys.stderr)
+        print(f"Error: failed to locate or download PyPilot native engine: {e}", file=sys.stderr)
+        return 1
+    try:
+        res = subprocess.run(
+            [str(info.path), "--version"],
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        print(f"pypilot-cli {__version__}", file=sys.stderr)
+        print(f"Error: could not run the engine at {info.path}: {e}", file=sys.stderr)
+        return 1
+
+    line = res.stdout.strip()
+    if res.returncode != 0 or not line:
+        sys.stderr.write(res.stderr)
+        print(f"pypilot-cli {__version__}", file=sys.stderr)
+        print(f"Error: `{info.path} --version` failed", file=sys.stderr)
+        return res.returncode or 1
+
+    print(line, flush=True)
+    print(f"pypilot-cli {__version__} (engine: {info.source}, {info.path})", file=sys.stderr)
+    for warning in skew_warnings(info, parse_version(line)):
+        print(f"warning: {warning}", file=sys.stderr)
+    return 0
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args in _VERSION_FLAGS:
+        sys.exit(print_version())
+
+    try:
+        bin_path = ensure_binary()
+    except Exception as e:
+        print(f"Error: failed to locate or download PyPilot native engine: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        proc = subprocess.run([str(bin_path), *args])
+        sys.exit(proc.returncode)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()