wexample-runner 0.0.3__py3-none-any.whl

wexample_runner/runner/abstract_runner.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AbstractRunner(ABC):
+    """Base class for all runners.
+
+    A runner is an execution environment that can build, start, stop, and
+    destroy itself, and execute commands within it.
+    """
+
+    def __init__(self, ephemeral: bool = False) -> None:
+        self.ephemeral = ephemeral
+
+    # --- Context manager (ephemeral support) ---
+    def __enter__(self) -> AbstractRunner:
+        self.ensure_running()
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.stop()
+        if self.ephemeral:
+            self.destroy()
+
+    @property
+    def is_built(self) -> bool:
+        return False
+
+    # --- Properties ---
+    @property
+    def is_running(self) -> bool:
+        return False
+
+    # --- Lifecycle ---
+    def build(self) -> None:
+        """Prepare the environment (build image, check connectivity, etc.). No-op if already built."""
+
+    def destroy(self) -> None:
+        """Completely remove the environment."""
+
+    def ensure_running(self) -> None:
+        """Build and start the environment if not already running."""
+        self.build()
+        self.start()
+
+    # --- Execution ---
+    @abstractmethod
+    def execute(
+        self,
+        cmd: list[str] | str,
+        workdir: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> RunnerResult:
+        """Execute a command in this environment and return the result."""
+
+    def start(self) -> None:
+        """Start the environment. No-op if already running."""
+
+    def stop(self) -> None:
+        """Stop the environment without destroying it."""

wexample_runner/runner/docker_runner.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from wexample_runner.runner.abstract_runner import AbstractRunner
+from wexample_runner.runner_result import RunnerResult
+
+
+class DockerRunner(AbstractRunner):
+    """Execute commands inside a Docker container.
+
+    Manages the full lifecycle: image build, container creation, start, stop, destroy.
+    """
+
+    def __init__(
+        self,
+        image_name: str,
+        dockerfile_path: Path | str | None = None,
+        volumes: dict[str, str] | None = None,
+        env: dict[str, str] | None = None,
+        container_name: str | None = None,
+        workdir: str = "/var/www/html",
+        ephemeral: bool = False,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(ephemeral=ephemeral)
+        self.image_name = image_name
+        self.dockerfile_path = Path(dockerfile_path) if dockerfile_path else None
+        self.volumes = volumes or {}
+        self.env = env or {}
+        self.workdir = workdir
+        self.user = user
+        self._container_name = container_name or self._build_container_name()
+
+    @property
+    def container_name(self) -> str:
+        return self._container_name
+
+    @property
+    def is_built(self) -> bool:
+        from wexample_helpers.helpers.docker import docker_image_exists
+
+        return docker_image_exists(self.image_name)
+
+    # --- Properties ---
+    @property
+    def is_running(self) -> bool:
+        from wexample_helpers.helpers.docker import docker_container_is_running
+
+        return docker_container_is_running(self.container_name)
+
+    # --- Lifecycle ---
+    def build(self) -> None:
+        from wexample_helpers.helpers.docker import (
+            docker_build_image,
+            docker_image_exists,
+        )
+
+        if self.dockerfile_path and not docker_image_exists(self.image_name):
+            docker_build_image(self.image_name, self.dockerfile_path)
+
+    def destroy(self) -> None:
+        from wexample_helpers.helpers.docker import (
+            docker_container_exists,
+            docker_image_exists,
+            docker_remove_container,
+            docker_remove_image,
+        )
+
+        if docker_container_exists(self.container_name):
+            self.stop()
+            docker_remove_container(self.container_name)
+
+        if docker_image_exists(self.image_name):
+            docker_remove_image(self.image_name)
+
+    # --- Execution ---
+    def execute(
+        self,
+        cmd: list[str] | str,
+        workdir: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> RunnerResult:
+        import subprocess
+
+        from wexample_helpers.helpers.shell import shell_run
+
+        if isinstance(cmd, str):
+            cmd = ["sh", "-c", cmd]
+
+        docker_cmd = ["docker", "exec"]
+
+        if self.user:
+            docker_cmd += ["--user", self.user]
+
+        effective_workdir = workdir or self.workdir
+        if effective_workdir:
+            docker_cmd += ["-w", effective_workdir]
+
+        effective_env = {**self.env, **(env or {})}
+        for key, value in effective_env.items():
+            docker_cmd += ["-e", f"{key}={value}"]
+
+        docker_cmd += [self.container_name] + cmd
+
+        try:
+            result = shell_run(cmd=docker_cmd, check=False, capture=True)
+            return RunnerResult(
+                stdout=result.stdout or "",
+                stderr=result.stderr or "",
+                exit_code=result.returncode,
+            )
+        except subprocess.CalledProcessError as e:
+            return RunnerResult(
+                stdout=e.stdout or "",
+                stderr=e.stderr or "",
+                exit_code=e.returncode,
+            )
+
+    # --- Utilities ---
+    def rebase_path(self, host_path: str | Path) -> str:
+        """Rebase a host path to its equivalent inside the container.
+
+        Example:
+            host:      /home/user/project/src/MyFile.php
+            mount:     /home/user/project → /var/www/html
+            result:    /var/www/html/src/MyFile.php
+        """
+        host_path = Path(host_path).resolve()
+        mount_host = Path(list(self.volumes.keys())[0]).resolve()
+        container_root = list(self.volumes.values())[0]
+        relative = host_path.relative_to(mount_host)
+        return f"{container_root.rstrip('/')}/{relative}"
+
+    def start(self) -> None:
+        import os
+
+        from wexample_helpers.helpers.docker import (
+            docker_container_exists,
+            docker_container_is_running,
+            docker_run_container,
+            docker_start_container,
+        )
+
+        if docker_container_exists(self.container_name):
+            if not docker_container_is_running(self.container_name):
+                docker_start_container(self.container_name)
+        else:
+            user = f"{os.getuid()}:{os.getgid()}"
+            docker_run_container(
+                self.container_name,
+                self.image_name,
+                volumes=self.volumes,
+                user=user,
+            )
+
+    def stop(self) -> None:
+        from wexample_helpers.helpers.docker import (
+            docker_container_is_running,
+            docker_stop_container,
+        )
+
+        if docker_container_is_running(self.container_name):
+            docker_stop_container(self.container_name)
+
+    def _build_container_name(self) -> str:
+        from wexample_helpers.helpers.docker import docker_build_name_from_path
+
+        anchor = list(self.volumes.keys())[0] if self.volumes else self.image_name
+        return docker_build_name_from_path(root_path=anchor, image_name=self.image_name)

wexample_runner/runner/local_runner.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from wexample_runner.runner.abstract_runner import AbstractRunner
+from wexample_runner.runner_result import RunnerResult
+
+
+class LocalRunner(AbstractRunner):
+    """Execute commands on the local machine via subprocess."""
+
+    @property
+    def is_built(self) -> bool:
+        return True
+
+    @property
+    def is_running(self) -> bool:
+        return True
+
+    def execute(
+        self,
+        cmd: list[str] | str,
+        workdir: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> RunnerResult:
+        from wexample_helpers.helpers.shell import shell_run
+
+        result = shell_run(
+            cmd=cmd,
+            cwd=workdir,
+            env=env,
+            check=False,
+            capture=True,
+        )
+
+        return RunnerResult(
+            stdout=result.stdout or "",
+            stderr=result.stderr or "",
+            exit_code=result.returncode,
+        )

wexample_runner/runner/ssh_runner.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from wexample_runner.runner.abstract_runner import AbstractRunner
+from wexample_runner.runner_result import RunnerResult
+
+
+class SshRunner(AbstractRunner):
+    """Execute commands on a remote server via SSH (using paramiko).
+
+    Supports key-based and password authentication.
+    The connection is opened on start() and closed on stop().
+    """
+
+    def __init__(
+        self,
+        host: str,
+        user: str = "root",
+        port: int = 22,
+        key_path: str | None = None,
+        password: str | None = None,
+        ephemeral: bool = False,
+    ) -> None:
+        super().__init__(ephemeral=ephemeral)
+        self.host = host
+        self.user = user
+        self.port = port
+        self.key_path = key_path
+        self.password = password
+        self._client = None
+
+    @property
+    def is_built(self) -> bool:
+        return True
+
+    # --- Properties ---
+    @property
+    def is_running(self) -> bool:
+        return (
+            self._client is not None
+            and self._client.get_transport() is not None
+            and self._client.get_transport().is_active()
+        )
+
+    # --- Lifecycle ---
+    def build(self) -> None:
+        """No build step needed for SSH — connectivity is checked on start()."""
+
+    def destroy(self) -> None:
+        """No remote resources to destroy — just close the connection."""
+        self.stop()
+
+    # --- Execution ---
+    def execute(
+        self,
+        cmd: list[str] | str,
+        workdir: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> RunnerResult:
+        if self._client is None:
+            raise RuntimeError(
+                "SshRunner is not started. Call start() or use as context manager."
+            )
+
+        if isinstance(cmd, list):
+            import shlex
+
+            cmd = shlex.join(cmd)
+
+        if workdir:
+            cmd = f"cd {shlex.quote(workdir)} && {cmd}"
+
+        if env:
+            env_prefix = " ".join(f"{k}={shlex.quote(v)}" for k, v in env.items())
+            cmd = f"{env_prefix} {cmd}"
+
+        _, stdout, stderr = self._client.exec_command(cmd)
+        exit_code = stdout.channel.recv_exit_status()
+
+        return RunnerResult(
+            stdout=stdout.read().decode("utf-8", errors="replace"),
+            stderr=stderr.read().decode("utf-8", errors="replace"),
+            exit_code=exit_code,
+        )
+
+    def start(self) -> None:
+        import paramiko
+
+        client = paramiko.SSHClient()
+        client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+        client.connect(
+            hostname=self.host,
+            port=self.port,
+            username=self.user,
+            key_filename=self.key_path,
+            password=self.password,
+        )
+        self._client = client
+
+    def stop(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None

wexample_runner/runner_config.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class RunnerConfig:
+    """Declarative configuration for a runner attached to a workdir.
+
+    Attributes:
+        dockerfile:       Path to the Dockerfile, relative to the workdir root.
+                          Convention: .wex/docker/Dockerfile.{runner_name}
+        image_name:       Docker image name. Defaults to "wex-{runner_name}".
+        mount_path:       Host path to mount inside the container.
+                          Defaults to the workdir's own path.
+        container_workdir: Working directory inside the container.
+        volumes:          Additional volume mappings {host: container}.
+        ephemeral:        If True, destroy the container after each runner_exec call.
+    """
+
+    dockerfile: str | Path
+
+    container_workdir: str = "/var/www/html"
+    ephemeral: bool = False
+    image_name: str = ""
+    mount_path: str | Path | None = None
+    volumes: dict[str, str] = field(default_factory=dict)

wexample_runner/runner_registry.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_runner.abstract_runner import AbstractRunner
+
+
+class RunnerRegistry:
+    """Global registry of named runners.
+
+    Allows packages to register runners by name and retrieve them later,
+    providing a central place to inspect the state of all known environments.
+    """
+
+    _runners: dict[str, AbstractRunner] = {}
+
+    @classmethod
+    def all(cls) -> dict[str, AbstractRunner]:
+        return dict(cls._runners)
+
+    @classmethod
+    def get(cls, name: str) -> AbstractRunner | None:
+        return cls._runners.get(name)
+
+    @classmethod
+    def get_or_raise(cls, name: str) -> AbstractRunner:
+        runner = cls.get(name)
+        if runner is None:
+            raise KeyError(f"No runner registered under name '{name}'.")
+        return runner
+
+    @classmethod
+    def register(cls, name: str, runner: AbstractRunner) -> None:
+        cls._runners[name] = runner
+
+    @classmethod
+    def status(cls) -> list[dict]:
+        """Return a list of dicts describing the state of each registered runner."""
+        return [
+            {
+                "name": name,
+                "type": type(runner).__name__,
+                "is_built": runner.is_built,
+                "is_running": runner.is_running,
+                "ephemeral": runner.ephemeral,
+            }
+            for name, runner in cls._runners.items()
+        ]

wexample_runner/runner_result.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RunnerResult:
+    exit_code: int
+    stderr: str
+    stdout: str
+
+    def is_success(self) -> bool:
+        return self.exit_code == 0
+
+    def raise_on_error(self) -> None:
+        if not self.is_success():
+            raise RuntimeError(
+                f"Command failed (exit {self.exit_code}):\n{self.stderr or self.stdout}"
+            )

wexample_runner-0.0.3.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.1
+Name: wexample-runner
+Version: 0.0.3
+Summary: Generic runner abstraction for executing commands in different environments (local, Docker, SSH).
+Author-Email: weeger <contact@wexample.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Project-URL: homepage, https://github.com/wexample/python-runner
+Requires-Python: >=3.10
+Requires-Dist: paramiko>=3.0.0
+Requires-Dist: wexample-helpers>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# runner
+
+Version: 0.0.3
+
+Generic runner abstraction for executing commands in different environments (local, Docker, SSH).
+
+## Table of Contents
+
+- [Tests](#tests)
+- [Suite Integration](#suite-integration)
+- [Dependencies](#dependencies)
+- [Versioning](#versioning)
+- [License](#license)
+- [Suite Integration](#suite-integration)
+- [Suite Signature](#suite-signature)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+## Dependencies
+
+- paramiko: >=3.0.0
+- wexample-helpers: >=0.7.0
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Free to use in both personal and commercial projects.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-runner/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-runner
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-runner/issues
+- **Discussions**: https://github.com/wexample/python-runner/discussions
+- **PyPI**: [pypi.org/project/runner](https://pypi.org/project/runner/)
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.

wexample_runner-0.0.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+wexample_runner-0.0.3.dist-info/METADATA,sha256=8OAYFSLjlu3wMQolvhzAYwDpf8BXrXmxly5n5cIBUs0,5991
+wexample_runner-0.0.3.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
+wexample_runner-0.0.3.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+wexample_runner/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wexample_runner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wexample_runner/runner/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wexample_runner/runner/abstract_runner.py,sha256=n0vKbAXDbuvTJ-oQGlLmQx0pipTkKf5hIDTmsYb_udI,1637
+wexample_runner/runner/docker_runner.py,sha256=Bh0Vdpg48QC-8Lo6YPt9rLK8vNT5hAgtHnq4RBhy8DE,5571
+wexample_runner/runner/local_runner.py,sha256=-ijSPs8BjJj2zWU9tzb9Ifdlqdh1QTQYW1eogWrGC0I,937
+wexample_runner/runner/ssh_runner.py,sha256=flaDqstChTlTISkWrMoSSVML9YUiLVLAVqBfi2wcgJg,2920
+wexample_runner/runner_config.py,sha256=1fXz2fqqxQOObzHaWpl6WRF-88JFD_taX2ku97KVq-E,1042
+wexample_runner/runner_registry.py,sha256=lzIOG_HRoLeRBtwiCc8uJxZhqw9BusO0IzNtjDNcVCI,1442
+wexample_runner/runner_result.py,sha256=elCht9CnUuPP__H5H56accw7iAF3lznXggKPnSqmMjI,432
+wexample_runner-0.0.3.dist-info/RECORD,,

wexample_runner-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.8)
+Root-Is-Purelib: true
+Tag: py3-none-any

wexample_runner-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+