API Reference

Functions

`shell_exec()`

Execute a shell command and return its output.

def shell_exec(
    cmd: str,
    *,
    env: Any = None,
    cwd: str | bytes | os.PathLike | None = None,
    stdin: int | None = None,
    stdout: int = PIPE,
    stderr: int = PIPE,
    yes: bool = False,
    is_sudo: bool = False,
    prompt_input: str | list[str] | None = None,
) -> str | None:

Parameters:

Parameter	Type	Default	Description
`cmd`	`str`	required	Shell command to execute
`env`	`Any`	`None`	Environment variables dict
`cwd`	`str \\| bytes \\| os.PathLike \\| None`	`None`	Working directory
`stdin`	`int \\| None`	`None`	stdin file descriptor
`stdout`	`int`	`PIPE`	stdout file descriptor
`stderr`	`int`	`PIPE`	stderr file descriptor
`yes`	`bool`	`False`	Pipe `yes` to command input
`is_sudo`	`bool`	`False`	Prefix command with `sudo`
`prompt_input`	`str \\| list[str] \\| None`	`None`	Input to send to stdin

Returns: str | None — Command stdout, or None if empty.

Raises: ShellExecError — If command exits with non-zero code.

Example:

from shelluha import shell

output = shell.shell_exec("ls -la", cwd="/tmp")

`cd()`

Context manager for temporary directory changes.

@contextmanager
def cd(path: str) -> Generator:

Parameters:

Parameter	Type	Description
`path`	`str`	Directory path to change to

Example:

from shelluha import shell

with shell.cd("/tmp"):
    # Working directory is /tmp
    pass
# Working directory restored

Classes

`ShellCommand`

Wrapper class for shell commands.

class ShellCommand:
    def __init__(self, bin_file: str) -> None: ...
    def __call__(self, *options: str, **kwargs: Any) -> str | None: ...
    @property
    def bin(self) -> str: ...

Parameters:

Parameter	Type	Description
`bin_file`	`str`	Binary name or path

Methods:

Method	Returns	Description
`__call__(options, *kwargs)`	`str \\| None`	Execute command with options
`bin`	`str`	Get the binary name

Example:

from shelluha import ShellCommand

git = ShellCommand("git")
git("status")
print(git.bin)  # "git"

Exceptions

`ShellExecError`

Raised when a shell command exits with a non-zero code.

class ShellExecError(Exception):
    pass

Message format: <command>\n<stderr> (stderr included if available)

Example:

from shelluha import shell

try:
    shell.shell_exec("false")
except shell.ShellExecError as e:
    print(e)  # "false\n" or "false" if no stderr

Pre-initialized Commands

The module provides pre-initialized ShellCommand instances accessible via the shell module:

from shelluha import shell

shell.ps("-aux")
shell.df("-h")
shell.du("-sh /home")
shell.cat("file.txt")
shell.tar("-czf archive.tar.gz .")
shell.tail("-f logfile")
shell.head("-n 10 file.txt")
shell.touch("newfile.txt")
shell.chown("user:group file")
shell.chmod("755 script.sh")
shell.chgrp("group file")
shell.which("python")