This release is a pre-release and may not be stable for production use.
Swarmauri Tool Subprocess
Execute subprocess commands and capture output, timeouts, and exit codes.
Features
- Execute argument vectors without shell expansion by default.
- Capture stdout, stderr, and integer exit codes, including nonzero codes.
- Distinguish completed commands, missing executables, timeouts, and errors.
- Select a child working directory and an explicit replacement environment.
- Discover the component through the
swarmauri.toolsentry point and facade. - Preserve the original standard import through a lazy compatibility adapter.
- Share execution with the standard kernel, which can run the legacy tool by itself.
Installation
uv add swarmauri_tool_subprocess
pip install swarmauri_tool_subprocess
Usage
import sys
from swarmauri_tool_subprocess import SubprocessTool
tool = SubprocessTool()
result = tool([sys.executable, "-c", "print('hello')"], timeout=5)
assert result["stdout"].strip() == "hello"
assert result["exit_code"] == 0
Use argument vectors for commands containing paths or arguments with spaces,
particularly on Windows. With shell=False, string commands use POSIX
shlex.split quoting; they are not parsed by the Windows command processor.
Shell mode accepts strings only and executes arbitrary syntax through the
platform shell (/bin/sh on POSIX or the configured Windows command processor):
result = tool("echo first && echo second", shell=True, timeout=5)
Only trusted callers should choose shell commands, executables, working
directories, and environment values. Windows native mode (shell=False)
resolves the executable from the parent search environment and requires a
native .exe or .com. Use a trusted absolute executable path for deterministic
selection. To invoke trusted batch syntax, use explicit shell mode. Windows
may otherwise parse batch arguments through its command interpreter.
cwd=None inherits the parent's working directory. env=None deliberately
inherits the parent's environment for compatibility. Pass env={...} to supply
the complete child environment; it is not merged with the parent. Include any
platform-required variables (such as SystemRoot on Windows) and an appropriate
PATH when needed, or use an absolute executable path. Avoid forwarding secrets
the child does not need.
timeout=None imposes no timeout. A supplied timeout applies to the direct
child after process creation. Timed Windows calls capture output in temporary
files, so inherited output handles cannot make the timeout wait for pipe EOF.
On success, capture is a snapshot taken after the direct child exits.
Descendants can continue running and retain inherited temporary handles until
they exit. Keep subprocess execution under the service's trust policy.
Results and migration
The standalone API returns status, stdout, stderr, and exit_code:
| Status | Meaning | Exit code |
|---|---|---|
success |
Process completed, including nonzero exit codes | Integer |
timeout |
Process exceeded the timeout | None |
not_found |
Executable or requested working directory was not found | 127 |
runtime_error |
Invalid arguments or another execution failure | None |
success describes process completion, not application success; check
exit_code == 0 before treating a command as successful. Passing an argument
list with shell=True, an empty command, or malformed quoting returns
runtime_error without starting a child.
Existing code can continue to use the original case-sensitive import:
from swarmauri_standard.tools.SubprocessTool import SubprocessTool
result = SubprocessTool()("echo hello", shell=True)
assert result["exit_code"] == "0"
The compatibility adapter emits a DeprecationWarning and retains the original
three-key result and string exit codes: numeric strings for completed commands,
"timeout" for timeouts, and "error" for execution failures. Import from the
standalone package when adopting the richer typed results and cwd/env
options. Importing the compatibility module alone does not load the standalone
package.
The lowercase module spelling introduced in the PR is also accepted as an
import alias. Both spellings share the same module and legacy result contract.
Metadata
Release files for swarmauri_tool_subprocess 0.11.0.dev4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swarmauri_tool_subprocess-0.11.0.dev4.tar.gz | 9.1 kB | Without provenance | Details for swarmauri_tool_subprocess-0.11.0.dev4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_subprocess-0.11.0.dev4-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_subprocess-0.11.0.dev4-py3-none-any.whl |
Total release size: 19.7 kB
Release files / swarmauri_tool_subprocess-0.11.0.dev4.tar.gz
| Download URL | swarmauri_tool_subprocess-0.11.0.dev4.tar.gz |
|---|---|
| Size | 9.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0620aee77614ab8a3cc08d33c9139ded9232442b099de1e2b51dd220a12536a
|
|
BLAKE2b-256 checksum How to use checksums |
a5051aeb42f0cbe1898bfeac47e5f7e333cd24a585126da871825a4ea5520c95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_tool_subprocess-0.11.0.dev4-py3-none-any.whl
| Download URL | swarmauri_tool_subprocess-0.11.0.dev4-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54590ac1bce59c718139a800b228a2a1e2e8a5d5ecbaee3cdb329e1b79356e80
|
|
BLAKE2b-256 checksum How to use checksums |
7f23536e0ba88a32b0c95c6cace9deb0ff676e188b9d514941e653fe22bf2450
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for swarmauri_tool_subprocess 0.11.0.dev4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.