bombshell 0.1.0__tar.gz

bombshell-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.python-version

bombshell-0.1.0/LICENSE

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

bombshell-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: bombshell
+Version: 0.1.0
+Summary: A library for easily running shell commands, whether standalone or piped.
+Project-URL: repository, https://github.com/lilellia/bombshell
+Project-URL: Bug Tracker, https://github.com/lilellia/bombshell/issues
+Author-email: Lily Ellington <lilell_@outlook.com>
+License-File: LICENSE
+Keywords: bash,command,command-line,pipe,shell,subprocess,zsh
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# bombshell
+
+A library for easily running subprocesses in Python, whether single or piped.
+
+## Why?
+
+Python's `subprocess` library is capable of running whatever you need it to, but isn't always the most friendly or readable option, even when running a single process:
+
+```py
+res = subprocess.run(("echo", "1"), capture_output=True, text=True)
+print(res.stdout)  # "1\n"
+```
+
+Needing to pass `capture_output=True, text=True` all the time is annoying when those are probably the most common default. Plus, the command has to be passed as a tuple/list, rather than just the arguments themselves.
+
+```py
+res = bombshell.Process("echo", "1").exec()
+print(res.stdout)        # "1\n"
+print(type(res.stdout))  # <class 'str'>
+```
+
+But if you want bytes, then you can have bytes:
+
+```py
+res = bombshell.Process("echo", "1").exec(mode=bytes)
+print(res.stdout)        # b"1\n"
+print(type(res.stdout))  # <class 'bytes'>
+```
+
+`subprocess` is also really picky about the types of arguments you pass in:
+
+```py
+res = subprocess.run(("echo", 1))
+TypeError: "expected str, bytes or os.PathLike object, not int"
+```
+
+Why, though? `bombshell` automatically calls `str()` on every argument passed to it.
+
+```py
+res = bombshell.Process("echo", 1).exec()
+print(res.stdout)     # "1\n"
+print(res.exit_code)  # 0
+```
+
+`subprocess` also makes piping commands way more difficult than it needs to be. What's easy in Bash...
+
+```bash
+res=$(echo "hello\nworld\ngoodbye" | grep "l")
+echo "$res"  # "hello\nworld"
+```
+
+...is way more complicated with `subprocess` since you have to individually manage both sides of the pipe.
+
+```py
+parent = subprocess.Popen(("echo", "hello\nworld\ngoodbye"), stdout=subprocess.PIPE)
+child = subprocess.Popen(("grep", "l"), stdin=parent.stdout, capture_output=True, text=True)
+stdout, _ = child.communicate()
+
+print(stdout)  # "hello\nworld"
+```
+
+There must be a better way.
+
+```py
+res = bombshell.Process("echo", "hello\nworld\ngoodbye").pipe_into("grep", "l")
+print(res.stdout)  # "hello\nworld"
+
+# Process supports .__or__, so we can also do
+p1 = bombshell.Process("echo", "hello\nworld\ngoodbye")
+p2 = bombshell.Process("grep", "l")
+res = (p1 | p2).exec()
+print(res.stdout)  # "hello\nworld"
+```
+
+We can also pass environment variables to individual commands:
+
+```py
+res = subprocess.run(("printenv", "FOO"), capture_output=True, text=True, env={"FOO": "bar"})
+print(res.stdout)  # "bar\n"
+
+
+res = bombshell.Process("printenv", "FOO").with_env(FOO="bar").exec()
+print(res.stdout)  # "bar\n"
+```
+
+`subprocess` also makes it somewhat difficult to chain commands (`command1 && command2`), preferring:
+
+```py
+# only "echo 1" and "echo 2" will successfully run; "echo 3" will not
+procs = [("echo", "1"), ("echo", "2"), ("false",), ("echo", "3")]
+for proc in procs:
+    res = subprocess.run(proc, capture_output=True, text=True)
+    if res.returncode:
+        break
+```
+
+whereas we can do
+
+```py
+res = bombshell.Process("echo", 1).then("echo", 2).then("false").then("echo", "3")
+print(res.command)     # echo 1 && echo 2 && false && echo 3
+print(res.stdout)      # "1\n2\n"
+print(res.exit_code)   # 1
+print(res.exit_codes)  # [0, 0, 1]  <-- indicating that the first two echo commands exited with 0, then false exited with 1
+```
+
+## Installation
+
+`bombshell` is supported on Python 3.10 and newer and can be easily installed with a package manager such as:
+
+```bash
+# using pip
+$ pip install bombshell
+
+# using uv
+$ uv add bombshell
+```
+
+`bombshell` has no other external dependencies (except `typing_extensions`, only on Python 3.10).
+
+## Documentation
+
+### `PipelineError`
+
+An error that is thrown by `CompletedProcess.check()` when the pipeline has errored. It stores the calling process under its `.process` attribute.
+
+```py
+try:
+    bombshell.Process("false").exec().check()
+except bombshell.PipelineError as err:
+    # err.process == bombshell.Process("false").exec()
+    print(err.process.command)     # "false"
+    print(err.process.exit_codes)  # [1]
+```
+
+### `CompletedProcess[S]`
+
+An object that stores the state of a completed process. In particular, its attributes are:
+
+- `args: tuple[tuple[str, ...], ...]`: the arguments that were passed to the process(es) that gave this result
+- `command: str`: a string representation of the command as would be run on the command line
+- `exit_codes: list[int]`: all of the exit codes for the various processes in the pipeline
+- `exit_code: int`: the exit code of the last executed part of the pipeline (and thus the exit code for the entire pipeline)
+- `stdout: str | bytes`: the contents of the stdout pipes, if captured. `.exec(mode=str)` (the default) means that this will be a string; `.exec(mode=bytes)` means this will be a byte string. Note: `(p1 | p2).exec().stdout` will contain only the stdout for `p2`; `p1.then(p2).exec().stdout` will contain both.
+- `stderr: str | bytes`: the contents of the stderr pipes, if captured. `.exec(mode=str)` (the default) means that this will be a string; `.exec(mode=bytes)` means this will be a byte string. This will always include the combination of all stderr pipes, if captured.
+
+```py
+res = (
+    bombshell.Process("echo", 1)
+    .pipe_into("echo", 2)
+    .pipe_into("false")
+    .pipe_into("echo", 3)
+    .exec()
+)
+
+print(res.args)        # (("echo", "1"), ("echo", "2"), ("false",), ("echo", "3"))
+print(res.command)     # "echo 1 | echo 2 | false | echo 3"
+print(res.exit_codes)  # [0, 0, 1, 0]
+print(res.exit_code)   # 0
+print(res.stdout)      # "3\n"
+print(res.stderr)      # ""
+```
+
+This class also defines a `.check` method:
+
+```py
+res = (
+    bombshell.Process("echo", 1)
+    .pipe_into("echo", 2)
+    .pipe_into("false")
+    .pipe_into("echo", 3)
+    .exec()
+)
+
+res.check()             # passes since the final exit code was zero
+res.check(strict=True)  # raises PipelineError since there was a failure along the pipeline
+```
+
+### `Process`
+
+A `Process` object takes a command to run as arguments, along with (optionally) an `env` mapping to use for it. The object defines:
+
+- `exec(self, stdin: S | None = None, *, capture: bool = True, mode: type[S] = str, merge_stderr: bool = False) -> CompletedProcess[S]`: Run the given command. `S` is either `str` or `bytes` (but must match in all cases). `stdin` is a str/bytes value (not a pipe/file) to pass as stdin to this command. `capture=True` (default) means that stdout and stderr will be captured in the resulting CompletedProcess object. `mode` determines whether the output is of type `str` or `bytes`. If `merge_stderr` is True, then stderr is redirected to stdout (meaning that `exec().stdout` will contain both streams and `.stderr` will be empty).
+
+- `__call__(...)`: an alias for `.exec(...)`.
+
+- `with_env(self, **kwargs) -> Self`: return a new Process object with the updated environment variables. Note that this updates the current environment, rather than replacing it.
+
+- `pipe_into(self, *args: Any, env: Mapping[str, str] = None | None) -> Pipeline`: return a new Pipeline object that represents `command1 | command2`. The given `args` can eithe ra series of values to use as a command (such as `Process("echo", 1).pipe_into("echo", 2)`, equivalent to `echo 1 | echo 2`), or it can be a single `Process` object (such as `Process("echo", 1).pipe_into(Process("echo", 2))`.)
+
+- `__or__(self, other: Self) -> Pipeline`: an alias for `.pipe_into`, but requires that the other object is a `Process` object.
+
+- `then(self, *args: Any) -> CommandChain`: return a CommandChain object that represents `command1 && command2`. The given `args` can be either a series of values to use as a command (such as `Process("echo", 1).then("echo", 2)`, equivalent to `echo 1 && echo 2`), or it can be a single Process/Pipeline/CommandChain object (such as `Process("echo", 1).then(Process("echo", 2)).)
+
+### `Pipeline`
+
+A `Pipeline` is an object that represents a piped series of commands. It provides the same methods to provide parity with `Process`, though `Pipeline.pipe_into` and `Pipeline.__or__` both support `Pipeline` as an object.
+
+In practice, it is unlikely that you would create Pipeline objects directly, but rather as `Process(...).pipe_into(...)`.
+
+### `CommandChain`
+
+Like `Pipeline`, this is an object that represents a chained series of commands. It also provides the same methods to provide parity with `Process`.
+
+It is unlikely that you would create CommandChain objects directly, but rather as `Process(...).then(...)`.

bombshell-0.1.0/README.md

@@ -0,0 +1,205 @@
+# bombshell
+
+A library for easily running subprocesses in Python, whether single or piped.
+
+## Why?
+
+Python's `subprocess` library is capable of running whatever you need it to, but isn't always the most friendly or readable option, even when running a single process:
+
+```py
+res = subprocess.run(("echo", "1"), capture_output=True, text=True)
+print(res.stdout)  # "1\n"
+```
+
+Needing to pass `capture_output=True, text=True` all the time is annoying when those are probably the most common default. Plus, the command has to be passed as a tuple/list, rather than just the arguments themselves.
+
+```py
+res = bombshell.Process("echo", "1").exec()
+print(res.stdout)        # "1\n"
+print(type(res.stdout))  # <class 'str'>
+```
+
+But if you want bytes, then you can have bytes:
+
+```py
+res = bombshell.Process("echo", "1").exec(mode=bytes)
+print(res.stdout)        # b"1\n"
+print(type(res.stdout))  # <class 'bytes'>
+```
+
+`subprocess` is also really picky about the types of arguments you pass in:
+
+```py
+res = subprocess.run(("echo", 1))
+TypeError: "expected str, bytes or os.PathLike object, not int"
+```
+
+Why, though? `bombshell` automatically calls `str()` on every argument passed to it.
+
+```py
+res = bombshell.Process("echo", 1).exec()
+print(res.stdout)     # "1\n"
+print(res.exit_code)  # 0
+```
+
+`subprocess` also makes piping commands way more difficult than it needs to be. What's easy in Bash...
+
+```bash
+res=$(echo "hello\nworld\ngoodbye" | grep "l")
+echo "$res"  # "hello\nworld"
+```
+
+...is way more complicated with `subprocess` since you have to individually manage both sides of the pipe.
+
+```py
+parent = subprocess.Popen(("echo", "hello\nworld\ngoodbye"), stdout=subprocess.PIPE)
+child = subprocess.Popen(("grep", "l"), stdin=parent.stdout, capture_output=True, text=True)
+stdout, _ = child.communicate()
+
+print(stdout)  # "hello\nworld"
+```
+
+There must be a better way.
+
+```py
+res = bombshell.Process("echo", "hello\nworld\ngoodbye").pipe_into("grep", "l")
+print(res.stdout)  # "hello\nworld"
+
+# Process supports .__or__, so we can also do
+p1 = bombshell.Process("echo", "hello\nworld\ngoodbye")
+p2 = bombshell.Process("grep", "l")
+res = (p1 | p2).exec()
+print(res.stdout)  # "hello\nworld"
+```
+
+We can also pass environment variables to individual commands:
+
+```py
+res = subprocess.run(("printenv", "FOO"), capture_output=True, text=True, env={"FOO": "bar"})
+print(res.stdout)  # "bar\n"
+
+
+res = bombshell.Process("printenv", "FOO").with_env(FOO="bar").exec()
+print(res.stdout)  # "bar\n"
+```
+
+`subprocess` also makes it somewhat difficult to chain commands (`command1 && command2`), preferring:
+
+```py
+# only "echo 1" and "echo 2" will successfully run; "echo 3" will not
+procs = [("echo", "1"), ("echo", "2"), ("false",), ("echo", "3")]
+for proc in procs:
+    res = subprocess.run(proc, capture_output=True, text=True)
+    if res.returncode:
+        break
+```
+
+whereas we can do
+
+```py
+res = bombshell.Process("echo", 1).then("echo", 2).then("false").then("echo", "3")
+print(res.command)     # echo 1 && echo 2 && false && echo 3
+print(res.stdout)      # "1\n2\n"
+print(res.exit_code)   # 1
+print(res.exit_codes)  # [0, 0, 1]  <-- indicating that the first two echo commands exited with 0, then false exited with 1
+```
+
+## Installation
+
+`bombshell` is supported on Python 3.10 and newer and can be easily installed with a package manager such as:
+
+```bash
+# using pip
+$ pip install bombshell
+
+# using uv
+$ uv add bombshell
+```
+
+`bombshell` has no other external dependencies (except `typing_extensions`, only on Python 3.10).
+
+## Documentation
+
+### `PipelineError`
+
+An error that is thrown by `CompletedProcess.check()` when the pipeline has errored. It stores the calling process under its `.process` attribute.
+
+```py
+try:
+    bombshell.Process("false").exec().check()
+except bombshell.PipelineError as err:
+    # err.process == bombshell.Process("false").exec()
+    print(err.process.command)     # "false"
+    print(err.process.exit_codes)  # [1]
+```
+
+### `CompletedProcess[S]`
+
+An object that stores the state of a completed process. In particular, its attributes are:
+
+- `args: tuple[tuple[str, ...], ...]`: the arguments that were passed to the process(es) that gave this result
+- `command: str`: a string representation of the command as would be run on the command line
+- `exit_codes: list[int]`: all of the exit codes for the various processes in the pipeline
+- `exit_code: int`: the exit code of the last executed part of the pipeline (and thus the exit code for the entire pipeline)
+- `stdout: str | bytes`: the contents of the stdout pipes, if captured. `.exec(mode=str)` (the default) means that this will be a string; `.exec(mode=bytes)` means this will be a byte string. Note: `(p1 | p2).exec().stdout` will contain only the stdout for `p2`; `p1.then(p2).exec().stdout` will contain both.
+- `stderr: str | bytes`: the contents of the stderr pipes, if captured. `.exec(mode=str)` (the default) means that this will be a string; `.exec(mode=bytes)` means this will be a byte string. This will always include the combination of all stderr pipes, if captured.
+
+```py
+res = (
+    bombshell.Process("echo", 1)
+    .pipe_into("echo", 2)
+    .pipe_into("false")
+    .pipe_into("echo", 3)
+    .exec()
+)
+
+print(res.args)        # (("echo", "1"), ("echo", "2"), ("false",), ("echo", "3"))
+print(res.command)     # "echo 1 | echo 2 | false | echo 3"
+print(res.exit_codes)  # [0, 0, 1, 0]
+print(res.exit_code)   # 0
+print(res.stdout)      # "3\n"
+print(res.stderr)      # ""
+```
+
+This class also defines a `.check` method:
+
+```py
+res = (
+    bombshell.Process("echo", 1)
+    .pipe_into("echo", 2)
+    .pipe_into("false")
+    .pipe_into("echo", 3)
+    .exec()
+)
+
+res.check()             # passes since the final exit code was zero
+res.check(strict=True)  # raises PipelineError since there was a failure along the pipeline
+```
+
+### `Process`
+
+A `Process` object takes a command to run as arguments, along with (optionally) an `env` mapping to use for it. The object defines:
+
+- `exec(self, stdin: S | None = None, *, capture: bool = True, mode: type[S] = str, merge_stderr: bool = False) -> CompletedProcess[S]`: Run the given command. `S` is either `str` or `bytes` (but must match in all cases). `stdin` is a str/bytes value (not a pipe/file) to pass as stdin to this command. `capture=True` (default) means that stdout and stderr will be captured in the resulting CompletedProcess object. `mode` determines whether the output is of type `str` or `bytes`. If `merge_stderr` is True, then stderr is redirected to stdout (meaning that `exec().stdout` will contain both streams and `.stderr` will be empty).
+
+- `__call__(...)`: an alias for `.exec(...)`.
+
+- `with_env(self, **kwargs) -> Self`: return a new Process object with the updated environment variables. Note that this updates the current environment, rather than replacing it.
+
+- `pipe_into(self, *args: Any, env: Mapping[str, str] = None | None) -> Pipeline`: return a new Pipeline object that represents `command1 | command2`. The given `args` can eithe ra series of values to use as a command (such as `Process("echo", 1).pipe_into("echo", 2)`, equivalent to `echo 1 | echo 2`), or it can be a single `Process` object (such as `Process("echo", 1).pipe_into(Process("echo", 2))`.)
+
+- `__or__(self, other: Self) -> Pipeline`: an alias for `.pipe_into`, but requires that the other object is a `Process` object.
+
+- `then(self, *args: Any) -> CommandChain`: return a CommandChain object that represents `command1 && command2`. The given `args` can be either a series of values to use as a command (such as `Process("echo", 1).then("echo", 2)`, equivalent to `echo 1 && echo 2`), or it can be a single Process/Pipeline/CommandChain object (such as `Process("echo", 1).then(Process("echo", 2)).)
+
+### `Pipeline`
+
+A `Pipeline` is an object that represents a piped series of commands. It provides the same methods to provide parity with `Process`, though `Pipeline.pipe_into` and `Pipeline.__or__` both support `Pipeline` as an object.
+
+In practice, it is unlikely that you would create Pipeline objects directly, but rather as `Process(...).pipe_into(...)`.
+
+### `CommandChain`
+
+Like `Pipeline`, this is an object that represents a chained series of commands. It also provides the same methods to provide parity with `Process`.
+
+It is unlikely that you would create CommandChain objects directly, but rather as `Process(...).then(...)`.

