Runez Library

5.7.1 · active · verified Wed Apr 15

Runez is a friendly, pure Python convenience library offering utilities for common operations such as file manipulation, process execution, and logging that developers often find themselves rewriting. It stands alone without external dependencies, focusing on robust handling of edge cases and providing clear error reporting. The current version is 5.7.1, with a regular release cadence.

Warnings

gotcha Many `runez` functions are 'fatal by default.' They will raise an exception on failure, logging a meaningful error. To prevent this and instead return a status or default value, use `fatal=False` for process-related functions (e.g., `runez.run`) or provide a `default` parameter for IO-related functions (e.g., `runez.readlines`).
Fix: Pass `fatal=False` or `default=None` (or another default value) to functions where you want to explicitly handle potential failures without an exception.
gotcha The `logger` parameter in `runez` functions (and global `runez.log.setup()`) offers granular control over logging. Its default (`UNSET`) typically logs at debug level, `logger=None` disables all logging (including errors), and `logger=False` logs only errors. Ensure you understand its impact on your application's logging verbosity.
Fix: Review the `logger` parameter's documentation for specific functions and configure `runez.log.setup()` to match your desired logging behavior and verbosity.
gotcha Runez provides a powerful `dryrun` mode, which, when enabled, simulates actions without performing them. While useful for testing, ensure that `runez.DRYRUN` is `False` or that you explicitly pass `dryrun=False` to functions in production environments where actual operations are intended.
Fix: Explicitly manage `runez.DRYRUN` or pass `dryrun=False` to functions to ensure actions are performed when not in a testing context.

Install

pip install runez Install with pip

Imports

runez
```
import runez
```

Quickstart

This quickstart demonstrates how to execute shell commands and perform basic file operations using `runez`. It shows handling both successful and potentially failing commands, as well as writing to and reading from a file.

import runez
import os

# Example 1: Running a command
print("--- Running a command ---")
try:
    output = runez.run("echo", "Hello from runez!", capture_output=True)
    print(f"Command output: {output.strip()}")

    # Example of a command that might fail gracefully
    print("\n--- Running a command that might fail (fatal=False) ---")
    result = runez.run("this-command-does-not-exist", fatal=False, capture_output=True)
    if result is False:
        print("Command failed gracefully as expected.")
    else:
        print("Unexpected success or output:", result)

except Exception as e:
    print(f"Error running command: {e}")

# Example 2: File operations
print("\n--- File operations ---")
filename = "my_runez_file.txt"
if os.path.exists(filename):
    runez.delete(filename)

runez.write(filename, "First line\nSecond line\n")
print(f"Content written to {filename}")

content = runez.readlines(filename)
print(f"Content read from {filename}: {content}")

runez.delete(filename)
print(f"Deleted {filename}")

view raw JSON →