funshell

A lightweight Python utility for executing shell commands, supporting real-time output streaming and captured output.

Installation

pip install funshell

Quick Start

from run import run_shell, run_shell_list

# Real-time output to terminal, returns exit code
exit_code = run_shell("echo hello world")
# hello world
# exit_code == "0"

# Capture output as string
output = run_shell("echo hello world", printf=False)
# output == "hello world"

API

`run_shell(command, printf=True, *, cwd=None, timeout=None, encoding="utf-8")`

Execute a shell command.

Parameter	Type	Default	Description
`command`	`str`	required	Shell command to execute
`printf`	`bool`	`True`	`True`: stream to terminal; `False`: capture output
`cwd`	`str \| None`	`None`	Working directory for the command
`timeout`	`float \| None`	`None`	Timeout in seconds
`encoding`	`str`	`"utf-8"`	Output encoding when capturing

Returns: Exit code as string when printf=True, stdout content when printf=False.

`run_shell_list(command_list, printf=True, *, cwd=None, timeout=None, encoding="utf-8")`

Execute multiple commands sequentially (joined with &&, stops on first failure).

Parameter	Type	Default	Description
`command_list`	`list[str]`	required	List of shell commands
`printf`	`bool`	`True`	`True`: stream; `False`: capture
`cwd`	`str \| None`	`None`	Working directory
`timeout`	`float \| None`	`None`	Timeout for the entire command chain
`encoding`	`str`	`"utf-8"`	Output encoding

Examples

from run import run_shell, run_shell_list

# Capture command output
result = run_shell("ls -la", printf=False)
print(result)

# Run in a specific directory
run_shell("git status", cwd="/path/to/repo")

# Set a timeout (seconds)
run_shell("sleep 100", timeout=5)
# Returns: "run shell error: command timed out"

# Execute a sequence of commands
run_shell_list(["mkdir -p build", "cd build", "cmake .."])

# Capture output of chained commands
output = run_shell_list(["echo hello", "echo world"], printf=False)
# output == "hello\nworld"

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

funshell-1.0.22-py3-none-any.whl (6.5 kB view details)

Uploaded Aug 31, 2026 Python 3

File details

Details for the file funshell-1.0.22-py3-none-any.whl.

File metadata

Download URL: funshell-1.0.22-py3-none-any.whl
Upload date: Aug 31, 2026
Size: 6.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","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":null}

File hashes

Hashes for funshell-1.0.22-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f8500fe53b0e522edf7d3ddea6a029a526afea36f2729d2f01cf38aaf513a901`
MD5	`6f22cf225aedcfd273c7bcf1049109f9`
BLAKE2b-256	`2e87a14790af12f2c6ae5ec197005735845dd3f46a5663b0dea8dbf01f9be553`