{"id":6447,"library":"runez","title":"Runez Library","description":"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.","status":"active","version":"5.7.1","language":"en","source_language":"en","source_url":"https://github.com/codrsquad/runez","tags":["utilities","misc","convenience","file operations","process execution","logging"],"install":[{"cmd":"pip install runez","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"runez","correct":"import runez"}],"quickstart":{"code":"import runez\nimport os\n\n# Example 1: Running a command\nprint(\"--- Running a command ---\")\ntry:\n    output = runez.run(\"echo\", \"Hello from runez!\", capture_output=True)\n    print(f\"Command output: {output.strip()}\")\n\n    # Example of a command that might fail gracefully\n    print(\"\\n--- Running a command that might fail (fatal=False) ---\")\n    result = runez.run(\"this-command-does-not-exist\", fatal=False, capture_output=True)\n    if result is False:\n        print(\"Command failed gracefully as expected.\")\n    else:\n        print(\"Unexpected success or output:\", result)\n\nexcept Exception as e:\n    print(f\"Error running command: {e}\")\n\n# Example 2: File operations\nprint(\"\\n--- File operations ---\")\nfilename = \"my_runez_file.txt\"\nif os.path.exists(filename):\n    runez.delete(filename)\n\nrunez.write(filename, \"First line\\nSecond line\\n\")\nprint(f\"Content written to {filename}\")\n\ncontent = runez.readlines(filename)\nprint(f\"Content read from {filename}: {content}\")\n\nrunez.delete(filename)\nprint(f\"Deleted {filename}\")","lang":"python","description":"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."},"warnings":[{"fix":"Pass `fatal=False` or `default=None` (or another default value) to functions where you want to explicitly handle potential failures without an exception.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the `logger` parameter's documentation for specific functions and configure `runez.log.setup()` to match your desired logging behavior and verbosity.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly manage `runez.DRYRUN` or pass `dryrun=False` to functions to ensure actions are performed when not in a testing context.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}