horus-environments 0.1.0__tar.gz

horus_environments-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.ipynb
+
+# Virtual environments
+venv/
+.venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+*.xml
+
+# i18n
+*.mo
+
+# logs
+logs/
+
+no-commit/

horus_environments-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

horus_environments-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: horus-environments
+Version: 0.1.0
+Summary: Automatically provision python virtual environments for Horus tasks.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: horus-runtime>=0.1.4

horus_environments-0.1.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+name = "horus-environments"
+description = "Automatically provision python virtual environments for Horus tasks."
+requires-python = ">=3.13"
+license = "MIT"
+classifiers = [
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["horus-runtime>=0.1.4"]
+dynamic = ["version"]
+
+# ================
+# Plugin entry-points
+# ================
+[project.entry-points."horus.executor"]
+python_environment = "horus_environments.executor.environment"
+
+# ================
+
+[dependency-groups]
+dev = [
+  "babel~=2.0",
+  "mypy~=1.19",
+  "pre_commit~=4.0",
+  "pytest~=9.0",
+  "pytest-asyncio~=1.3.0",
+  "pytest-cov~=7.0",
+  "ruff~=0.15",
+  "types-PyYAML~=6.0",
+  "uv-dynamic-versioning>=0.14.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.29,<2.0", "uv-dynamic-versioning>=0.14.0,<1.0"]
+build-backend = "hatchling.build"
+
+[tool.coverage.run]
+source = ["horus_environments"]
+
+[tool.coverage.report]
+omit = ["tests/*"]
+
+# Other tool configurations
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/horus_environments"]
+# py.typed ships the type marker; compiled translations are git-ignored (*.mo)
+# but must ship in the wheel.
+artifacts = [
+  "src/horus_environments/py.typed",
+  "src/horus_environments/locale/**/*.mo"
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/horus_environments", "tests"]
+artifacts = [
+  "src/horus_environments/py.typed",
+  "src/horus_environments/locale/**/*.mo"
+]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+exclude = ["build", "dist"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_typed = true
+init_forbid_extra = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+addopts = """
+    --verbose
+    --cov=src/horus_environments
+    --cov-report=html
+    --cov-report=term-missing
+    --cov-fail-under=90
+"""
+minversion = "7.0"
+python_classes = ["Test*"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 79
+target-version = "py313"
+exclude = [".git", ".venv", "build", "dist", "__pycache__"]
+
+[tool.ruff.lint]
+select = [
+  "D",  # pydocstyle
+  "E",  # pycodestyle errors
+  "W",  # pycodestyle warnings
+  "F",  # pyflakes
+  "I",  # isort
+  "N",  # pep8-naming
+  "UP",  # pyupgrade
+  "B",  # flake8-bugbear
+  "PL",  # pylint
+  "RUF",  # ruff-specific
+  "ARG",  # ruff-arglint
+  "SLF",  # ruff-slf
+]
+extend-select = ["T201"]  # Prevent use of print()
+
+ignore = [
+  "E203",  # Whitespace before ':', conflicts with formatter
+  "D104",  # Missing docstring in __init__ (often redundant)
+  "D205",  # 1 blank line required between summary line and description
+  "D212",  # Multi-line docstring summary should start at the first line
+  "D200",  # One-line docstring should fit on one line
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["SLF001"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.1"

horus_environments-0.1.0/src/horus_environments/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# Licensed under the MIT License. See LICENSE for details.

horus_environments-0.1.0/src/horus_environments/executor/__init__.py

@@ -0,0 +1 @@
+"""Executor implementations for horus-environments."""

horus_environments-0.1.0/src/horus_environments/executor/environment.py

@@ -0,0 +1,427 @@
+"""
+Python environment executors for Horus tasks.
+"""
+
+import asyncio
+import re
+import shlex
+from contextlib import aclosing
+from typing import TYPE_CHECKING, ClassVar
+
+from horus_builtin.runtime.command import CommandRuntime
+from horus_builtin.runtime.python_string import PythonCodeStringRuntime
+from horus_runtime.core.executor.base import BaseExecutor, RuntimeFilterType
+from horus_runtime.core.task.exceptions import TaskExecutionError
+from horus_runtime.logging import horus_logger
+from horus_runtime.settings import runtime_settings
+from pydantic import Field
+
+from horus_environments.i18n import tr as _
+
+if TYPE_CHECKING:
+    from horus_runtime.core.task.base import BaseTask
+
+
+class PythonEnvironmentExecutor(BaseExecutor):
+    """
+    Shared implementation for Python environment-backed executors.
+    """
+
+    add_to_registry: ClassVar[bool] = False
+
+    runtimes: ClassVar[RuntimeFilterType] = (
+        CommandRuntime,
+        PythonCodeStringRuntime,
+    )
+
+    requirements: list[str] = Field(default_factory=list)
+    """
+    Python package requirements installed into the environment with pip.
+    """
+
+    env: dict[str, str] = Field(default_factory=dict)
+    """
+    Extra environment variables passed to the target process.
+    """
+
+    environment_dir: str = ".horus_python_environment"
+    """
+    Directory, relative to the task working directory, where the environment
+    is created.
+    """
+
+    recreate: bool = False
+    """
+    Recreate the environment before running the task.
+    """
+
+    def _environment_path(self, task: "BaseTask") -> str:
+        """Return the target-side path where the environment lives."""
+        return f"{task.working_dir}/{self.environment_dir}"
+
+    def _python_bin(self, task: "BaseTask") -> str:
+        """Return the target-side Python executable inside the environment."""
+        return f"{self._environment_path(task)}/bin/python"
+
+    def _environment_log_name(self) -> str:
+        """Return a human-readable backend name for setup logs."""
+        return type(self).__name__
+
+    def _log_command(self, message: str) -> str:
+        """Return a shell command that emits one setup log line."""
+        return f"printf '%s\\n' {shlex.quote(message)}"
+
+    def _create_log_command(self, task: "BaseTask") -> str:
+        """Return a shell log command for environment creation."""
+        return self._log_command(
+            _("Creating %(executor)s at %(path)s")
+            % {
+                "executor": self._environment_log_name(),
+                "path": self._environment_path(task),
+            }
+        )
+
+    def _reuse_log_command(self, task: "BaseTask") -> str:
+        """Return a shell log command for environment reuse."""
+        return self._log_command(
+            _("Using existing %(executor)s at %(path)s")
+            % {
+                "executor": self._environment_log_name(),
+                "path": self._environment_path(task),
+            }
+        )
+
+    def _pip_install_command(self, task: "BaseTask") -> str | None:
+        """Return the pip install command, or ``None`` with no requirements."""
+        if not self.requirements:
+            return None
+        requirements = " ".join(shlex.quote(req) for req in self.requirements)
+        return (
+            f"{shlex.quote(self._python_bin(task))}"
+            f" -m pip install {requirements}"
+        )
+
+    @staticmethod
+    def _version_probe_snippet() -> str:
+        """Python one-liner that prints the interpreter's ``major.minor``."""
+        return (
+            "import sys; "
+            "print(f'{sys.version_info.major}.{sys.version_info.minor}')"
+        )
+
+    def _reuse_or_create_command(
+        self, task: "BaseTask", create: str, version: str | None
+    ) -> str:
+        """
+        Return a shell snippet that reuses the env when the interpreter exists
+        (and, when ``version`` is given, matches ``major.minor``), otherwise
+        wipes and recreates it with ``create``.
+        """
+        env_path = shlex.quote(self._environment_path(task))
+        python_bin = shlex.quote(self._python_bin(task))
+        if version is not None:
+            probe = shlex.quote(self._version_probe_snippet())
+            stale = (
+                f"[ ! -x {python_bin} ]"
+                f' || [ "$({python_bin} -c {probe} 2>/dev/null)"'
+                f" != {shlex.quote(version)} ]"
+            )
+            return (
+                f"if {stale};"
+                f" then {self._create_log_command(task)}"
+                f" && rm -rf {env_path} && {create};"
+                f" else {self._reuse_log_command(task)};"
+                f" fi"
+            )
+        return (
+            f"if [ -x {python_bin} ];"
+            f" then {self._reuse_log_command(task)};"
+            f" else {self._create_log_command(task)} && {create};"
+            f" fi"
+        )
+
+    def _create_environment_command(self, task: "BaseTask") -> str:
+        """
+        Return the shell command that ensures the environment exists.
+        """
+        raise NotImplementedError
+
+    def _run_command(self, task: "BaseTask", prepared_command: str) -> str:
+        """Return a command runtime invocation inside the environment."""
+        activate = shlex.quote(f"{self._environment_path(task)}/bin/activate")
+        return f". {activate} && /bin/sh -c {shlex.quote(prepared_command)}"
+
+    def _run_python_script_command(
+        self, task: "BaseTask", script_path: str
+    ) -> str:
+        """Return a Python runtime invocation inside the environment."""
+        return (
+            f"{shlex.quote(self._python_bin(task))} {shlex.quote(script_path)}"
+        )
+
+    def _setup_commands(self, task: "BaseTask") -> list[str]:
+        """Return all shell commands required before the runtime executes."""
+        commands: list[str] = []
+        env_path = shlex.quote(self._environment_path(task))
+        if self.recreate:
+            commands.append(
+                self._log_command(
+                    _("Recreating Python environment at %(path)s")
+                    % {"path": self._environment_path(task)}
+                )
+            )
+            commands.append(f"rm -rf {env_path}")
+        commands.append(self._create_environment_command(task))
+        install = self._pip_install_command(task)
+        if install is not None:
+            commands.append(
+                self._log_command(
+                    _(
+                        "Installing %(count)d Python requirement(s) into "
+                        "%(path)s"
+                    )
+                    % {
+                        "count": len(self.requirements),
+                        "path": self._environment_path(task),
+                    }
+                )
+            )
+            commands.append(install)
+        return commands
+
+    async def _runtime_command(self, task: "BaseTask") -> str:
+        """Prepare the task runtime and return its environment command."""
+        if isinstance(task.runtime, CommandRuntime):
+            command = await task.runtime.setup_runtime(task)
+            return self._run_command(task, command)
+
+        if isinstance(task.runtime, PythonCodeStringRuntime):
+            code = await task.runtime.setup_runtime(task)
+            script_path = f"{task.working_dir}/.horus_python_runtime.py"
+            await task.target.put_file(code.encode(), script_path)
+            return self._run_python_script_command(task, script_path)
+
+        raise TaskExecutionError(
+            _("Unsupported runtime %(runtime)s for %(executor)s")
+            % {
+                "runtime": type(task.runtime).__name__,
+                "executor": type(self).__name__,
+            }
+        )
+
+    async def _execute(self, task: "BaseTask") -> None:
+        """
+        Provision the selected Python environment and execute the runtime.
+        """
+        await task.target.mkdir(task.working_dir)
+        run_command = await self._runtime_command(task)
+        full_command = " && ".join([*self._setup_commands(task), run_command])
+
+        horus_logger.log.debug(
+            _("Executing task %(task_id)s in %(executor)s: %(command)s")
+            % {
+                "task_id": task.id,
+                "executor": type(self).__name__,
+                "command": full_command,
+            }
+        )
+
+        env = {
+            **self.env,
+            runtime_settings.SIDE_ARTIFACTS_DIR_ENV: str(
+                task.side_artifacts_dir
+            ),
+        }
+        proc = await task.target.run_command(
+            full_command,
+            cwd=task.working_dir,
+            env=env,
+        )
+
+        try:
+            async with aclosing(proc.stream()) as stream:
+                async for stream_name, line in stream:
+                    if stream_name == "stdout":
+                        horus_logger.log.info(line.decode("utf-8").rstrip())
+                    elif stream_name == "stderr":
+                        horus_logger.log.warning(line.decode("utf-8").rstrip())
+        except asyncio.CancelledError:
+            proc.kill()
+            await proc.wait()
+            raise
+
+        # Draining the stream hits EOF but doesn't reap the process; wait() is
+        # what yields a reliable returncode (matches ShellExecutor).
+        await proc.wait()
+        if proc.returncode != 0:
+            raise TaskExecutionError(
+                _(
+                    "Python environment command exited with return code "
+                    "%(code)s"
+                )
+                % {"code": proc.returncode}
+            )
+
+
+class CondaPythonEnvironmentExecutor(PythonEnvironmentExecutor):
+    """
+    Execute tasks in a Conda environment on the task target.
+    """
+
+    add_to_registry: ClassVar[bool] = True
+
+    kind: str = "conda_python_environment"
+    kind_name: ClassVar[str] = "Conda Python Environment"
+    kind_description: ClassVar[str] = _(
+        "Executes command and Python runtimes inside a Conda environment."
+    )
+
+    conda: str = "conda"
+    """Conda executable available on the target."""
+
+    python_version: str | None = None
+    """Optional Python version passed to ``conda create``."""
+
+    def _environment_log_name(self) -> str:
+        """Return a human-readable backend name for setup logs."""
+        return "Conda Python environment"
+
+    def _create_environment_command(self, task: "BaseTask") -> str:
+        """Return the Conda environment creation command."""
+        env_path = shlex.quote(self._environment_path(task))
+        conda = shlex.quote(self.conda)
+        python = (
+            f"python={shlex.quote(self.python_version)}"
+            if self.python_version
+            else "python"
+        )
+        create = f"{conda} create -y -p {env_path} {python} pip"
+        return self._reuse_or_create_command(
+            task, create, self._requested_python_version()
+        )
+
+    def _requested_python_version(self) -> str | None:
+        """Return the requested ``major.minor`` version, if one was given."""
+        if self.python_version is None:
+            return None
+        match = re.search(
+            r"(?<!\d)(\d+\.\d+)(?:\.\d+)?(?!\d)", self.python_version
+        )
+        return match.group(1) if match else None
+
+    def _pip_install_command(self, task: "BaseTask") -> str | None:
+        """Install requirements through ``conda run``."""
+        if not self.requirements:
+            return None
+        conda = shlex.quote(self.conda)
+        env_path = shlex.quote(self._environment_path(task))
+        requirements = " ".join(shlex.quote(req) for req in self.requirements)
+        return (
+            f"{conda} run -p {env_path} python -m pip install {requirements}"
+        )
+
+    def _run_command(self, task: "BaseTask", prepared_command: str) -> str:
+        """Run a shell command with ``conda run``."""
+        conda = shlex.quote(self.conda)
+        env_path = shlex.quote(self._environment_path(task))
+        return (
+            f"{conda} run --no-capture-output -p {env_path}"
+            f" /bin/sh -c {shlex.quote(prepared_command)}"
+        )
+
+    def _run_python_script_command(
+        self, task: "BaseTask", script_path: str
+    ) -> str:
+        """Run a Python script with ``conda run``."""
+        conda = shlex.quote(self.conda)
+        env_path = shlex.quote(self._environment_path(task))
+        return (
+            f"{conda} run --no-capture-output -p {env_path}"
+            f" python {shlex.quote(script_path)}"
+        )
+
+
+class UvPythonEnvironmentExecutor(PythonEnvironmentExecutor):
+    """
+    Execute tasks in a uv-managed virtual environment on the task target.
+    """
+
+    add_to_registry: ClassVar[bool] = True
+
+    kind: str = "uv_python_environment"
+    kind_name: ClassVar[str] = "uv Python Environment"
+    kind_description: ClassVar[str] = _(
+        "Executes command and Python runtimes inside a uv virtual environment."
+    )
+
+    uv: str = "uv"
+    """uv executable available on the target."""
+
+    python: str | None = None
+    """Optional interpreter or Python version passed to ``uv venv``."""
+
+    def _environment_log_name(self) -> str:
+        """Return a human-readable backend name for setup logs."""
+        return "uv Python environment"
+
+    def _requested_python_version(self) -> str | None:
+        """
+        Return the requested major.minor version when it can be inferred.
+        """
+        if self.python is None:
+            return None
+        match = re.search(r"(?<!\d)(\d+\.\d+)(?:\.\d+)?(?!\d)", self.python)
+        return match.group(1) if match else None
+
+    def _create_environment_command(self, task: "BaseTask") -> str:
+        """Return the uv venv creation command."""
+        env_path = shlex.quote(self._environment_path(task))
+        uv = shlex.quote(self.uv)
+        python = f" --python {shlex.quote(self.python)}" if self.python else ""
+        create = f"{uv} venv{python} {env_path}"
+        return self._reuse_or_create_command(
+            task, create, self._requested_python_version()
+        )
+
+    def _pip_install_command(self, task: "BaseTask") -> str | None:
+        """Install requirements through uv pip."""
+        if not self.requirements:
+            return None
+        uv = shlex.quote(self.uv)
+        requirements = " ".join(shlex.quote(req) for req in self.requirements)
+        return (
+            f"{uv} pip install --python {shlex.quote(self._python_bin(task))}"
+            f" {requirements}"
+        )
+
+
+class VirtualenvPythonEnvironmentExecutor(PythonEnvironmentExecutor):
+    """
+    Execute tasks in a standard-library venv on the task target.
+    """
+
+    add_to_registry: ClassVar[bool] = True
+
+    kind: str = "virtualenv_python_environment"
+    kind_name: ClassVar[str] = "Virtualenv Python Environment"
+    kind_description: ClassVar[str] = _(
+        "Executes command and Python runtimes inside a Python virtualenv."
+    )
+
+    python: str = "python"
+    """Python interpreter used to create the virtual environment."""
+
+    def _environment_log_name(self) -> str:
+        """Return a human-readable backend name for setup logs."""
+        return "virtualenv Python environment"
+
+    def _create_environment_command(self, task: "BaseTask") -> str:
+        """Return the stdlib venv creation command."""
+        env_path = shlex.quote(self._environment_path(task))
+        return (
+            f"if [ -x {shlex.quote(self._python_bin(task))} ];"
+            f" then {self._reuse_log_command(task)};"
+            f" else {self._create_log_command(task)}"
+            f" && {shlex.quote(self.python)} -m venv {env_path};"
+            f" fi"
+        )

horus_environments-0.1.0/src/horus_environments/i18n.py

@@ -0,0 +1,18 @@
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# Licensed under the MIT License. See LICENSE for details.
+"""
+Localization for horus_environments.
+
+Import ``tr`` (aliased as ``_``) in any module that has user-visible strings::
+
+    from horus_environments.i18n import tr as _
+
+    _("Something happened.")
+    _("%(n)s item processed", "%(n)s items processed", n=count)
+"""
+
+from pathlib import Path
+
+from horus_runtime.i18n import make_translator
+
+tr = make_translator("horus_environments", Path(__file__).parent / "locale")

horus_environments-0.1.0/src/horus_environments/locale/messages.pot

@@ -0,0 +1,21 @@
+# Translations template for horus_environments.
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# This file is distributed under the same license as the horus_environments project.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: horus_environments VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-04-12 00:00+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: src/horus_environments/task/custom_task.py
+msgid "CustomTask._run() is not implemented yet."
+msgstr ""

horus_environments-0.1.0/tests/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# Licensed under the MIT License. See LICENSE for details.

horus_environments-0.1.0/tests/conftest.py

@@ -0,0 +1,52 @@
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# Licensed under the MIT License. See LICENSE for details.
+"""
+Shared pytest configuration and fixtures for horus_environments tests.
+"""
+
+from collections.abc import Generator
+
+import pytest
+from horus_runtime.context import HorusContext, _runtime_ctx
+from horus_runtime.registry.auto_registry import AutoRegistry
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """
+    Register custom markers.
+    """
+    # Register custom markers for test categorization.
+    # This is optional but can be useful for filtering tests.
+    config.addinivalue_line("markers", "unit: mark test as a unit test")
+    config.addinivalue_line(
+        "markers", "integration: mark test as an integration test"
+    )
+
+
+@pytest.fixture(scope="session", autouse=True)
+def init_registry() -> None:
+    """
+    Load all registered plugins (including horus_environments) once per
+    session.
+
+    ``AutoRegistry.init_registry()`` discovers every installed package that
+    declares a ``horus.*`` entry point and imports its module, triggering
+    class registration. This must run before any Pydantic model that contains
+    a registry field is instantiated.
+    """
+    AutoRegistry.init_registry()
+
+
+@pytest.fixture
+def horus_context() -> Generator[HorusContext]:
+    """
+    Provide a fresh ``HorusContext`` for each test and reset the context
+    variable afterwards so tests do not leak state into each other.
+    """
+    ctx = HorusContext()
+    ctx.bus.start()
+    token = _runtime_ctx.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _runtime_ctx.reset(token)

horus_environments-0.1.0/tests/unit/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2026 YOUR_ORGANIZATION_NAME
+# Licensed under the MIT License. See LICENSE for details.

horus_environments-0.1.0/tests/unit/test_environment_executor.py

@@ -0,0 +1,357 @@
+"""Unit tests for Python environment executors."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from horus_builtin.runtime.command import CommandRuntime
+from horus_builtin.runtime.python_string import PythonCodeStringRuntime
+from horus_builtin.task.horus_task import HorusTask
+from horus_runtime.context import HorusContext
+from horus_runtime.core.executor.base import BaseExecutor
+from horus_runtime.core.task.exceptions import TaskExecutionError
+
+from horus_environments.executor.environment import (
+    CondaPythonEnvironmentExecutor,
+    PythonEnvironmentExecutor,
+    UvPythonEnvironmentExecutor,
+    VirtualenvPythonEnvironmentExecutor,
+)
+
+_NONZERO_CODE = 7
+
+
+def _make_mock_proc(
+    returncode: int = 0, stdout: bytes = b"", stderr: bytes = b""
+) -> AsyncMock:
+    """Return an AsyncMock channel process."""
+    proc = AsyncMock()
+    proc.returncode = returncode
+    proc.communicate = AsyncMock(return_value=(stdout, stderr))
+    proc.wait = AsyncMock(return_value=returncode)
+
+    async def _stream() -> object:
+        for line in stdout.splitlines(keepends=True):
+            yield ("stdout", line)
+        for line in stderr.splitlines(keepends=True):
+            yield ("stderr", line)
+
+    # The executor consumes proc.stream() with `async for`, so stream must
+    # return an async generator (not an awaitable).
+    proc.stream = MagicMock(return_value=_stream())
+    return proc
+
+
+def _make_mock_target(proc: AsyncMock | None = None) -> MagicMock:
+    """Return a mock target whose channel methods are async."""
+    target = MagicMock()
+    target.working_directory = "/tmp/horus"
+    target.mkdir = AsyncMock()
+    target.put_file = AsyncMock()
+    target.run_command = AsyncMock(return_value=proc or _make_mock_proc())
+    return target
+
+
+def _make_command_task(
+    executor: PythonEnvironmentExecutor, command: str = "python --version"
+) -> HorusTask:
+    """Create a HorusTask using a command runtime."""
+    return HorusTask(
+        id="task-1",
+        name="task_1",
+        executor=executor,
+        runtime=CommandRuntime(command=command),
+    )
+
+
+@pytest.mark.unit
+class TestEnvironmentExecutorRegistration:
+    """Verify concrete executors register under separate kinds."""
+
+    def test_base_executor_is_not_registered(self) -> None:
+        """The shared base class must not appear in the registry."""
+        assert PythonEnvironmentExecutor not in BaseExecutor.registry.values()
+
+    @pytest.mark.parametrize(
+        ("kind", "executor_cls"),
+        [
+            ("conda_python_environment", CondaPythonEnvironmentExecutor),
+            ("uv_python_environment", UvPythonEnvironmentExecutor),
+            (
+                "virtualenv_python_environment",
+                VirtualenvPythonEnvironmentExecutor,
+            ),
+        ],
+    )
+    def test_concrete_executors_are_registered(
+        self,
+        kind: str,
+        executor_cls: type[PythonEnvironmentExecutor],
+    ) -> None:
+        """Each environment backend must have its own registry kind."""
+        assert BaseExecutor.registry[kind] is executor_cls
+
+    def test_runtimes_filter_allows_commands_and_python(self) -> None:
+        """Environment executors support command and Python string runtimes."""
+        assert CommandRuntime in PythonEnvironmentExecutor.runtimes
+        assert PythonCodeStringRuntime in PythonEnvironmentExecutor.runtimes
+
+
+@pytest.mark.unit
+class TestEnvironmentCommandBuilders:
+    """Verify backend-specific shell command generation."""
+
+    def test_virtualenv_setup_uses_stdlib_venv(self) -> None:
+        """Virtualenv executor creates a venv with the configured Python."""
+        executor = VirtualenvPythonEnvironmentExecutor(python="python3.13")
+        task = _make_command_task(executor)
+
+        command = executor._create_environment_command(task)
+
+        assert "Creating virtualenv Python environment" in command
+        assert "Using existing virtualenv Python environment" in command
+        assert "python3.13 -m venv" in command
+        assert ".horus_python_environment" in command
+
+    def test_uv_setup_uses_uv_venv_with_python(self) -> None:
+        """Uv executor creates the environment through uv."""
+        executor = UvPythonEnvironmentExecutor(python="3.13")
+        task = _make_command_task(executor)
+
+        command = executor._create_environment_command(task)
+
+        assert "sys.version_info.major" in command
+        assert "rm -rf" in command
+        assert "Creating uv Python environment" in command
+        assert "Using existing uv Python environment" in command
+        assert "uv venv --python 3.13" in command
+        assert "!= 3.13" in command
+
+    def test_uv_setup_detects_interpreter_style_version(self) -> None:
+        """Uv extracts major.minor versions from interpreter-like strings."""
+        executor = UvPythonEnvironmentExecutor(python="python3.11")
+        task = _make_command_task(executor)
+
+        command = executor._create_environment_command(task)
+
+        assert "uv venv --python python3.11" in command
+        assert "!= 3.11" in command
+
+    def test_conda_setup_uses_conda_create_with_python_version(self) -> None:
+        """Conda executor creates the environment with conda create."""
+        executor = CondaPythonEnvironmentExecutor(python_version="3.13")
+        task = _make_command_task(executor)
+
+        command = executor._create_environment_command(task)
+
+        assert "Creating Conda Python environment" in command
+        assert "Using existing Conda Python environment" in command
+        assert "conda create -y -p" in command
+        assert "python=3.13" in command
+        assert " pip" in command
+        # A pinned version must recreate the env when it drifts, not blindly
+        # reuse whatever interpreter already exists.
+        assert "sys.version_info.major" in command
+        assert "!= 3.13" in command
+        assert "rm -rf" in command
+
+    def test_conda_setup_without_version_uses_existence_check(self) -> None:
+        """Without a pinned version, conda reuses any existing interpreter."""
+        executor = CondaPythonEnvironmentExecutor()
+        task = _make_command_task(executor)
+
+        command = executor._create_environment_command(task)
+
+        assert "conda create -y -p" in command
+        assert "python " in command  # unpinned interpreter
+        assert "sys.version_info.major" not in command
+        assert "rm -rf" not in command
+
+    def test_requirements_are_installed_with_pip(self) -> None:
+        """Requirements are shell-quoted and installed into the environment."""
+        executor = VirtualenvPythonEnvironmentExecutor(
+            requirements=["numpy==2.0", "my package"]
+        )
+        task = _make_command_task(executor)
+
+        command = executor._pip_install_command(task)
+
+        assert command is not None
+        assert "-m pip install" in command
+        assert "numpy==2.0" in command
+        assert "'my package'" in command
+
+    def test_conda_requirements_install_uses_conda_run(self) -> None:
+        """Conda installs requirements from inside the Conda environment."""
+        executor = CondaPythonEnvironmentExecutor(requirements=["pandas"])
+        task = _make_command_task(executor)
+
+        command = executor._pip_install_command(task)
+
+        assert command is not None
+        assert command.startswith("conda run -p")
+        assert "python -m pip install pandas" in command
+
+    def test_conda_without_requirements_skips_install(self) -> None:
+        """Conda does not emit an install command without requirements."""
+        executor = CondaPythonEnvironmentExecutor()
+        task = _make_command_task(executor)
+
+        assert executor._pip_install_command(task) is None
+
+    def test_uv_requirements_install_uses_uv_pip(self) -> None:
+        """Uv installs requirements through uv pip."""
+        executor = UvPythonEnvironmentExecutor(requirements=["httpx"])
+        task = _make_command_task(executor)
+
+        command = executor._pip_install_command(task)
+
+        assert command is not None
+        assert command.startswith("uv pip install --python")
+        assert " httpx" in command
+
+    def test_recreate_removes_environment_before_setup(self) -> None:
+        """recreate=True removes the old environment before creation."""
+        executor = VirtualenvPythonEnvironmentExecutor(recreate=True)
+        task = _make_command_task(executor)
+
+        commands = executor._setup_commands(task)
+
+        assert "Recreating Python environment" in commands[0]
+        assert commands[1].startswith("rm -rf")
+        assert "python -m venv" in commands[2]
+
+    def test_requirements_install_logs_count(self) -> None:
+        """Requirement setup logs the install count before pip runs."""
+        executor = VirtualenvPythonEnvironmentExecutor(
+            requirements=["rich", "httpx"]
+        )
+        task = _make_command_task(executor)
+
+        commands = executor._setup_commands(task)
+
+        assert "Installing 2 Python requirement(s)" in commands[-2]
+        assert "-m pip install rich httpx" in commands[-1]
+
+    def test_command_runtime_is_wrapped_in_environment_shell(self) -> None:
+        """Command runtimes execute with the virtualenv activated."""
+        executor = VirtualenvPythonEnvironmentExecutor()
+        task = _make_command_task(executor)
+
+        command = executor._run_command(task, "python -c 'print(1)'")
+
+        expected = ".horus_python_environment/bin/activate && /bin/sh -c"
+        assert expected in command
+        assert "/bin/sh -c" in command
+
+    def test_conda_runtime_commands_use_conda_run(self) -> None:
+        """Conda wraps shell commands and Python scripts with conda run."""
+        executor = CondaPythonEnvironmentExecutor(conda="mamba")
+        task = _make_command_task(executor)
+
+        command = executor._run_command(task, "echo hi")
+        python = executor._run_python_script_command(task, "/tmp/run.py")
+
+        assert command.startswith("mamba run --no-capture-output -p")
+        assert "/bin/sh -c" in command
+        assert python.startswith("mamba run --no-capture-output -p")
+        assert " python /tmp/run.py" in python
+
+
+@pytest.mark.unit
+class TestEnvironmentExecutorExecute:
+    """Verify end-to-end executor behavior against the target channel."""
+
+    @pytest.mark.asyncio
+    async def test_execute_runs_setup_install_and_command(
+        self, horus_context: HorusContext
+    ) -> None:
+        """A command runtime is provisioned and delegated to run_command."""
+        del horus_context
+        executor = VirtualenvPythonEnvironmentExecutor(
+            requirements=["rich"], env={"EXTRA": "1"}
+        )
+        task = _make_command_task(executor, "python -c 'print(42)'")
+        target = _make_mock_target(_make_mock_proc(stdout=b"42\n"))
+
+        with patch.object(task, "target", target):
+            await executor._execute(task)
+
+        expected_working_dir = "/tmp/horus/task-1"
+        target.mkdir.assert_called_once_with(expected_working_dir)
+        target.run_command.assert_called_once()
+        command = target.run_command.call_args[0][0]
+        assert "python -m venv" in command
+        assert "-m pip install rich" in command
+        assert "/bin/sh -c" in command
+        kwargs = target.run_command.call_args.kwargs
+        assert kwargs["cwd"] == expected_working_dir
+        assert kwargs["env"]["EXTRA"] == "1"
+
+    @pytest.mark.asyncio
+    async def test_execute_python_string_uploads_and_runs_script(
+        self, horus_context: HorusContext
+    ) -> None:
+        """Python string runtimes are written as a target-side script."""
+        del horus_context
+        executor = UvPythonEnvironmentExecutor()
+        task = HorusTask(
+            id="task-2",
+            name="task_2",
+            executor=executor,
+            runtime=PythonCodeStringRuntime(code="print('hi')"),
+        )
+        target = _make_mock_target()
+
+        with patch.object(task, "target", target):
+            await executor._execute(task)
+
+        target.put_file.assert_called_once_with(
+            b"print('hi')", "/tmp/horus/task-2/.horus_python_runtime.py"
+        )
+        command = target.run_command.call_args[0][0]
+        assert "uv venv" in command
+        assert ".horus_python_environment/bin/python" in command
+        assert ".horus_python_runtime.py" in command
+
+    @pytest.mark.asyncio
+    async def test_execute_nonzero_exit_raises(
+        self, horus_context: HorusContext
+    ) -> None:
+        """A non-zero environment command exit code raises a task error."""
+        del horus_context
+        executor = VirtualenvPythonEnvironmentExecutor()
+        task = _make_command_task(executor)
+        target = _make_mock_target(
+            _make_mock_proc(returncode=_NONZERO_CODE, stderr=b"failed")
+        )
+
+        with patch.object(task, "target", target):
+            with pytest.raises(TaskExecutionError, match=str(_NONZERO_CODE)):
+                await executor._execute(task)
+
+    @pytest.mark.asyncio
+    async def test_execute_cancellation_kills_process(
+        self, horus_context: HorusContext
+    ) -> None:
+        """Cancellation kills the target process before propagating."""
+        del horus_context
+        executor = VirtualenvPythonEnvironmentExecutor()
+        task = _make_command_task(executor)
+        proc = _make_mock_proc()
+        proc.kill = MagicMock()
+
+        # The executor cancels while iterating the stream, so raise there.
+        async def _cancelled_stream() -> object:
+            raise asyncio.CancelledError
+            yield  # pragma: no cover - makes this an async generator
+
+        proc.stream = MagicMock(return_value=_cancelled_stream())
+        target = _make_mock_target(proc)
+
+        with patch.object(task, "target", target):
+            with pytest.raises(asyncio.CancelledError):
+                await executor._execute(task)
+
+        proc.kill.assert_called_once()
+        proc.wait.assert_awaited_once()