shelltastic 0.5.0__tar.gz → 0.7.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "shelltastic"
-version = "0.5.0"
+version = "0.7.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.7.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.7.0}/src/shelltastic/backend/default/common.py

@@ -1,20 +1,20 @@
-from __future__ import annotations
-
 import logging
 import os
 import shlex
 import subprocess
 import time
+from io import RawIOBase
+from multiprocessing import Pipe
+from multiprocessing.connection import Connection
 from multiprocessing.pool import ThreadPool
-from typing import IO, TYPE_CHECKING, Literal
+from pathlib import Path
+from typing import IO, Literal
 
 from shelltastic import display
 from shelltastic.backend.base import ShellBackend
 from shelltastic.enum import CaptureMode, DisplayMode
-from shelltastic.result import ShellResult
-
-if TYPE_CHECKING:
-    from pathlib import Path
+from shelltastic.io import PipeReader
+from shelltastic.result import ShellResult, ShellResultAsync
 
 LOGGER = logging.getLogger(__name__)
 
@@ -87,26 +87,27 @@ class IOTimeoutStream:
                 return return_val
 
 
-def _output_and_collect(
-    io: IO[bytes] | None, display: display.IODisplay | None, collect: bool = True
-) -> bytes | None:
-    if io is None:
-        return None
+def _output_and_pipe(
+    io: IO[bytes] | None, display: display.IODisplay | None, pipe: Connection | None
+) -> None:
+    try:
+        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 collect:
         if display:
-            return_bytes: bytes = b""
             for line in IOTimeoutStream(io):
-                return_bytes += line
                 display.printbytes(line)
-            return return_bytes
-        return io.read()
-
-    if display:
-        for line in IOTimeoutStream(io):
-            display.printbytes(line)
-
-    return None
+    finally:
+        if pipe:
+            pipe.close()
 
 
 def _determine_subprocess_output_mode(
@@ -119,6 +120,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 +133,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 +146,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 +157,126 @@ 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_capture: CaptureMode | None,
+        stderr_capture: CaptureMode | None,
+        stdout_display: display.IODisplay | None,
+        stderr_display: display.IODisplay | None,
+        check: bool,
+    ) -> None:
+        _display_pool = None
+        _stdout_async_result = None
+        _stderr_async_result = None
+
+        if popen.stdout:
+            # If stdout is PIPE, then setup reader
+            if stdout_capture == CaptureMode.PIPE:
+                stdout_rcv, stdout_snd = Pipe(False)
+                stdout = PipeReader(stdout_rcv)
+            else:
+                stdout_snd = None
+                stdout = None
+
+            if stdout_snd or stdout_display:
+                if _display_pool is None:
+                    _display_pool = ThreadPool(2)
+
+                _stdout_async_result=_display_pool.apply_async(
+                    _output_and_pipe,
+                    args=[
+                        popen.stdout,
+                        stdout_display,
+                        stdout_snd,
+                    ],
+                )
+        else:
+            stdout = None
+
+        if popen.stderr:
+            if stderr_capture == CaptureMode.PIPE:
+                stderr_rcv, stderr_snd = Pipe(False)
+                stderr = PipeReader(stderr_rcv)
+            else:
+                stderr_snd = None
+                stderr = None
+
+            if stderr_snd or stderr_display:
+                if _display_pool is None:
+                    _display_pool = ThreadPool(2)
+
+                _stderr_async_result = _display_pool.apply_async(
+                    _output_and_pipe,
+                    args=[
+                        popen.stderr,
+                        stderr_display,
+                        stderr_snd,
+                    ],
+                )
+        else:
+            stderr = None
+
+        super().__init__(cmd, stdout, stderr)
+
+        self._display_pool = _display_pool
+        self._stdout_async_result = _stdout_async_result
+        self._stderr_async_result = _stderr_async_result
+        self._popen = popen
+        self._check = check
+
+    def __exit__(self, exc_type, exc, tb):
+        # Wait for command to finish before closing everything
+        self.wait()
+
+        print("closing popen")
+        # Close popen
+        self._popen.__exit__(exc_type, exc, tb)
+
+        if self._display_pool:
+            print("closing _display_pool")
+            self._display_pool.__exit__(exc_type, exc, tb)
+
+        # Close stdout and stderr
+        if self.stdout:
+            print("closing stdout")
+            self.stdout.close()
+        if self.stderr:
+            print("closing stderr")
+            self.stderr.close()
+
+    def close(self) -> None:
+        self.__exit__(None, None, None)
+
+    def terminate(self) -> None:
+        self._popen.terminate()
+        self.close()
+
+    def result(self) -> ShellResult[RawIOBase | None, RawIOBase | None]:
+        # Get result
+        result = ShellResult(
+            cmd=self.cmd,
+            returncode=self._popen.wait(),
+            stdout=self.stdout,
+            stderr=self.stderr,
+        )
+
+        # Wait for our async reader to be complete
+        if self._stdout_async_result:
+            self._stdout_async_result.wait()
+
+        if self._stderr_async_result:
+            self._stderr_async_result.wait()
+
+        # Check if set
+        if self._check:
+            result.check_returncode()
+
+        return result
+
+
 class CommonDefaultBackend(ShellBackend):
     __slots__ = ()
 
@@ -168,7 +292,33 @@ class CommonDefaultBackend(ShellBackend):
         cwd: str | Path | None = None,
         echo_cmd: DisplayMode | display.IODisplay | bool | None = None,
         **kwargs,
