Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Swarmauri Logo

PyPI - Downloads Hits PyPI - Python Version PyPI - License PyPI - swarmauri_tool_subprocess Discord

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.tools entry 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.dev3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for swarmauri_tool_subprocess 0.11.0.dev3
File Size Uploaded Provenance Actions
swarmauri_tool_subprocess-0.11.0.dev3.tar.gz 9.1 kB Without provenance Details for swarmauri_tool_subprocess-0.11.0.dev3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for swarmauri_tool_subprocess 0.11.0.dev3
File Interpreter ABI Platform Actions
swarmauri_tool_subprocess-0.11.0.dev3-py3-none-any.whl Python 3 none any Details for swarmauri_tool_subprocess-0.11.0.dev3-py3-none-any.whl

Total release size: 19.7 kB

Release files / swarmauri_tool_subprocess-0.11.0.dev3.tar.gz

Download URL swarmauri_tool_subprocess-0.11.0.dev3.tar.gz
Size 9.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5ac34450ffc002017dccca6dad48f2fc4f306516d36d2e4fb5ae337c76bb71d7
BLAKE2b-256 checksum
How to use checksums
1ff255d712d1c769d74635f1328cbbb0b38db57b37e76aac4c7b65ae9f4bf5d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.dev3-py3-none-any.whl

Download URL swarmauri_tool_subprocess-0.11.0.dev3-py3-none-any.whl
Size 10.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8cff30b1acde27c40ab6e3a2318cd4368bed4c54e36a794c1c498e5828da91a
BLAKE2b-256 checksum
How to use checksums
c80390be7c7206c6c2b6d5be0051cf65eec79efd98a5061290715ae070e98b64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.dev3

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page