bex-hooks-python 0.1.0__py3-none-any.whl

bex_hooks/hooks/python/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from bex_hooks.hooks.python.setup import setup_python
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from bex_hooks.hooks.python._interface import HookFunc
+
+
+def get_hooks() -> Mapping[str, HookFunc]:
+    return {
+        "python/setup-python": setup_python,
+    }

bex_hooks/hooks/python/_interface.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, NoReturn, Protocol, Self, TypeGuard
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from types import TracebackType
+
+
+# --- Helpers ---
+@dataclass(frozen=True)
+class Context:
+    working_dir: str
+    metadata: Mapping[str, Any]
+    environ: Mapping[str, str]
+
+
+def is_token_cancelled(
+    token: CancellationToken,
+) -> TypeGuard[CancelledCancellationToken]:
+    return token.is_cancelled()
+
+
+# --- Typing ---
+class HookFunc(Protocol):
+    def __call__(
+        self,
+        token: CancellationToken,
+        args: Mapping[str, Any],
+        ctx: ContextLike,
+        *,
+        ui: UI,
+    ) -> ContextLike: ...
+
+
+class ContextLike(Protocol):
+    @property
+    def working_dir(self) -> str: ...
+    @property
+    def metadata(self) -> Mapping[str, Any]: ...
+    @property
+    def environ(self) -> Mapping[str, str]: ...
+
+
+class CancellationToken(Protocol):
+    def register(self, fn: Callable[[Exception], None]) -> None: ...
+    def is_cancelled(self) -> bool: ...
+    def get_error(self) -> Exception | None: ...
+    def raise_if_cancelled(self): ...
+    def wait(self, timeout: float | None) -> Exception | None: ...
+
+
+class CancelledCancellationToken(CancellationToken, Protocol):
+    def is_cancelled(self) -> Literal[True]: ...
+    def get_error(self) -> Exception: ...
+    def raise_if_cancelled(self) -> NoReturn: ...
+    def wait(self, timeout: float | None) -> Exception: ...
+
+
+class UI(Protocol):
+    def scope(self, status: str) -> UIScope: ...
+    def progress(self) -> UIProgress: ...
+    def log(self, *objects: Any, end: str = "\n") -> None: ...
+    def print(self, *objects: Any, end: str = "\n") -> None: ...
+
+
+class UIScope(Protocol):
+    def update(self, status: str | None) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None: ...
+
+
+class UIProgress(Protocol):
+    def add_task(self, description: str, /, *, total: float | None = None) -> Any: ...
+    def update(
+        self,
+        token: Any,
+        /,
+        *,
+        description: str | None = None,
+        total: float | None = None,
+        completed: float | None = None,
+        advance: float | None = None,
+    ) -> None: ...
+    def advance(self, token: Any, advance: float) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None: ...