-    ) -> ShellResult:
+    ) -> ShellResult[bytes | None, bytes | None]:
+        with self.run_async(
+            cmd,
+            check=check,
+            stdout=stdout,
+            stderr=stderr,
+            stdout_display=stdout_display,
+            stderr_display=stderr_display,
+            cwd=cwd,
+            echo_cmd=echo_cmd,
+            **kwargs,
+        ) as running_cmd:
+            return running_cmd.result_bytes()
+
+    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())}")
 
@@ -215,57 +365,28 @@ class CommonDefaultBackend(ShellBackend):
             )
 
         # Run subprocess command
-        with (
-            subprocess.Popen(
-                cmd,
-                shell=shell,
-                stdout=stdout_sub_mode,
-                stderr=stderr_sub_mode,
-                cwd=cwd,
-            ) as popen,
-            ThreadPool(2) as display_pool,
-        ):
-            # Print out and capture stdout
-            stdout_result = display_pool.apply_async(
-                _output_and_collect,
-                args=[
-                    popen.stdout,
-                    (
-                        stdout_display
-                        if isinstance(stdout_display, display.IODisplay)
-                        else display.from_mode(stdout_display)
-                    ),
-                    stdout is not None and stdout != CaptureMode.DEVNULL,
-                ],
-            )
-
-            # Print out and capture stderr
-            stderr_result = display_pool.apply_async(
-                _output_and_collect,
-                args=[
-                    popen.stderr,
-                    (
-                        stderr_display
-                        if isinstance(stderr_display, display.IODisplay)
-                        else display.from_mode(stderr_display)
-                    ),
-                    stderr is not None and stderr != CaptureMode.DEVNULL,
-                ],
-            )
-
-            # Wait on command completion
-            returncode = popen.wait()
-
-            # Build our result
-            result = ShellResult(
-                cmd=cmd,
-                stdout=stdout_result.get(),
-                stderr=stderr_result.get(),
-                returncode=returncode,
-            )
-
-        # If check is True, raise exception if returncode is not 0
-        if check:
-            result.check_returncode()
+        popen = subprocess.Popen(
+            cmd,
+            shell=shell,
+            stdout=stdout_sub_mode,
+            stderr=stderr_sub_mode,
+            cwd=cwd,
+        )
 
-        return result
+        return CommonShellAcyncResult(
+            cmd=cmd,
+            popen=popen,
+            stdout_capture=stdout,
+            stderr_capture=stderr,
+            stdout_display=(
+                stdout_display
+                if isinstance(stdout_display, display.IODisplay)
+                else display.from_mode(stdout_display)
+            ),
+            stderr_display=(
+                stderr_display
+                if isinstance(stderr_display, display.IODisplay)
+                else display.from_mode(stderr_display)
+            ),
+            check=check,
+        )

{shelltastic-0.5.0 → shelltastic-0.7.0}/src/shelltastic/backend/default/local.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import logging
 
 from shelltastic.backend.base import LocalShellBackend

{shelltastic-0.5.0 → shelltastic-0.7.0}/src/shelltastic/backend/default/remote.py

@@ -1,19 +1,13 @@
-from __future__ import annotations
-
 import logging
 import shlex
-from typing import TYPE_CHECKING
+from pathlib import Path
 
 from shelltastic.backend.base import RemoteShellBackend
 from shelltastic.backend.default.common import CommonDefaultBackend
 from shelltastic.enum import CaptureMode
 from shelltastic.exception import ShellException, SSHConnectionError
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-    from shelltastic.host import Host
-    from shelltastic.result import ShellResult
+from shelltastic.host import Host
+from shelltastic.result import ShellResult
 
 LOGGER = logging.getLogger(__name__)
 

{shelltastic-0.5.0 → shelltastic-0.7.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.7.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.7.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.7.0/src/shelltastic/result.py

@@ -0,0 +1,101 @@
+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):
+    """
+    An asynchronsly running shell command.
+
+    cmd: String for the running shell command.
+
+    stdout: Bytes stream for stdout
+
+    stderr: Bytes stream for stderr
+    """
+
+    def __init__(self, cmd: str | list[str], stdout: SO, stderr: SE) -> None:
+        self.cmd = cmd
+        """The running command"""
+
+        self.stdout = stdout
+        """Byte based IO stream for stdout"""
+
+        self.stderr = stderr
+        """Byte based IO stream for stderr"""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    def close(self) -> None:
+        """Close the running command."""
+        return
+
+    def terminate(self) -> None:
+        """Terminate the running command"""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def result(self) -> ShellResult[SO, SE]:
+        """
+        Blocking
+
+        Wait for the command to finish and return a ShellResult with the outcome.
+        """
+        raise NotImplementedError()
+
+    def wait(self) -> None:
+        """
+        Blocking
+
+        Wait for the command to finish.
+        """
+        self.result()
+
+    def returncode(self) -> int:
+        """
+        Blocking
+
+        Get the returncode of the command.
+        """
+        return self.result().returncode
+
+    def check_returncode(self):
+        """
+        Blocking
+
+        Raise a ShellException if the returncode is not zero.
+        """
+        self.result().check_returncode()
+
+    def result_bytes(self) -> ShellResult[bytes | None, bytes | None]:
+        result = self.result()
+        stdout = result.stdout
+        stdout_bytes = stdout.readall() if stdout is not None else None
+        stderr = result.stderr
+        stderr_bytes = stderr.readall() if stderr is not None else None
+
+        return ShellResult(
+            cmd=result.cmd,
+            returncode=result.returncode,
+            stdout=stdout_bytes,
+            stderr=stderr_bytes,
+        )

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)