bashautom 0.1.1__py3-none-any.whl

bashautom/__init__.py

@@ -0,0 +1,5 @@
+from .session import Session, CommandResult
+from .manager import SessionManager
+
+__all__ = ["Session", "CommandResult", "SessionManager"]
+__version__ = "0.1.0"

bashautom/manager.py

@@ -0,0 +1,90 @@
+from typing import Optional
+from .session import Session
+
+
+class SessionManager:
+    """Named session pool. Create, get, and cleanup multiple sessions."""
+    def __init__(self):
+        self._sessions: dict[str, Session] = {}
+
+    def create(
+        self,
+        name: str,
+        shell: str = "/bin/bash",
+        env: Optional[dict] = None,
+        cwd: Optional[str] = None,
+    ) -> Session:
+        """Create a named session. Raises KeyError if name exists."""
+        if name in self._sessions:
+            raise ValueError(f"Session '{name}' already exists. Use get() or close it first.")
+
+        session = Session(shell=shell, env=env, cwd=cwd, name=name)
+        self._sessions[name] = session
+        return session
+
+    def get(self, name: str) -> Session:
+        """Get session by name. Raises KeyError if not found."""
+        if name not in self._sessions:
+            raise KeyError(f"No session named '{name}'. Available: {list(self._sessions.keys())}")
+        return self._sessions[name]
+
+    def get_or_create(
+        self,
+        name: str,
+        shell: str = "/bin/bash",
+        env: Optional[dict] = None,
+        cwd: Optional[str] = None,
+    ) -> Session:
+        """Get or create a session."""
+        if name in self._sessions and self._sessions[name].alive:
+            return self._sessions[name]
+        # Clean up dead session if it exists
+        if name in self._sessions:
+            self._sessions[name].close()
+            del self._sessions[name]
+        return self.create(name, shell=shell, env=env, cwd=cwd)
+
+    def close(self, name: str) -> None:
+        """Close and remove a specific session."""
+        if name in self._sessions:
+            self._sessions[name].close()
+            del self._sessions[name]
+
+    def close_all(self) -> None:
+        """Close everything."""
+        for session in self._sessions.values():
+            try:
+                session.close()
+            except Exception:
+                pass
+        self._sessions.clear()
+
+    @property
+    def names(self) -> list[str]:
+        """List all session names."""
+        return list(self._sessions.keys())
+
+    @property
+    def active(self) -> list[Session]:
+        """List all alive sessions."""
+        return [s for s in self._sessions.values() if s.alive]
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._sessions
+
+    def __len__(self) -> int:
+        return len(self._sessions)
+
+    def __getitem__(self, name: str) -> Session:
+        return self.get(name)
+
+    def __enter__(self) -> "SessionManager":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close_all()
+
+    def __repr__(self) -> str:
+        alive = len(self.active)
+        total = len(self._sessions)
+        return f"<SessionManager sessions={total} alive={alive}>"

bashautom/session.py

