shelltastic 0.5.0__tar.gz → 0.6.0__tar.gz

{shelltastic-0.5.0 → shelltastic-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shelltastic
-Version: 0.5.0
+Version: 0.6.0
 Summary: A fantastic shell command runner for python
 Author: Bearmine
 License-Expression: MPL-2.0

{shelltastic-0.5.0 → shelltastic-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shelltastic"
-version = "0.5.0"
+version = "0.6.0"
 description = "A fantastic shell command runner for python"
 readme = "README.md"
 authors = [
@@ -43,3 +43,15 @@ extend-select = [
 
 [tool.ruff.lint.pycodestyle]
 max-line-length = 100
+
+[dependency-groups]
+dev = [
+  {include-group = "lint"},
+  {include-group = "test"}
+]
+lint = [
+  "ruff"
+]
+test = [
+  "pytest"
+]

{shelltastic-0.5.0 → shelltastic-0.6.0}/src/shelltastic/backend/base.py

@@ -5,22 +5,26 @@ from functools import wraps
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    from io import RawIOBase
     from pathlib import Path
 
     from shelltastic.display import IODisplay
     from shelltastic.enum import CaptureMode, DisplayMode
     from shelltastic.host import Host
-    from shelltastic.result import ShellResult
+    from shelltastic.result import ShellResult, ShellResultAsync
 
 
 class BackendShimResult:
+    __slots__ = ("args", "kwargs")
+
     def __init__(self, *args, **kwargs) -> None:
         self.args = args
         self.kwargs = kwargs
 
 
 class BackendShim(ABC):
-    @abstractmethod
+    __slots__ = ()
+
     def run_shim(
         self,
         backend_type: type,
@@ -31,15 +35,33 @@ class BackendShim(ABC):
         """
         Shim for run() method of `ShellBackend`
 
+        Use `self.result(...)` to create and return a `BackendShimResult`
+
+        ```python
+        return self.result(*args, **kwargs)
+        ```
+        """
+        return self.result(*args, **kwargs)
+
+    def run_async_shim(
+        self,
+        backend_type: type,
+        /,
+        *args,
+        **kwargs,
+    ) -> BackendShimResult:
+        """
+        Shim for run() method of `ShellBackend`
+
         Use `self.run(...)` to create and return a `BackendShimResult`
 
         ```python
         return self.run(*args, **kwargs)
         ```
         """
-        raise NotImplementedError()
+        return self.result(*args, **kwargs)
 
-    def run(
+    def result(
         self,
         cmd: str | list[str],
         *,
@@ -80,7 +102,9 @@ def _shim_run(f, backend_type: type):
     def wrapper(*args, **kwargs):
         result: BackendShimResult = BackendShimResult(*args, **kwargs)
         for shim in _backend_shims:
-            result = shim.run_shim(backend_type, *result.args, **result.kwargs)
+            result = shim.run_shim(
+                backend_type, f.__name__, *result.args, **result.kwargs
+            )
         return f(*result.args, **result.kwargs)
 
     return wrapper
@@ -90,6 +114,7 @@ class _InstallShims(ABCMeta):
     def __call__(self, *args: Any, **kwds: Any) -> Any:
         instance = super().__call__(*args, **kwds)
         instance.run = _shim_run(instance.run, instance.__class__)
+        instance.run_async = _shim_run(instance.run_async, instance.__class__)
         return instance
 
 
@@ -109,7 +134,23 @@ class ShellBackend(metaclass=_InstallShims):
         cwd: str | Path | None = None,
         echo_cmd: DisplayMode | IODisplay | bool | None = None,
         **kwargs,
-    ) -> ShellResult:
+    ) -> ShellResult[bytes | None, bytes | None]:
+        raise NotImplementedError()
+
+    @abstractmethod
+    def run_async(
+        self,
+        cmd: str | list[str],
+        *,
+        check: bool = True,
+        stdout: CaptureMode | None = None,
+        stderr: CaptureMode | None = None,
+        stdout_display: DisplayMode | IODisplay | None = None,
+        stderr_display: DisplayMode | IODisplay | None = None,
+        cwd: str | Path | None = None,
+        echo_cmd: DisplayMode | IODisplay | bool | None = None,
+        **kwargs,
+    ) -> ShellResultAsync[RawIOBase | None, RawIOBase | None]:
         raise NotImplementedError()
 
 

{shelltastic-0.5.0 → shelltastic-0.6.0}/src/shelltastic/backend/default/common.py

@@ -5,15 +5,19 @@ import os
 import shlex
 import subprocess
 import time
+from io import RawIOBase
+from multiprocessing import Pipe
 from multiprocessing.pool import ThreadPool
 from typing import IO, TYPE_CHECKING, Literal
 
 from shelltastic import display
 from shelltastic.backend.base import ShellBackend
 from shelltastic.enum import CaptureMode, DisplayMode
-from shelltastic.result import ShellResult
+from shelltastic.io import PipeReader
+from shelltastic.result import ShellResult, ShellResultAsync
 
 if TYPE_CHECKING:
+    from multiprocessing.connection import Connection
     from pathlib import Path
 
 LOGGER = logging.getLogger(__name__)
@@ -109,6 +113,25 @@ def _output_and_collect(
     return None
 
 
+def _output_and_pipe(
+    io: IO[bytes] | None, display: display.IODisplay | None, pipe: Connection | None
+) -> None:
+    if io is None:
+        return
+
+    if pipe:
+        if display:
+            for line in IOTimeoutStream(io):
+                pipe.send_bytes(line)
+                display.printbytes(line)
+        for line in IOTimeoutStream(io):
+            pipe.send_bytes(line)
+
+    if display:
+        for line in IOTimeoutStream(io):
+            display.printbytes(line)
+
+
 def _determine_subprocess_output_mode(
     capture_mode: CaptureMode | None,
     display_mode: DisplayMode | display.IODisplay | None,
@@ -119,6 +142,8 @@ def _determine_subprocess_output_mode(
         if capture_mode == CaptureMode.PIPE:
             return subprocess.PIPE
         if capture_mode == CaptureMode.STDOUT:
+            if output_name == "stdout":
+                raise ValueError("stdout cannot be piped to stdout")
             return subprocess.STDOUT
         if capture_mode == CaptureMode.DEVNULL:
             return subprocess.DEVNULL
@@ -130,8 +155,7 @@ def _determine_subprocess_output_mode(
             return subprocess.PIPE
         if capture_mode == CaptureMode.STDOUT:
             if output_name == "stdout":
-                # stdout
-                return subprocess.PIPE
+                raise ValueError("stdout cannot be piped to stdout")
             # stderr
             return subprocess.STDOUT
         if capture_mode == CaptureMode.DEVNULL:
@@ -144,6 +168,8 @@ def _determine_subprocess_output_mode(
     if capture_mode == CaptureMode.PIPE:
         return subprocess.PIPE
     if capture_mode == CaptureMode.STDOUT:
+        if output_name == "stdout":
+            raise ValueError("stdout cannot be piped to stdout")
         return subprocess.STDOUT
     if capture_mode == CaptureMode.DEVNULL:
         # We need to PIPE to be able to print the output
@@ -153,6 +179,56 @@ def _determine_subprocess_output_mode(
     return subprocess.PIPE
 
 
+class CommonShellAcyncResult(ShellResultAsync[RawIOBase | None, RawIOBase | None]):
+    def __init__(
+        self,
+        cmd: str | list[str],
+        popen: subprocess.Popen,
+        stdout_display: display.IODisplay | None,
+        stderr_display: display.IODisplay | None,
+    ) -> None:
+        stdout_rcv, stdout_snd = Pipe(False)
+        stderr_rcv, stderr_snd = Pipe(False)
+        super().__init__(cmd, PipeReader(stdout_rcv), PipeReader(stderr_rcv))
+        self._popen = popen
+        self._display_pool = ThreadPool(2)
+
+        # Print out and capture stdout
+        self._stdout_result = self._display_pool.apply_async(
+            _output_and_pipe,
+            args=[
+                popen.stdout,
+                stdout_display,
+                stdout_snd,
+            ],
+        )
+
+        # Print out and capture stderr
+        self._stderr_result = self._display_pool.apply_async(
+            _output_and_pipe,
+            args=[
+                popen.stderr,
+                stderr_display,
+                stderr_snd,
+            ],
+        )
+
+    def __exit__(self, exc_type, exc, tb):
+        self._popen.__exit__(exc_type, exc, tb)
+        self._display_pool.__exit__(exc_type, exc, tb)
+
+    def close(self) -> None:
+        self.__exit__(None, None, None)
+
+    def result(self) -> ShellResult[RawIOBase | None, RawIOBase | None]:
+        return ShellResult(
+            cmd=self.cmd,
+            returncode=self._popen.wait(),
+            stdout=self.stdout,
+            stderr=self.stderr,
+        )
+
+
 class CommonDefaultBackend(ShellBackend):
     __slots__ = ()
 
@@ -168,7 +244,7 @@ class CommonDefaultBackend(ShellBackend):
         cwd: str | Path | None = None,
         echo_cmd: DisplayMode | display.IODisplay | bool | None = None,
         **kwargs,
-    ) -> ShellResult:
+    ) -> ShellResult[bytes | None, bytes | None]:
         if kwargs:
             raise TypeError(f"Uknown argument/s {list(kwargs.keys())}")
 
@@ -269,3 +345,85 @@ class CommonDefaultBackend(ShellBackend):
             result.check_returncode()
 
         return result
+
+    def run_async(
+        self,
+        cmd: str | list[str],
+        *,
+        check: bool = True,
+        stdout: CaptureMode | None = None,
+        stderr: CaptureMode | None = None,
+        stdout_display: DisplayMode | display.IODisplay | None = None,
+        stderr_display: DisplayMode | display.IODisplay | None = None,
+        cwd: str | Path | None = None,
+        echo_cmd: DisplayMode | display.IODisplay | bool | None = None,
+        **kwargs,
+    ) -> ShellResultAsync[RawIOBase | None, RawIOBase | None]:
+        if kwargs:
+            raise TypeError(f"Uknown argument/s {list(kwargs.keys())}")
+
+        # If cmd is a str, run as shell
+        shell = isinstance(cmd, str)
+
+        # Echo command based on setting
+        # Defaults to DEBUG_LOG
+        # False to disable
+        if isinstance(echo_cmd, bool):
+            echo_cmd = DisplayMode.STDOUT if echo_cmd else DisplayMode.DEVNULL
+
+        if echo_cmd is None:
+            echo_cmd = DisplayMode.DEBUG_LOG
+
+        if isinstance(echo_cmd, display.IODisplay):
+            echo_display = echo_cmd
+        else:
+            echo_display = display.from_mode(echo_cmd)
+
+        if isinstance(cmd, str):
+            echo_display.printline("%s> %s", cwd or "", cmd)
+        else:
+            echo_display.printline("%s> %s", cwd or "", shlex.join(cmd))
+
+        # Determine PIPE mode for stdout
+        stdout_sub_mode = _determine_subprocess_output_mode(
+            stdout, stdout_display, "stdout"
+        )
+
+        # Determine PIPE mode for stderr
+        stderr_sub_mode = _determine_subprocess_output_mode(
+            stderr, stderr_display, "stderr"
+        )
+
+        if stdout_display is None:
+            stdout_display = (
+                DisplayMode.STDOUT if stdout is None else DisplayMode.DEVNULL
+            )
+
+        if stderr_display is None:
+            stderr_display = (
+                DisplayMode.STDERR if stderr is None else DisplayMode.DEVNULL
+            )
+
+        # Run subprocess command
+        popen = subprocess.Popen(
+            cmd,
+            shell=shell,
+            stdout=stdout_sub_mode,
+            stderr=stderr_sub_mode,
+            cwd=cwd,
+        )
+
+        return CommonShellAcyncResult(
+            cmd,
+            popen,
+            (
+                stdout_display
+                if isinstance(stdout_display, display.IODisplay)
+                else display.from_mode(stdout_display)
+            ),
+            (
+                stderr_display
+                if isinstance(stderr_display, display.IODisplay)
+                else display.from_mode(stderr_display)
+            ),
+        )

{shelltastic-0.5.0 → shelltastic-0.6.0}/src/shelltastic/exception.py

@@ -1,3 +1,6 @@
+from io import RawIOBase
+
+
 class SSHConnectionError(Exception):
     def __init__(
         self, hostname: str, returncode: int, stdout: bytes | None, stderr: bytes | None
@@ -12,13 +15,13 @@ class SSHConnectionError(Exception):
         self.stderr = stderr
 
 
-class ShellException(Exception):
+class ShellException[SO: RawIOBase | bytes | None, SE: RawIOBase | bytes | None](Exception):
     def __init__(
         self,
         cmd: str | list[str],
         returncode: int,
-        stdout: bytes | None,
-        stderr: bytes | None,
+        stdout: SO,
+        stderr: SE,
     ):
         super().__init__(f"Shell execution failed with returncode {returncode}")
         self.cmd = cmd

{shelltastic-0.5.0 → shelltastic-0.6.0}/src/shelltastic/frontend/shell.py

@@ -9,10 +9,12 @@ from shelltastic.enum import CaptureMode, DisplayMode, SystemType
 from shelltastic.frontend.common import RemoteFrontend, RemoteFrontendFactory
 
 if TYPE_CHECKING:
+    from io import RawIOBase
+
     from shelltastic.backend.base import ShellBackend
     from shelltastic.display import IODisplay
     from shelltastic.host import Host
-    from shelltastic.result import ShellResult
+    from shelltastic.result import ShellResult, ShellResultAsync
 
 
 class ShellFrontend:
@@ -74,7 +76,7 @@ class ShellFrontend:
         cwd: str | Path | None = None,
         echo_cmd: DisplayMode | IODisplay | bool | None = None,
         **kwargs,
-    ) -> ShellResult:
+    ) -> ShellResult[bytes | None, bytes | None]:
         """Run a shell command"""
         return self._backend.run(
             cmd,
@@ -88,6 +90,31 @@ class ShellFrontend:
             **kwargs,
         )
 
+    def run_async(
+        self,
+        cmd: str | list[str],
+        *,
+        check: bool = True,
+        stdout: CaptureMode | None = None,
+        stderr: CaptureMode | None = None,
+        stdout_display: DisplayMode | IODisplay | None = None,
+        stderr_display: DisplayMode | IODisplay | None = None,
+        cwd: str | Path | None = None,
+        echo_cmd: DisplayMode | IODisplay | bool | None = None,
+        **kwargs,
+    ) -> ShellResultAsync[RawIOBase | None, RawIOBase | None]:
+        return self._backend.run_async(
+            cmd,
+            check=check,
+            stdout=stdout,
+            stderr=stderr,
+            stdout_display=stdout_display,
+            stderr_display=stderr_display,
+            cwd=cwd,
+            echo_cmd=echo_cmd,
+            **kwargs,
+        )
+
 
 class RemoteShellFrontend(ShellFrontend, RemoteFrontend):
     __slots__ = ()

shelltastic-0.6.0/src/shelltastic/io.py

@@ -0,0 +1,59 @@
+from io import RawIOBase
+from multiprocessing.connection import Connection
+
+
+class PipeReader(RawIOBase):
+    def __init__(self, receiver: Connection) -> None:
+        super().__init__()
+        if not receiver.readable:
+            raise TypeError("Receiver Connection must be readable")
+        self.receiver = receiver
+        self._last_byte_read: bytes | None = None
+
+    def readinto(self, buffer) -> int:
+        # Fill buffer or flush last read
+        with memoryview(buffer) as buf:
+            # If there's nothing in our buffer, read bytes
+            if self._last_byte_read is None:
+                try:
+                    self._last_byte_read = self.receiver.recv_bytes()
+                except EOFError:
+                    return 0
+
+            if len(buf) >= len(self._last_byte_read):
+                # Buffer is bigger than read bytes
+                size = len(self._last_byte_read)
+                buf[0:size] = self._last_byte_read
+                self._last_byte_read = None
+                return size
+
+            # More bytes read than size of buffer
+            size = len(buf)
+            buf[0:size] = self._last_byte_read[0:size]
+            self._last_byte_read = self._last_byte_read[size:]
+            return size
+
+    def readall(self) -> bytes:
+        # Read until EOF
+        if self._last_byte_read is None:
+            self._last_byte_read = b""
+        while True:
+            try:
+                self._last_byte_read = self._last_byte_read + self.receiver.recv_bytes()
+            except EOFError:
+                return self._last_byte_read
+
+    def readable(self) -> bool:
+        return True
+
+    def writable(self) -> bool:
+        return False
+
+    def seekable(self) -> bool:
+        return False
+
+    def fileno(self) -> int:
+        return self.receiver.fileno()
+
+    def close(self) -> None:
+        return self.receiver.close()

shelltastic-0.6.0/src/shelltastic/result.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from io import RawIOBase
+
+from shelltastic.exception import ShellException
+
+
+@dataclass
+class ShellResult[SO: RawIOBase | bytes | None, SE: RawIOBase | bytes | None]:
+    cmd: str | list[str]
+    returncode: int
+    stdout: SO
+    stderr: SE
+
+    def check_returncode(self):
+        """If returncode is not 0, raise ShellException"""
+        if self.returncode != 0:
+            raise ShellException(self.cmd, self.returncode, self.stdout, self.stderr)
+
+
+class ShellResultAsync[SO: RawIOBase | None, SE: RawIOBase | None](ABC):
+    def __init__(self, cmd: str | list[str], stdout: SO, stderr: SE) -> None:
+        self.cmd = cmd
+        self.stdout = stdout
+        self.stderr = stderr
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    def close(self) -> None:
+        return
+
+    @abstractmethod
+    def result(self) -> ShellResult[SO, SE]:
+        raise NotImplementedError()
+
+    def wait(self) -> None:
+        self.result()
+
+    def returncode(self) -> int:
+        return self.result().returncode
+
+    def check_returncode(self):
+        self.result().check_returncode()

shelltastic-0.5.0/src/shelltastic/result.py

@@ -1,16 +0,0 @@
-from dataclasses import dataclass
-
-from shelltastic.exception import ShellException
-
-
-@dataclass
-class ShellResult:
-    cmd: str | list[str]
-    returncode: int
-    stdout: bytes | None
-    stderr: bytes | None
-
-    def check_returncode(self):
-        """If returncode is not 0, raise ShellException"""
-        if self.returncode != 0:
-            raise ShellException(self.cmd, self.returncode, self.stdout, self.stderr)