Skip to main content

Friendly misc/utils/convenience library

Version on pypi Tested with Github Actions Python versions tested (link to github project)

Overview

runez is a convenience "utils" library for common operations I found myself rewriting multiple times.

The name was initially meant as “run ez” (“run easy”), the fact that it sounds like “runes” gives it a bit of a mystery/magic side that’s also relatively appropriate (it does indeed concentrate a bit of invocation magic, as you can save quite a few lines of repetitive code by using it)

Features

  • Usable with any python version

  • Pure python standalone library, does not bring in any additional dependency

  • Takes care of most edge cases, with nice errors

    • Functions can be called without checking for return code etc (abort by default, with nice error)

    • They can also be called with fatal=False, in which case the return value will indicate whether call succeeded or not

  • Support for dryrun mode (show what would be done, but don’t do it)

  • Perform most typical logging setups in one call to runez.log.setup()

  • Log operations systematically (at debug level mostly), examples:

    Running: foo ...
    Copy foo -> bar
    Would move foo -> bar    (for dryrun)
  • CaptureOutput context manager -> grab output/logging from any code section

  • 100% test coverage

Example

Run a program:

import runez

# Aborts if "foo" doesn't exist
output = runez.run("ls", "foo")

# Output can also be ignored
runez.run("ls", "foo")

# Don't capture output, just run the command and let output "pass through"
runez.run("ls", "foo", stdout=None, stderr=None)

# Don't abort, return False on failure (or actual output when successful)
output = runez.run("ls", "foo", fatal=False)

File operations:

import runez

runez.touch("foo")
runez.copy("foo", "bar")
runez.move("foo", "baz")
runez.delete("foo")

runez.write("foo", "bar\nbaz\n")
content = "\n".join(runez.readlines("foo", first=10))

full_path = runez.resolved_path("foo/bar")
folder = runez.parent_folder(full_path)
runez.ensure_folder(folder)
with runez.Anchored(folder):
    assert runez.short(full_path) == "bar"

Installation

As usual, available on pypi: pip install runez

Philosophy

runez tries to provide a consistent interface across functions. Here are the main tenets for functions involving I/O (such as writing, reading, copy-ing files etc):

All IO-related functions NOT returning content (run(), delete(), …) have this common signature: fatal=True, logger=UNSET, dryrun=UNSET

  • fatal: decides whether operation should raise an exception on failure or not

    • fatal=True (default): raise an exception on failure, log a meaningful error

    • fatal=False: don’t raise on failure, log a meaningful error

    • fatal=None: don’t raise on failure, don’t log anything

    • In non-fatal mode, calls try to return a usable value appropriate for the call (see docstring of each function)

  • logger: decides how chatty the operation should be

    • LOG.error() is used for failures, except when fatal is not True AND provided logger is a callable

    • logger=UNSET (default):

      • LOG.debug("Running: ...") to trace activity

      • print("Would run: ...") in dryrun mode

    • logger=False: Log errors only (used internally, to avoid unnecessary log chatter when one operation calls another)

    • logger=mylogger: call provided mylogger() to trace activity (example: logger=MY_LOGGER.info)

      • mylogger("Running: ...") to trace activity

      • mylogger("Would run: ...") in dryrun mode

    • logger=None: Don’t log anything (even errors)

  • dryrun allows to override current runez.DRYRUN setting just for that call

All IO-related functions returning content (read_json(), readlines(), …) use a simpler convention based on: default=UNSET, which decides whether operation should raise an exception on failure or not:

  • When default is NOT provided, the function call will abort on failure with an exception, logging a meaningful error via LOG.error()

  • When default is provided (even if None), the function call will NOT abort, but return the specified default instead, it is up to the caller to log anything in that case (no log chatter comes from runez in that case, at all)

Metadata

Release files for runez 5.11.3

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

Source distribution (sdist)

Source distribution for runez 5.11.3
File Size Uploaded Provenance Actions
runez-5.11.3.tar.gz 167.0 kB With provenance Details for runez-5.11.3.tar.gz

Built distribution (wheel)

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

Total release size: 289.3 kB

Release files / runez-5.11.3.tar.gz

Download URL runez-5.11.3.tar.gz
Size 167.0 kB
Tags Source
SHA-256 checksum
How to use checksums
794591e707c179a19d9ec47bbb968b68fee2d04375b7955d01dc5707afb87742
BLAKE2b-256 checksum
How to use checksums
2eb04f12d1e1e2c98fef6b9c9dd8b74b1df4f840c923ef089193f647f0b75dd7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / runez-5.11.3-py3-none-any.whl

Download URL runez-5.11.3-py3-none-any.whl
Size 122.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a1833de66ea0727c0e9f785c79d3af4e7e54d079e16ca6ad31b926e8278b9a6f
BLAKE2b-256 checksum
How to use checksums
4d157ba28f9dcbadc346b4332e2cce6126f3fe0fbc5224cfdfb974991d2a6499
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for runez 5.11.3

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for runez-5.11.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

5.11.3 This release

2 release files Full provenance

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