bex_hooks/hooks/python/setup.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+import datetime as dt
+import glob
+import itertools
+import logging
+import platform
+import stat
+import subprocess
+import sys
+import sysconfig
+import tarfile
+import zipfile
+from collections import defaultdict
+from pathlib import Path
+from string import Template
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urljoin
+
+import httpx
+from pydantic import BaseModel, Field
+
+from bex_hooks.hooks.python._interface import Context
+from bex_hooks.hooks.python.utils import (
+    append_path,
+    download_file,
+    prepend_path,
+    wait_process,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from bex_hooks.hooks.python._interface import UI, CancellationToken, ContextLike
+
+_UV_RELEASES_URL = "https://api.github.com/repos/astral-sh/uv/releases"
+_UV_DOWNLOAD_URL = "https://github.com/astral-sh/uv/releases/download/{version}/"
+
+
+class _Args(BaseModel):
+    version: str
+    uv_version: str | None = Field(default=None, alias="uv")
+    requirements: str = Field(default="")
+    requirements_file: list[str] = Field(default_factory=list)
+    activate_env: bool = Field(default=False)
+    set_python_path: bool = Field(default=False)
+    inexact: bool = Field(default=False)
+
+
+def setup_python(
+    token: CancellationToken, args: Mapping[str, Any], ctx: ContextLike, *, ui: UI
+) -> ContextLike:
+    data = _Args.model_validate(args, from_attributes=False)
+
+    bex_dir = Path(ctx.working_dir) / ".bex"
+    root_dir = Path(ctx.working_dir) / "python"
+    root_dir.mkdir(exist_ok=True)
+
+    uv = _download_uv(token, ui, bex_dir / "cache" / "uv", version=data.uv_version)
+    if uv is None:
+        msg = "Failed to download uv"
+        raise RuntimeError(msg)
+
+    req_files = list(
+        itertools.chain(
+            *[
+                glob.iglob(
+                    Template(file).substitute(
+                        {
+                            "working_dir": ctx.working_dir,
+                            "metadata": ctx.metadata,
+                            "environ": ctx.environ,
+                        }
+                    ),
+                    recursive=True,
+                )
+                for file in data.requirements_file
+            ]
+        )
+    )
+    for file in req_files:
+        ui.log("Discovered requirement file: {}".format(file))
+
+    python_bin = _create_isolated_environment(
+        token,
+        ctx,
+        root_dir,
+        uv,
+        data.version,
+        data.requirements,
+        req_files,
+        data.inexact,
+        ui,
+    )
+    if python_bin is None:
+        msg = "Failed to create python virtual environment"
+        raise RuntimeError(msg)
+
+    # Configure PYTHONPATH environment variables
+    _python_path = _get_python_path(python_bin)
+
+    _metadata = dict(ctx.metadata)
+    _environ = dict(ctx.environ)
+    _metadata["python_bin"] = str(python_bin)
+
+    venv_dir = root_dir / ".venv"
+    if data.activate_env is True:
+        _environ["VIRTUAL_ENV"] = str(venv_dir)
+        _environ["VENV_DIR"] = str(venv_dir)
+        _environ["PATH"] = prepend_path(
+            _environ["PATH"],
+            str(venv_dir / ("Scripts" if platform.system() == "Windows" else "bin")),
+        )
+        _environ["VIRTUAL_ENV_PROMPT"] = Path(ctx.working_dir).name
+        if "PYTHONHOME" in _environ:
+            del _environ["PYTHONHOME"]
+
+    if data.set_python_path is True and _python_path:
+        _environ["PYTHONPATH"] = append_path(
+            _environ.get("PYTHONPATH", ""), str(Path(_python_path))
+        )
+
+    return Context(ctx.working_dir, _metadata, _environ)
+
+
+def _create_isolated_environment(
+    token: CancellationToken,
+    ctx: ContextLike,
+    root_dir: Path,
+    uv_bin: Path,
+    python_specifier: str,
+    requirements: str,
+    req_files: Iterable[str],
+    inexact: bool,  # noqa: FBT001
+    ui: UI,
+):
+    logger = logging.getLogger("bex_hooks.hooks.python")
+
+    venv_dir = root_dir / ".venv"
+    requirements_in = root_dir / "requirements.in"
+    requirements_txt = root_dir / "requirements.txt"
+    python_bin = (
+        venv_dir
+        / ("Scripts" if platform.system() == "Windows" else "bin")
+        / ("python.exe" if platform.system() == "Windows" else "python")
+    )
+    with ui.scope("[not dim]Updating virtual environment[/not dim]"):
+        create_venc_rc = wait_process(
+            token,
+            [
+                str(uv_bin),
+                "venv",
+                "--allow-existing",
+                "--no-project",
+                "--seed",
+                "--python",
+                python_specifier,
+                "--python-preference",
+                "only-managed",
+                str(venv_dir),
+            ],
+            callback=logger.debug,
+        )
+        if create_venc_rc != 0:
+            return None
+
+        logger.info("Refreshed virtual environment")
+
+        full_requirements = requirements
+        for file in req_files:
+            full_requirements += "\n" + Path(file).read_text()
+
+        requirements_in.write_bytes(
+            Template(full_requirements)
+            .substitute(
+                {
+                    "working_dir": ctx.working_dir,
+                    "metadata": ctx.metadata,
+                    "environ": ctx.environ,
+                }
+            )
+            .encode("utf-8")
+        )
+
+        lock_pip_requirements_rc = wait_process(
+            token,
+            [
+                str(uv_bin),
+                "pip",
+                "compile",
+                "--python",
+                str(python_bin),
+                "--emit-index-url",
+                str(requirements_in),
+                "-o",
+                str(requirements_txt),
+            ],
+            callback=logger.debug,
+        )
+        if lock_pip_requirements_rc != 0:
+            return None
+
+        logger.info("Locked dependencies")
+
+        sync_pip_requirements_rc = wait_process(
+            token,
+            [
+                str(uv_bin),
+                "pip",
+                "install",
+                "--python",
+                str(python_bin),
+            ]
+            + (["--exact"] if inexact is False else [])
+            + [
+                "-r",
+                str(requirements_txt),
+            ],
+            callback=logger.debug,
+        )
+        if sync_pip_requirements_rc != 0:
+            return None
+
+        logger.info("Synced dependencies")
+
+    return python_bin
+
+
+def _download_uv(
+    token: CancellationToken,
+    ui: UI,
+    directory: Path,
+    *,
+    version: str | None = None,
+):
+    logger = logging.getLogger("bex_hooks.hooks.python")
+
+    if version is None:
+        version = _get_uv_latest_version()
+    if version is None:
+        return None
+
+    logger.info("Resolved uv version to %s", version)
+
+    exe = ".exe" if sys.platform == "win32" else ""
+    uv_bin = directory / f"uv-{version}{exe}"
+    if uv_bin.exists():
+        return uv_bin
+
+    filename, target = _get_uv_release_info()
+    if filename is None or target is None:
+        return None
+
+    with ui.progress() as pb:
+        task_id = pb.add_task(f"Downloading uv {version}")
+        temp_filename = download_file(
+            token,
+            urljoin(_UV_DOWNLOAD_URL.format(version=version), filename),
+            report_hook=lambda curr, total: pb.update(
+                task_id, total=total, completed=curr
+            ),
+        )
+
+    try:
+        if filename.endswith(".zip"):
+            with (
+                zipfile.ZipFile(temp_filename, "r") as archive,
+                archive.open(archive.getinfo(f"uv{exe}")) as source,
+                open(uv_bin, "wb") as target_file,
+            ):
+                target_file.write(source.read())
+        else:
+            with tarfile.open(temp_filename, "r:gz") as archive:
+                source = archive.extractfile(f"{target}/uv{exe}")
+                if source is None:
+                    msg = "Failed to extract uv from archive"
+                    raise RuntimeError(msg)
+
+                with (
+                    source,
+                    open(uv_bin, "wb") as target_file,
+                ):
+                    target_file.write(source.read())
+
+        uv_bin.chmod(uv_bin.stat().st_mode | stat.S_IXUSR)
+        return uv_bin
+    finally:
+        _path = Path(temp_filename)
+        if _path.exists():
+            _path.unlink()
+
+
+def _get_python_path(python_bin: Path):
+    try:
+        _output = subprocess.check_output(
+            [
+                str(python_bin),
+                "-c",
+                "import sysconfig;print(sysconfig.get_paths()['purelib'])",
+            ],
+            shell=False,
+            text=True,
+            stderr=subprocess.STDOUT,
+        )
+    except subprocess.CalledProcessError:
+        return None
+    else:
+        if _output[-1:] == "\n":
+            _output = _output[:-1]
+        return _output
+
+
+def _get_uv_latest_version() -> str | None:
+    response = httpx.get(_UV_RELEASES_URL).json()
+    releases = (
+        (entry["name"], dt.datetime.fromisoformat(entry["published_at"]))
+        for entry in response
+        if entry["draft"] is False and entry["prerelease"] is False
+    )
+    return next(
+        iter(sorted(releases, key=lambda entry: entry[1], reverse=True)),
+        (None, None),
+    )[0]
+
+
+def _get_uv_release_info():
+    system = platform.system().lower()
+    if system not in ("windows", "linux", "darwin"):
+        return None, None
+
+    arch = defaultdict(
+        lambda: None,
+        {
+            "AMD64": "x86_64",
+            "x86_64": "x86_64",
+            "arm64": "aarch64",
+            "aarch64": "aarch64",
+        },
+    )[platform.machine()]
+    if arch is None:
+        return None, None
+
+    vendor = defaultdict(lambda: "unknown", {"windows": "pc", "darwin": "apple"})[
+        system
+    ]
+
+    abi = None
+    if system == "windows":
+        cc = sysconfig.get_config_var("CC")
+        abi = "msvc" if cc is None or cc == "cl.exe" else "gnu"
+    elif system == "linux":
+        libc, _ = platform.libc_ver()
+        abi = "gnu" if libc in ("glibc", "libc") else "musl"
+
+    if abi is not None:
+        target = f"uv-{arch}-{vendor}-{system}-{abi}"
+    else:
+        target = f"uv-{arch}-{vendor}-{system}"
+
+    if system == "windows":
+        return target + ".zip", target
+
+    return target + ".tar.gz", target

bex_hooks/hooks/python/utils.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import contextlib
+import datetime as dt
+import platform
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from stdlibx.compose import flow
+from stdlibx.option import fn as option
+from stdlibx.option import optional_of
+from stdlibx.result import Error, Ok, as_result
+from stdlibx.result import fn as result
+
+from bex_hooks.hooks.python._interface import is_token_cancelled
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from bex_hooks.hooks.python._interface import CancellationToken
+
+
+def append_path(previous: str, *values: str) -> str:
+    path_sep = ";" if platform.system() == "Windows" else ":"
+    previous_path = previous.split(path_sep)
+    for value in values:
+        if value not in previous_path:
+            previous_path.append(value)
+    return path_sep.join([value for value in previous_path if len(value) > 0])
+
+
+def prepend_path(previous: str, *values: str) -> str:
+    path_sep = ";" if platform.system() == "Windows" else ":"
+    previous_path = previous.split(path_sep)
+    for value in reversed(values):
+        if value not in previous_path:
+            previous_path.insert(0, value)
+    return path_sep.join([value for value in previous_path if len(value) > 0])
+
+
+def download_file(
+    token: CancellationToken,
+    source: str,
+    *,
+    chunk_size: int | None = None,
+    report_hook: Callable[[int, int], Any] | None = None,
+) -> Path:
+    with (
+        tempfile.NamedTemporaryFile(delete=False) as dest,
+        httpx.stream(
+            "GET", source, follow_redirects=True, headers={"Accept-Encoding": ""}
+        ) as response,
+    ):
+        _content_len = (
+            int(response.headers["Content-Length"])
+            if "Content-Length" in response.headers
+            else -1
+        )
+
+        chunk_iter = response.iter_bytes(chunk_size)
+        with contextlib.suppress(StopIteration):
+            while token.is_cancelled() is False:
+                dest.write(next(chunk_iter))
+                if callable(report_hook):
+                    report_hook(response.num_bytes_downloaded, _content_len)
+
+        _path = Path(dest.name)
+        if is_token_cancelled(token) and _path.exists():
+            _path.unlink()
+            raise token.get_error()
+
+        return _path
+
+
+def wait_process(
+    token: CancellationToken,
+    args: str | Sequence[str],
+    /,
+    *,
+    callback: Callable[[str], Any] | None = None,
+    timeout: float | None = None,
+    **kwargs,
+) -> int:
+    class _ProcessEndedError(Exception): ...
+
+    process = subprocess.Popen(
+        args,
+        shell=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        **kwargs,
+    )
+
+    def _terminate_process(_: Exception | None):
+        if process.poll() is not None:
+            return
+
+        process.terminate()
+        try:
+            process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+
+    token.register(_terminate_process)
+
+    while True:
+        _result = flow(
+            optional_of(lambda: process.stdout),
+            option.map_or_else(
+                lambda: Ok("\n") if process.poll() is None else Ok(""),
+                as_result(
+                    lambda stdout: (
+                        stdout.readline() or "\n" if process.poll() is None else ""
+                    )
+                ),
+            ),
+            result.and_then(
+                lambda val: Ok(val) if len(val) > 0 else Error(_ProcessEndedError())
+            ),
+            result.map_(lambda val: val.strip("\n")),
+        )
+
+        match _result:
+            case Ok(line) if callback is not None:
+                callback(line)
+            case Error(_ProcessEndedError()):
+                token.raise_if_cancelled()
+                return process.poll()  # type: ignore
+            case Error():
+                _terminate_process(None)
+                return process.poll()  # type: ignore
+
+
+class EtaCalculator:
+    def __init__(self) -> None:
+        self.__start_time = None
+
+    def eta(self, value: int, total: int) -> str:
+        if value == -1:
+            return str(dt.timedelta())
+
+        _now = dt.datetime.now(tz=dt.UTC)
+        if self.__start_time is None:
+            self.__start_time = _now
+
+        _elapsed = (_now - self.__start_time).total_seconds()
+        if _elapsed == 0:
+            return str(dt.timedelta())
+
+        return str(dt.timedelta(seconds=(total - value) / (value / _elapsed)))

bex_hooks_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: bex-hooks-python
+Version: 0.1.0
+Summary: bex-hooks-python
+Author: Lucino772
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: stdlibx-compose>=0.1.0,<1
+Requires-Dist: stdlibx-option>=0.1.0,<1
+Requires-Dist: stdlibx-result>=0.1.0,<1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# bex-hooks-python
+
+Python-related hooks for **bex**. This package provides hooks to create and manage Python virtual environments and their dependencies.
+
+## Usage
+`bex-hooks-python` is available on PyPI.
+
+Add the plugin package to the `requirements` section of your `bex` bootstrap header:
+
+```yaml
+# /// bootstrap
+# requires-python: ">=3.11,<3.12"
+# requirements: |
+#   bex-hooks
+#   bex-hooks-python
+# entrypoint: bex_hooks.exec:main
+# ///
+```
+
+Then enable the plugin in your configuration:
+```yaml
+config:
+  plugins:
+    - bex_hooks.hooks.python
+```
+
+## Hooks
+
+### `python/setup-python`
+
+Sets up a Python virtual environment for a specified version and synchronizes its dependencies using `uv`. When both `requirements` and `requirements_file` are provided, their contents are merged into a single set of requirements.
+
+#### Arguments
+
+| Name                | Type          |    Default   | Description                                                                                             |
+|---------------------|---------------|:------------:|---------------------------------------------------------------------------------------------------------|
+| `version`           | `str`         | *(required)* | Python version to provision (e.g. `">=3.11,<3.12"`)                                                     |
+| `uv`                | `str \| None` | `None`       | Version of `uv` to use                                                                                  |
+| `requirements`      | `str`         | `""`         | Inline requirements (e.g. `"requests==2.32.0"`).                                                        |
+| `requirements_file` | `list[str]`   | `[]`         | One or more requirements file paths.                                                                    |
+| `activate_env`      | `bool`        | `False`      | If `True`, activates the environment for subsequent steps.                                              |
+| `set_python_path`   | `bool`        | `False`      | If `True`, sets `PYTHONPATH` to the virtual environment.                                                |
+| `inexact`           | `bool`        | `False`      | If `True`, tells `uv` not to remove dependencies that are present but not declared in the requirements. |
+
+#### Example
+
+```yaml
+hooks:
+  - id: python/setup-python
+    version: ">=3.11,<3.12"
+    uv: "0.4.0"
+    requirements_file:
+      - requirements.txt
+    requirements: |
+      requests==2.32.0
+    activate_env: true
+    inexact: true
+```

bex_hooks_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+bex_hooks/hooks/python/__init__.py,sha256=Ca_ZaarYqxUtd2zylrBHSZDCAiNBmzVJp0nRl_b-Ql0,352
+bex_hooks/hooks/python/_interface.py,sha256=hZle0vH_Buyo0vkh1aMiWg3msVHcyvyE9gpwW12wq-4,2700
+bex_hooks/hooks/python/setup.py,sha256=ZsQu2tul83w1-HCMI0UPAtIYxD0Gyl0luRBux3Q_oX4,10302
+bex_hooks/hooks/python/utils.py,sha256=fFec03RC90d_2m7XoB0gvKlAhFNFAz2d6GwsESjgOUM,4587
+bex_hooks_python-0.1.0.dist-info/licenses/LICENSE,sha256=EpsoiD9x04vG_Im6LSZpj5ev1iFTq5TYKVbR55N8k5w,1066
+bex_hooks_python-0.1.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+bex_hooks_python-0.1.0.dist-info/METADATA,sha256=lmK4YzGxtS81vzJ1QTi8dup_4rHPiUA5_lsxd4oZ4cs,2925
+bex_hooks_python-0.1.0.dist-info/RECORD,,

bex_hooks_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

bex_hooks_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucino772
+
+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.