bombshell-0.1.0/bombshell/__init__.py

@@ -0,0 +1,3 @@
+from .core import CommandChain, CompletedProcess, Pipeline, PipelineError, Process
+
+__all__ = ["Process", "Pipeline", "CompletedProcess", "PipelineError", "CommandChain"]

bombshell-0.1.0/bombshell/core.py

@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+import itertools
+import os
+import shlex
+import subprocess
+import sys
+from threading import Thread
+from typing import Any, cast, Generic, IO, overload, TypeVar
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from .stream import consume_stream, feed_stream
+
+S = TypeVar("S", str, bytes)
+
+
+class PipelineError(Exception, Generic[S]):
+    def __init__(self, process: CompletedProcess[S]) -> None:
+        msg = f"Pipeline exited with non-zero exit code(s): {process.exit_codes}"
+        super().__init__(msg)
+        self.process: CompletedProcess[S] = process
+
+
+@dataclass(frozen=True, slots=True)
+class CompletedProcess(Generic[S]):
+    args: tuple[tuple[str, ...], ...]
+    command: str
+    exit_codes: list[int]
+    stdout: S
+    stderr: S
+
+    @property
+    def exit_code(self) -> int:
+        return self.exit_codes[-1]
+
+    def check(self, *, strict: bool = False) -> None:
+        """Raise a PipelineError if the pipeline exited with a non-zero exit code.
+
+        :arg strict:
+            If True, raise PipelineError if any process exited with a non-zero exit code.
+            If False, raise PipelineError if the last process exited with a non-zero exit code.
+
+        :return: None
+        :raise PipelineError: If any (strict=True) or the last (strict=False) process exited with a non-zero exit code.
+        """
+        if strict and any(ec != 0 for ec in self.exit_codes):
+            raise PipelineError(self)
+
+        if not strict and self.exit_code != 0:
+            raise PipelineError(self)
+
+
+class Process:
+    def __init__(self, *args: Any, env: Mapping[str, str] | None = None):
+        self.args = tuple(str(arg) for arg in args)
+        self.env = {**os.environ, **(env or {})}
+
+    def with_env(self, **kwargs: str) -> Self:
+        return type(self)(*self.args, env={**self.env, **kwargs})
+
+    def then(self, *args: Any) -> CommandChain:
+        match args:
+            case ():
+                raise ValueError(".then requires at least one argument")
+            case [obj] if isinstance(obj, (type(self), Pipeline, CommandChain)):
+                # Process("echo", 1).then(Process("echo", 2))
+                return CommandChain(self, obj)
+            case _:
+                # Process("echo", 1).then("echo", 2)
+                return CommandChain(self, Process(*args))
+
+    @overload
+    def exec(
+        self,
+        stdin: str | None = None,
+        *,
+        capture: bool = True,
+        mode: type[str] = str,
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def exec(
+        self,
+        stdin: bytes | None = None,
+        *,
+        capture: bool = True,
+        mode: type[bytes],
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[bytes]: ...
+
+    def exec(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        return Pipeline(self)(stdin=stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+    @overload
+    def __call__(
+        self,
+        stdin: str | None = None,
+        *,
+        capture: bool = True,
+        mode: type[str] = str,
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def __call__(
+        self,
+        stdin: bytes | None = None,
+        *,
+        capture: bool = True,
+        mode: type[bytes],
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[bytes]: ...
+
+    def __call__(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        return self.exec(stdin=stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+    def __or__(self, other: Self) -> Pipeline:
+        """Create a pipeline between this process and other. Example: Process("ls", "-1") | Process("tail", 5)"""
+        if isinstance(other, type(self)):
+            return Pipeline(self, other)
+
+        return NotImplemented
+
+    def pipe_into(self, *args: str, env: Mapping[str, str] | None = None) -> Pipeline:
+        """Create a pipeline between this process and a command. Example: Process("ls", "-1").pipe_into("tail", 5)"""
+        match args:
+            case ():
+                raise ValueError(".pipe_into requires at least one argument")
+            case [obj] if isinstance(obj, type(self)):
+                # Process("echo", 1).pipe_into(Process("echo", 2))
+                return Pipeline(self, obj)
+            case _:
+                # Process("echo", 1).pipe_into("echo", 2)
+                return Pipeline(self, Process(*args))
+
+        if args:
+            return Pipeline(self, Process(*args, env=env))
+
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return shlex.join(self.args)
+
+    def __repr__(self) -> str:
+        args = ", ".join(repr(arg) for arg in self.args)
+        return f"{self.__class__.__name__}({args})"
+
+
+class Pipeline:
+    def __init__(self, *processes: Process) -> None:
+        self.processes = processes
+
+    def pipe_into(self, *args: Any, env: Mapping[str, str] | None = None) -> Self:
+        match args:
+            case ():
+                raise ValueError(".pipe_into requires at least one argument")
+            case [obj] if isinstance(obj, Process):
+                return type(self)(*self.processes, obj)
+            case [obj] if isinstance(obj, type(self)):
+                return type(self)(*self.processes, *obj.processes)
+            case _:
+                # Process("echo", 1).pipe_into("echo", 2)
+                return type(self)(*self.processes, Process(*args))
+
+    def __or__(self, other: Process) -> Self:
+        return self.pipe_into(other)
+
+    def then(self, *args: Any) -> CommandChain:
+        match args:
+            case ():
+                raise ValueError(".then requires at least one argument")
+            case [obj] if isinstance(obj, (Process, type(self), CommandChain)):
+                # Process("echo", 1).then(Process("echo", 2))
+                return CommandChain(self, obj)
+            case _:
+                # Process("echo", 1).then("echo", 2)
+                return CommandChain(self, Process(*args))
+
+    @overload
+    def _setup_chain(
+        self, stdin: str | None, capture: bool, mode: type[str], merge_stderr: bool
+    ) -> list[subprocess.Popen[str]]: ...
+
+    @overload
+    def _setup_chain(
+        self, stdin: bytes | None, capture: bool, mode: type[bytes], merge_stderr: bool
+    ) -> list[subprocess.Popen[bytes]]: ...
+
+    def _setup_chain(
+        self, stdin: S | None, capture: bool, mode: type[S], merge_stderr: bool
+    ) -> list[subprocess.Popen[S]]:
+        procs: list[subprocess.Popen[S]] = []
+        is_text = mode is str
+
+        for i, proc in enumerate(self.processes):
+            # determine where to get input
+            proc_stdin: int | IO[Any] | None
+            if i == 0 and stdin is not None:
+                proc_stdin = subprocess.PIPE
+            elif i > 0:
+                proc_stdin = procs[i - 1].stdout
+            else:
+                proc_stdin = None
+
+            # determine where to send output
+            if capture or i < len(self.processes) - 1:
+                proc_stdout = subprocess.PIPE
+            else:
+                proc_stdout = None
+
+            # determine where to send stderr
+            if i < len(self.processes) - 1:
+                # intermediate process
+                proc_stderr = subprocess.PIPE if capture else None
+            elif capture:
+                # final process
+                proc_stderr = subprocess.STDOUT if merge_stderr else subprocess.PIPE
+            else:
+                proc_stderr = None
+
+            p = subprocess.Popen(
+                proc.args, stdin=proc_stdin, stdout=proc_stdout, stderr=proc_stderr, text=is_text, env=proc.env
+            )
+            procs.append(p)
+
+            # close the stdout of the previous process in order to allow it to receive SIGPIPE
+            if i > 0 and (prev_stdout := procs[i - 1].stdout):
+                prev_stdout.close()
+
+        return procs
+
+    @overload
+    def exec(
+        self,
+        stdin: str | None = None,
+        *,
+        capture: bool = True,
+        mode: type[str] = str,
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def exec(
+        self,
+        stdin: bytes | None = None,
+        *,
+        capture: bool = True,
+        mode: type[bytes],
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[bytes]: ...
+
+    def exec(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        procs = self._setup_chain(stdin=stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+        # --- set up stdout/stderr handlers --- #
+        stdout_block: list[S] = []
+        stderr_blocks: list[list[S]] = [[] for _ in procs]
+        threads: list[Thread] = []
+
+        for idx, proc in enumerate(procs):
+            if proc.stderr:
+                t = Thread(target=consume_stream, args=(proc.stderr, stderr_blocks[idx]))
+                t.start()
+                threads.append(t)
+
+        if procs[-1].stdout:
+            t = Thread(target=consume_stream, args=(procs[-1].stdout, stdout_block))
+            t.start()
+            threads.append(t)
+
+        # --- handle stdin to first process --- #
+        if stdin is not None:
+            assert procs[0].stdin is not None
+            t = Thread(target=feed_stream, args=(procs[0].stdin, stdin))
+            t.start()
+            threads.append(t)
+
+        # --- wait for all processes to finish --- #
+        for t in threads:
+            t.join()
+
+        exit_codes: list[int] = []
+        for p in procs:
+            p.wait()
+            exit_codes.append(p.returncode)
+
+        # --- build completed process object --- #
+        stdout = mode().join(stdout_block) if capture else mode()
+        stderr = mode().join(mode().join(block) for block in stderr_blocks) if capture and not merge_stderr else mode()
+        args = tuple(proc.args for proc in self.processes)
+
+        return CompletedProcess(args=args, command=str(self), exit_codes=exit_codes, stdout=stdout, stderr=stderr)
+
+    @overload
+    def __call__(
+        self,
+        stdin: str | None = None,
+        *,
+        capture: bool = True,
+        mode: type[str] = str,
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def __call__(
+        self,
+        stdin: bytes | None = None,
+        *,
+        capture: bool = True,
+        mode: type[bytes],
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[bytes]: ...
+
+    def __call__(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        return self.exec(stdin=stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+    def __str__(self) -> str:
+        return " | ".join(str(process) for process in self.processes)
+
+    def __repr__(self) -> str:
+        args = ", ".join(repr(process) for process in self.processes)
+        return f"{self.__class__.__name__}({args})"
+
+
+class CommandChain:
+    def __init__(self, *items: Process | Pipeline | Self) -> None:
+        self.items: list[Process | Pipeline] = []
+
+        for item in items:
+            if isinstance(item, type(self)):
+                self.items.extend(item.items)
+            else:
+                item = cast(Process | Pipeline, item)
+                self.items.append(item)
+
+    def then(self, *args: Any) -> Self:
+        match args:
+            case ():
+                raise ValueError(".then requires at least one argument")
+            case [obj] if isinstance(obj, (Process, Pipeline, type(self))):
+                # Process("echo", 1).then(Process("echo", 2))
+                return type(self)(self, obj)
+            case _:
+                # Process("echo", 1).then("echo", 2)
+                return type(self)(self, Process(*args))
+
+    @overload
+    def exec(
+        self, stdin: str | None = None, *, capture: bool = True, mode: type[str] = str, merge_stderr: bool = False
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def exec(
+        self, stdin: bytes | None = None, *, capture: bool = True, mode: type[bytes], merge_stderr: bool = False
+    ) -> CompletedProcess[bytes]: ...
+
+    def exec(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        all_args: list[tuple[tuple[str, ...], ...]] = []
+        all_exit_codes: list[int] = []
+
+        stdout_parts: list[S] = []
+        stderr_parts: list[S] = []
+
+        for idx, item in enumerate(self.items):
+            proc_stdin = stdin if idx == 0 else None
+            res = item.exec(stdin=proc_stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+            all_args.append(res.args)
+            all_exit_codes.extend(res.exit_codes)
+            stdout_parts.append(res.stdout)
+            stderr_parts.append(res.stderr)
+
+            if res.exit_code != 0:
+                break
+
+        return CompletedProcess(
+            args=tuple(itertools.chain.from_iterable(all_args)),
+            command=str(self),
+            exit_codes=all_exit_codes,
+            stdout=mode().join(stdout_parts),
+            stderr=mode().join(stderr_parts),
+        )
+
+    @overload
+    def __call__(
+        self, stdin: str | None = None, *, capture: bool = True, mode: type[str] = str, merge_stderr: bool = False
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    def __call__(
+        self, stdin: bytes | None = None, *, capture: bool = True, mode: type[bytes], merge_stderr: bool = False
+    ) -> CompletedProcess[bytes]: ...
+
+    def __call__(
+        self,
+        stdin: S | None = None,
+        *,
+        capture: bool = True,
+        mode: type[S] = str,  # type: ignore
+        merge_stderr: bool = False,
+    ) -> CompletedProcess[S]:
+        return self.exec(stdin=stdin, capture=capture, mode=mode, merge_stderr=merge_stderr)
+
+    def __str__(self) -> str:
+        return " && ".join(str(item) for item in self.items)
+
+    def __repr__(self) -> str:
+        args = ", ".join(repr(item) for item in self.items)
+        return f"{self.__class__.__name__}({args})"

bombshell-0.1.0/bombshell/stream.py

@@ -0,0 +1,18 @@
+from typing import IO, TypeVar
+
+S = TypeVar("S", str, bytes)
+
+
+def consume_stream(stream: IO[S], buffer: list[S]) -> None:
+    try:
+        while block := stream.read():
+            buffer.append(block)
+    finally:
+        stream.close()
+
+
+def feed_stream(stream: IO[S], content: S) -> None:
+    try:
+        stream.write(content)
+    finally:
+        stream.close()

bombshell-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bombshell"
+version = "0.1.0"
+description = "A library for easily running shell commands, whether standalone or piped."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "typing-extensions>=4.0; python_version < '3.11'"
+]
+authors = [
+    { name = "Lily Ellington", email = "lilell_@outlook.com" }
+]
+keywords = [
+    "shell",
+    "command",
+    "command-line",
+    "bash",
+    "zsh",
+    "subprocess",
+    "pipe"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities"
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F"]
+ignore = ["I001"]
+
+[tool.ruff.isort]
+known-local-folder = ["bombshell"]
+force-single-line = false
+lines-after-imports = 1
+force-sort-within-sections = true
+order-by-type = false
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+]
+
+[project.urls]
+repository = "https://github.com/lilellia/bombshell"
+"Bug Tracker" = "https://github.com/lilellia/bombshell/issues"
+
+[tool.hatch.build]
+include = [
+    "bombshell"
+]