shtoobz

Talk to a child process or a TCP socket through the same Python API. A shtoob handles bytes, buffering, prompts, and timeouts so your client code can stay the same when you switch transports.

Python 3.11+ · Windows and Linux · No runtime dependencies

Install

In an existing uv project:

uv add shtoobz

Or install into your Python environment with python -m pip install shtoobz. This is a Python library; there is no shtoobz command to launch.

Try a process

Save this as hello.py. It launches a Python child, sends a line, and reads the child's response. It runs on both Windows and Linux without an external server.

import sys
from shtoobz import ProcessShtoob

with ProcessShtoob(
    [
        sys.executable, "-u", "-c",
        "print(input().upper(), flush=True)",
    ],
    timeout=5,
) as shtoob:
    shtoob.sendline(b"hello")
    reply = shtoob.recvline()
    print(reply.decode().rstrip("\r\n"))

Run uv run python hello.py from your project, or python hello.py if you used pip. You should see:

HELLO

The with block closes the shtoob and cleans up the child. Python's -u option keeps the child's output unbuffered so responses arrive promptly.

Switch transports

For an application that exposes the same byte protocol over stdin/stdout and TCP, switch the connection by changing LOCAL. The example below expects your application to print Name: , accept a name, and reply with a newline-terminated message. Replace the executable path or host and port with your own target.

from shtoobz import ProcessShtoob, SocketShtoob

LOCAL = True

shtoob = (
    ProcessShtoob(
        ["./example", "--stdio"], timeout=5,
    )
    if LOCAL
    else SocketShtoob("127.0.0.1", 9000, timeout=5)
)

with shtoob:
    shtoob.sendlineafter(
        b"Name: ", b"Alice", max_bytes=4096,
    )
    print(shtoob.recvline(max_bytes=4096))

On Windows, use your executable's path, for example r".\example.exe". Both endpoints must speak the same protocol; shtoobz does not translate between a CLI menu and a different network protocol.

To keep connection setup out of your client, accept the shared Shtoob type:

from shtoobz import Shtoob

class Client:
    def __init__(self, shtoob: Shtoob):
        self.shtoob = shtoob

    def request(self, payload: bytes) -> bytes:
        self.shtoob.sendline(payload)
        return self.shtoob.recvline(max_bytes=4096)

Choose a read

Payloads and delimiters are bytes. Encode text before sending and decode it after reading. Reads retain bytes beyond a delimiter for the next call.

Set a finite timeout when you want a stalled read to fail. The default waits indefinitely. A timeout preserves partial input so you can continue the same read. Writes are blocking and have no timeout.

recv(n) may return fewer than n bytes; recvn(n) waits for the exact count. recvline() raises ShtoobEOF if the peer closes before a newline arrives. Use iterlines() when an unterminated final line should be returned.

The API reference covers errors and recovery, response limits, prompt helpers, buffering, streaming, traffic logging, and transport options.

Supported use

shtoobz supports redirected process pipes and IPv4/IPv6 TCP connections. Use it for programs that accept bytes on stdin and write responses to stdout, or expose the same protocol through a socket. A child must flush its output promptly.

PTY/ConPTY terminal emulation, interactive terminal forwarding, async APIs, TLS, server listeners, and process-tree management are outside the current scope. Closing a process shtoob terminates and reaps its direct child, not descendants.

More documentation

• API reference: method behavior, timeout and EOF rules, examples, and lifecycle.
• Development and releases: work on the package, run checks, and publish with GitLab.
• Issues: report a problem or request a feature.

Licensed under the MIT License. Copyright 2026 Jeremy Dunn.