@@ -0,0 +1,334 @@
+import os
+import subprocess
+import selectors
+import time
+import secrets
+import signal
+from dataclasses import dataclass, field
+from typing import Optional, Callable
+
+
+@dataclass
+class CommandResult:
+    """Output of Session.execute()."""
+    command: str
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration: float
+    timed_out: bool = False
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out
+
+    def __repr__(self) -> str:
+        status = "OK" if self.success else f"FAIL({self.exit_code})"
+        return f"<CommandResult [{status}] {self.command!r} ({self.duration:.2f}s)>"
+
+
+@dataclass
+class StreamEvent:
+    """Chunk of output from a streaming execute() call."""
+    stream: str          # "stdout" or "stderr"
+    data: str            # the chunk of text
+    timestamp: float     # time.monotonic()
+
+
+class SessionError(Exception):
+    """Raised when the session is in an invalid state."""
+    pass
+
+
+class Session:
+    """Persistent bash session. State carries over between execute() calls."""
+    _TOKEN_PREFIX = "__BASHAUTOM_END_krjyngsczkvmlzqaoxpgudjhkejvbowc__"
+
+    def __init__(
+        self,
+        shell: str = "/bin/bash",
+        env: Optional[dict] = None,
+        cwd: Optional[str] = None,
+        name: Optional[str] = None,
+    ):
+        self.shell = shell
+        self.name = name or f"session-{secrets.token_hex(4)}"
+        self._closed = False
+
+        # Spawn the bash process (non-interactive to avoid input echo on stderr)
+        self._proc = subprocess.Popen(
+            [shell, "--norc", "--noprofile"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            cwd=cwd,
+            # Ensure line-buffered isn't forced; we handle our own buffering
+            bufsize=0,
+            # New process group so we can signal children
+            preexec_fn=os.setsid,
+        )
+
+        # Setup selector for non-blocking reads on stdout and stderr
+        self._sel = selectors.DefaultSelector()
+        os.set_blocking(self._proc.stdout.fileno(), False)
+        os.set_blocking(self._proc.stderr.fileno(), False)
+        self._sel.register(self._proc.stdout, selectors.EVENT_READ, "stdout")
+        self._sel.register(self._proc.stderr, selectors.EVENT_READ, "stderr")
+
+        self._drain(timeout=0.5)
+
+        # Setup: trap SIGINT in bash with a no-op handler so that:
+        # - bash itself survives SIGINT (doesn't exit)
+        # - child processes still get default SIGINT behavior (they die)
+        # This is crucial for timeout support, we SIGINT the process group,
+        # which kills the running child but keeps bash alive for the next command.
+        self._proc.stdin.write(b"trap : INT\n")
+        self._proc.stdin.flush()
+        self._drain(timeout=0.2)
+
+    def _generate_token(self) -> str:
+        """Generate a unique end-of-command token."""
+        return f"{self._TOKEN_PREFIX}{secrets.token_hex(8)}"
+
+    def _drain(self, timeout: float = 0.1) -> tuple[str, str]:
+        """Drain all pending output from stdout/stderr."""
+        stdout_buf = []
+        stderr_buf = []
+        deadline = time.monotonic() + timeout
+
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+
+            # FIXME: _drain can miss output if process writes in bursts > 50ms apart
+            events = self._sel.select(timeout=min(remaining, 0.05))
+            if not events:
+                break
+
+            for key, _ in events:
+                chunk = key.fileobj.read(65536)
+                if chunk:
+                    text = chunk.decode("utf-8", errors="replace")
+                    if key.data == "stdout":
+                        stdout_buf.append(text)
+                    else:
+                        stderr_buf.append(text)
+
+        return "".join(stdout_buf), "".join(stderr_buf)
+
+    def _ensure_alive(self) -> None:
+        """Raise if the session or underlying process is dead."""
+        if self._closed:
+            raise SessionError(f"Session '{self.name}' is closed.")
+        if self._proc.poll() is not None:
+            self._closed = True
+            raise SessionError(
+                f"Session '{self.name}' process exited with code {self._proc.returncode}."
+            )
+
+    def execute(self, command: str, timeout: Optional[float] = None, 
+            stream_callback: Optional[Callable] = None) -> CommandResult:
+        """Run a command. Returns CommandResult.
+        
+        timeout kills the command but keeps the session alive.
+        stream_callback gets StreamEvent objects as output arrives.
+        """
+
+        self._ensure_alive()
+
+        token = self._generate_token()
+        start = time.monotonic()
+
+        # Build the payload
+        payload = (
+            f"{command}\n"
+            f"__bashautom_ec=$?\n"
+            f"echo \"{token}:$__bashautom_ec\"\n"
+        )
+        self._proc.stdin.write(payload.encode("utf-8"))
+        self._proc.stdin.flush()
+
+        # Collect output until we see the token
+        stdout_chunks: list[str] = []
+        stderr_chunks: list[str] = []
+        found_token = False
+        exit_code = -1
+        timed_out = False
+
+        while not found_token:
+            elapsed = time.monotonic() - start
+
+            if timeout is not None and elapsed >= timeout and not timed_out:
+                timed_out = True
+                # Send SIGINT to the process group , kills the child command,
+                # but bash survives thanks to `trap : INT`
+                try:
+                    os.killpg(os.getpgid(self._proc.pid), signal.SIGINT)
+                except ProcessLookupError:
+                    pass
+                # Don't break , continue reading to find the token
+                # (bash will proceed to echo it after the child dies)
+                # Extend the deadline so we can capture the token
+                timeout = elapsed + 3.0
+                continue
+
+            if timed_out and timeout is not None and elapsed >= timeout:
+                # Extended grace period also expired , bail out
+                break
+
+            sel_timeout = None
+            if timeout is not None:
+                sel_timeout = max(0.01, timeout - elapsed)
+
+            events = self._sel.select(timeout=min(sel_timeout or 1.0, 1.0))
+
+            for key, _ in events:
+                chunk = key.fileobj.read(65536)
+                if not chunk:
+                    continue
+
+                text = chunk.decode("utf-8", errors="replace")
+                stream_name = key.data
+
+                if stream_name == "stdout":
+                    # Check if the token is in this chunk
+                    if token in text:
+                        # Split: everything before the token line is real output
+                        lines = text.split("\n")
+                        clean_lines = []
+                        for line in lines:
+                            if token in line:
+                                # Parse exit code from "TOKEN:CODE"
+                                try:
+                                    exit_code = int(line.split(":")[-1].strip())
+                                except (ValueError, IndexError):
+                                    exit_code = -1
+                                found_token = True
+                            else:
+                                clean_lines.append(line)
+                        clean_text = "\n".join(clean_lines)
+                        if clean_text.strip() and stream_callback:
+                            stream_callback(StreamEvent(
+                                stream=stream_name,
+                                data=clean_text,
+                                timestamp=time.monotonic(),
+                            ))
+                        if clean_lines:
+                            stdout_chunks.append(clean_text)
+                    else:
+                        if stream_callback:
+                            stream_callback(StreamEvent(
+                                stream=stream_name,
+                                data=text,
+                                timestamp=time.monotonic(),
+                            ))
+                        stdout_chunks.append(text)
+                else:
+                    if stream_callback:
+                        stream_callback(StreamEvent(
+                            stream=stream_name,
+                            data=text,
+                            timestamp=time.monotonic(),
+                        ))
+                    stderr_chunks.append(text)
+
+            # Check if process died
+            if self._proc.poll() is not None and not found_token:
+                self._closed = True
+                break
+
+        duration = time.monotonic() - start
+
+        stdout_text = "".join(stdout_chunks).strip()
+        stderr_text = "".join(stderr_chunks).strip()
+
+        # Clean up: remove the echo of our payload commands from stdout
+        # (bash -i echoes input lines back to stdout)
+        for noise in [
+            f"__bashautom_ec=$?",
+            f'echo "{token}:$__bashautom_ec"',
+        ]:
+            stdout_text = stdout_text.replace(noise, "")
+        stdout_text = stdout_text.strip()
+
+        return CommandResult(
+            command=command,
+            stdout=stdout_text,
+            stderr=stderr_text,
+            exit_code=exit_code,
+            duration=duration,
+            timed_out=timed_out,
+        )
+
+    def send_signal(self, sig: int = signal.SIGINT) -> None:
+        """Send a signal to the process group."""
+        self._ensure_alive()
+        try:
+            os.killpg(os.getpgid(self._proc.pid), sig)
+        except ProcessLookupError:
+            pass
+
+    def get_cwd(self) -> str:
+        """Current working directory."""
+        result = self.execute("pwd")
+        return result.stdout.strip()
+
+    def get_env(self, var: str) -> Optional[str]:
+        """Read an env var from the session."""
+        result = self.execute(f"echo \"${{{var}}}\"")
+        val = result.stdout.strip()
+        return val if val else None
+
+    # TODO: validate var name in set_env to prevent injection
+    def set_env(self, var: str, value: str) -> None:
+        """Export an env var."""
+        self.execute(f"export {var}={value!r}")
+
+    @property
+    def pid(self) -> int:
+        """PID of the underlying bash process."""
+        return self._proc.pid
+
+    @property
+    def alive(self) -> bool:
+        """True if the session process is still running."""
+        return not self._closed and self._proc.poll() is None
+
+    def close(self) -> None:
+        """Kill the bash process and cleanup."""
+        if self._closed:
+            return
+        self._closed = True
+
+        try:
+            self._sel.unregister(self._proc.stdout)
+            self._sel.unregister(self._proc.stderr)
+        except Exception:
+            pass
+        self._sel.close()
+
+        try:
+            self._proc.stdin.write(b"exit\n")
+            self._proc.stdin.flush()
+            self._proc.wait(timeout=5)
+        except Exception:
+            self._proc.kill()
+            self._proc.wait()
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        status = "alive" if self.alive else "closed"
+        return f"<Session '{self.name}' [{status}] pid={self._proc.pid}>"

bashautom-0.1.1.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: bashautom
+Version: 0.1.1
+Summary: Persistent bash sessions for Python
+Author-email: Huskago <huskago@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/huskago/bashautom
+Project-URL: Documentation, https://github.com/huskago/bashautom#readme
+Project-URL: Issues, https://github.com/huskago/bashautom/issues
+Project-URL: Changelog, https://github.com/huskago/bashautom/blob/main/CHANGELOG.md
+Keywords: bash,automation,shell,session,subprocess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Shells
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bashautom
+
+Persistent bash sessions for Python.
+
+Unlike `subprocess.run()` which spawns a new process every time, bashautom keeps a `/bin/bash` process alive so state (env vars, cwd, etc.) persists across commands.
+
+```python
+from bashautom import Session
+
+with Session() as s:
+    s.execute("cd /opt/myproject")
+    s.execute("source .env")
+    s.execute("export BUILD_ID=42")
+    result = s.execute("make build")
+```
+
+## Install
+
+```bash
+pip install bashautom
+```
+
+Python 3.10+, Linux/macOS only.
+
+## Usage
+
+```python
+from bashautom import Session
+
+with Session() as s:
+    result = s.execute("echo hello")
+    print(result.stdout)
+    print(result.exit_code)
+    print(result.success)
+```
+
+### Timeouts
+
+Commands can be killed without destroying the session:
+
+```python
+with Session() as s:
+    result = s.execute("sleep 60", timeout=3)
+    print(result.timed_out)
+
+    # session still works
+    s.execute("echo ok")
+```
+
+### Streaming
+
+```python
+from bashautom.session import StreamEvent
+
+def on_output(event: StreamEvent):
+    print(f"[{event.stream}] {event.data.strip()}")
+
+with Session() as s:
+    s.execute("for i in 1 2 3; do echo $i; sleep 0.5; done", stream_callback=on_output)
+```
+
+### Multiple sessions
+
+```python
+from bashautom import SessionManager
+
+with SessionManager() as mgr:
+    build = mgr.create("build", cwd="/opt/project")
+    deploy = mgr.create("deploy", cwd="/opt/infra")
+
+    build.execute("make release")
+    deploy.execute("./deploy.sh")
+```
+
+### Env helpers
+
+```python
+with Session() as s:
+    s.set_env("PROJECT", "bashautom")
+    print(s.get_env("PROJECT"))
+    print(s.get_cwd())
+    print(s.pid)
+    print(s.alive)
+```
+
+## API
+
+### Session
+
+- `execute(command, timeout=None, stream_callback=None)` - run a command, returns `CommandResult`
+- `send_signal(sig=SIGINT)` - send a signal to the running process
+- `get_cwd()` / `get_env(var)` / `set_env(var, value)` - shell state access
+- `close()` - kill the session
+- `pid`, `alive` - process info
+
+### CommandResult
+
+- `command`, `stdout`, `stderr` - what ran and what came back
+- `exit_code`, `success`, `timed_out` - status
+- `duration` - wall time in seconds
+
+### SessionManager
+
+- `create(name, ...)` / `get(name)` / `get_or_create(name, ...)` - session lifecycle
+- `close(name)` / `close_all()` - cleanup
+- `names`, `active` - introspection
+
+## License
+
+MIT

bashautom-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+bashautom/__init__.py,sha256=L8iUrtMHLGU9NhmTR2aFGUyar49JK4-7L5_4q3dmbA8,159
+bashautom/manager.py,sha256=2TbeZmc-Uf2M6egwSv9O4vszn_obxOHdBkMj2EhyxQc,2824
+bashautom/session.py,sha256=Hoaul6PsfKOgzXCtVCCnjHIQUhDWFhz0O1vNKnrleFs,11608
+bashautom-0.1.1.dist-info/licenses/LICENSE,sha256=M8xB87PcLMFT_jFhy8CqkGEX9AF25TNrjktNzr9_izo,1064
+bashautom-0.1.1.dist-info/METADATA,sha256=63TADEOSC3v5ne-jfl_C_HNjgeMY82-pJgdHvUn4Y0k,3173
+bashautom-0.1.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+bashautom-0.1.1.dist-info/top_level.txt,sha256=iie9u75peIF6VFv6xIwA-PTD-2Kev-ZFY3KVN2yMbik,10
+bashautom-0.1.1.dist-info/RECORD,,

bashautom-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bashautom-0.1.1.dist-info/licenses/LICENSE

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

bashautom-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bashautom