NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI
Friendly misc/utils/convenience library
Latest stable
5.11.2
Last release 27 days ago
26 Oct 2026
Release timing varies
gaps range from 8 days to 7 months
Most releases are documented
notes for 50 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 years old
199 releases · first in 2018
Drag across the ruler to compare, or tap a release to open it.
Fix PythonSpec parsing of free-threaded Python versions such as 3.14.10t and 3.14.10t+.
PythonSpec parsing of free-threaded Python versions such as 3.14.10t and 3.14.10t+.Annotated Version and PythonSpec comparisons
Annotated Version and PythonSpec comparisons (#66)
Version comparisons are annotated as returning bool: v1 < v2 was inferred as bool | None,
as Version.__lt__() returned None (instead of False) when other could not be parsed as a version
PythonSpec and ArtifactInfo comparisons (via runez.system.ltattr()) and PythonInstallation comparisons
now return False (or NotImplemented) instead of None in their fall-through cases
Your coding agent can read these notes before it upgrades. Set up the MCP server →
More type annotations More type annotations
More type annotations
More type annotations
Added runez.required(value, message): aborts if value is None, returns it otherwise.
Unlike abort_if(not value, ...), type checkers know the returned value is not None
Annotated parameters of ArtifactInfo() and ArtifactInfo.from_basename()
runez.cached_property is now generic: type checkers see the return type of decorated methods
(they were all Unknown before, even when annotated).
Projects using @runez.cached_property will likely see new type checker errors: code flowing through
their own cached properties is now actually checked (typically: properties that can return None)
Annotated return types of Version properties (given_components_count, is_valid, is_final, is_dirty, pep_440),
PythonSpec.abi_suffix, SYS_INFO.invoker_python, SYS_INFO.platform_id, PsInfo.cmd_basename,
runez.which(), runez.touch() and runez.write()
runez.ls_dir() accepts None (it already yielded nothing for None at runtime), and is annotated as yielding Path
Version.is_dirty now always returns a bool (could return None or "" before)
DEV.project_path(), DEV.tests_path() and DEV.venv_path() are now annotated as returning str | None:
they always returned None when not running from a dev project. Use runez.required(...) where a path is expected
ClickRunner.project_path() and ClickRunner.tests_path() (cli test fixture) now assert that the path could be determined,
and are annotated as returning str
ClickRunner (cli test fixture) now captures stderr separately with click>=8.2:
cli.logged.stdout no longer contains what was written to stderr (log chatter, abort() messages).
Use ... in cli.logged (checks both) or cli.logged.stderr in tests that relied on the old behavior
runez.run(..., passthrough=True):
\r\n line ends�)Cover code previously marked pragma: no cover
pragma: no coverTests for Ctrl+C in run_cmds(), running without click installed, and the debugging __repr__ methods.
Co-Authored-By: Claude Opus 5.5 (1M context) noreply@anthropic.com
Enabled ruff UP rule
More type annotations
Consistent logger spec
Co-authored-by: Claude Opus 5.5 (1M context) noreply@anthropic.com
Methods decorated with @runez.log.timeit now return their result (they used to always return None)
Better type annotations: with TempFolder() as tmp: gives a str, RestClient.get(..., fatal=True)
never returns None
Annotated globals that can be changed by users:
RestClient.handlerrunez.system.ABORT_LOGGERrunez.date.DEFAULT_DURATION_SPANrunez.heartbeat.DEFAULT_FREQUENCYrunez.click.Cli attributesPlatformId.default_subsystemRemoved unused PypiStd.DEFAULT_PYPI_URL
Removed runez.cli (unused shortcut), use runez.click.Cli instead
runez.colored() now always returns a str, like named colors (runez.blue() etc.) do:
text was returned as-is when not coloring (or when falsy), now colored(None, ...) is "None", colored(3, ...) is "3"
Removed # pragma: no cover where tests can reach the code instead
Enabled ruff's UP (pyupgrade) rules: collections.abc.Callable, open() instead of io.open(),
OSError instead of IOError, f-strings instead of .format(), unquoted annotations
Added more type annotations
Added more type annotations
Better type annotations for to_int(), to_float(), to_path(), json_sanitized() and ClickRunner.context_wrapper
to_float() (and Configuration.get_float()) no longer return default for non-integer strings
(to_float("1.5", default=0) used to yield 0.0)
Version.mm and Version.main are now empty strings (instead of None) when not applicable
Removed .claude/ (no longer needed)
uvx vermin src/ now reports the correct minimum python (3.10), instead of mistakingfrom runez import file for python2's builtin filepy_mimic()Co-authored-by: Claude Opus 5.5 (1M context) noreply@anthropic.com
Type-checking cleanup (driven by ty), with fixes found along the way:
Version comparisons no longer raise TypeError for versions parsed with different max_parts,
and post/rev/r releases now compare equal (they are equivalent PEP-440 spellings)
abort() overloads simplified, its return type now follows fatal and return_value
runez.system.AbortException = SystemExit and setting runez.date.DEFAULT_TIMEZONE no longer upset type checkers
runez.click imports click only where needed (clear ModuleNotFoundError when it's not installed)
Configuration.provider_by_name() no longer raises AttributeError when a non-dict provider (like propsfs) is present
runez.timezone() accepts name= as a keyword argument (used to raise TypeError)
RestClient.mock() (decorator or context manager) and to_epoch() now have precise signatures
New public type aliases FatalSpec, LoggerSpec and DryrunSpec, used by every fatal=, logger=
and dryrun= parameter (pyright used to reject e.g. logger=None where the default was False)
Edge-case fixes:
delete(), and copy()/move() when overwriting, report failures in non-fatal mode
(instead of leaving the folder behind, or raising)
ensure_folder(clean=True) replaces a file or symlink in the way with an actual folder (an existing folder is
still only emptied, it may be a mount)
Path containment checks (copy(), move(), symlink(), venv detection) no longer match on a string prefix
(foo vs foobar)
SYS_INFO.program_name is the package name when running via python -m (it was __main__)
runez.timezone().dst() returns zero (it returned the UTC offset)
Fixed the github table border (separator row was missing its outer pipes)
RunResult.output and .error are now always a str (they were None when nothing was captured)
Removed (unused) RestClient caching: CacheWrapper, RestClient.std_diskcache() and RestClient(cache=...)
Removed py2-era runez.serialize.add_metaclass() and add_meta(), use metaclass=MetaInjector instead
freethreading is now always a bool (in PythonSpec, and in python installation inspection)
freethreading is now always a bool (in PythonSpec, and in python installation inspection)Be stricter about python specs for freethreading by @thatch in https://github.com/codrsquad/runez/pull/53
Full Changelog: https://github.com/codrsquad/runez/compare/v5.8.0...v5.9.0
PythonInstallation.mm_spec now retains freethreading (e.g. cpython:3.14t)Breaking changes worth highlighting:
Breaking changes worth highlighting:
ArtifactInfo.from_basename() raises ValueError on unparseable input (was None).
Callers that depended on the None branch need to catch ValueError instead.
PythonSpec.version is never None anymore. Code checking spec.version is None should switch to
not spec.is_valid (or not spec.version.is_valid).
cached_property.to_dict(cls) no longer returns None for a class — the method now requires an
instance. If any caller passed the class as a "no cached values" sentinel, they need to adjust.
PythonSpec.from_object(Version("foo")) used to return a spec with an invalid version; now returns
None.
Non-breaking additions:
runez.OptionalColor, Traceable, Version.required_from_object(), PythonSpec.is_valid
abort() overloads — purely a typing improvement, runtime behavior unchanged
More details:
Stronger and more consistent type annotations across the library (pyenv, system, logsetup,
colors, render, serialize); modernized to X | None / list[X] style throughout
Added runez.OptionalColor type alias (Callable | str | None) for parameters accepting a color name,
color callable, or None
Added Traceable protocol in runez.logsetup for objects exposing a .trace(message) method
abort() now has proper @overload-ed signatures: NoReturn when fatal, otherwise returns
return_value with a preserved generic type
Version.required_from_object(): new classmethod that raises ValueError when a version can't be
determined (companion to Version.from_object() which returns None)
Version.from_object(), PythonSpec.from_object() and PythonSpec.from_text() now share a
consistent contract: a returned object is guaranteed to be valid, otherwise None is returned
PythonSpec.is_valid property added as a shortcut for spec.version.is_valid
PythonSpec.__init__ now accepts Version | str (tighter input typing)
ArtifactInfo.from_basename() return type narrowed to ArtifactInfo (no longer | None)
cached_property.to_dict(): target must now be an instance (not a class, not None); always
returns a dict
cached_property.properties() and cached_property._walk_properties(): annotated as
Iterator[...] generators
Avoid crashing when trying to flush log buffers at the end of test runs
Support py3.10+ only
Simplified TempFolder()
Avoid crashing when trying to flush log buffers at the end of test runs
Stronger typing for all methods in runez.file
parent_folder() now returns a Path
to_path() no longer accepts/returns None
Nothing published for this version
Don't try to model source any longer in (seldom used) ArtifactInfo
ArtifactInfoAccept basic types in schemas again
Corrected log wrapping, accept level as default logger
Support py3.8+ for a while longer
Correctly handle main() functions that return a str
main() functions that return a strClickRunner.default_main and ClickRunner.context_wrapper replace deprecated cli.default_main and cli.context
which() looks at current venv bin/ folder first
ClickRunner.default_main and ClickRunner.context_wrapper replace deprecated cli.default_main and cli.context
Removed:
assert_printed() from CapturedStream, TrackedOutput, and ClickRunner
runez.SYS_INFO.platform_id.is_windows
runez.inspector.AutoInstall
runez.inspector.ImportTime
Not exposing in top-level runez import (use from runez.<submodule> import ... if needed):
AdaptedProperty, ascii, config , is_subfolder, PsInfo, SlottedSimplified runez.schema internals
Turned on flake8-simplify and tryceratops, fixed corresponding issues
Added tests
Modernized GH actions and project metadata
ClickRunner.run() now accepts pathlib.Path objects for main/script args
Fixed operator precedence bug in Version.__le__()
Fixed WrappedHandler.clean_accumulated_logs() crash when called before any test runs
stringified() uses errors="replace" when decoding bytes
make_executable() now preserves existing permission bits instead of hardcoding 0o755
Using extractall(filter="data") from stdlib for path traversal protection
Adapted type declarations, pyright now reports 0 errors
Added freethreading support to PythonSpec: new freethreading parameter, abi_suffix property, and "t" suffix parsing in spec strings
PythonSpec: new freethreading parameter, abi_suffix property,
and "t" suffix parsing in spec stringsNothing published for this version
Modernized repo setup, use pyproject.toml, test with py3.14
Dropped support for EOL-ed python versions < 3.10
Removed legacy pypi listing functions from runez.pyenv:
Removed legacy pypi listing functions from runez.pyenv:
default_pypi_client()
latest_pypi_version()
ls_pypi()
pypi_response()
Restore env vars in IsolatedLogSetup context manager
IsolatedLogSetup context managerAdded OverrideDryrun context manager
OverrideDryrun context managerFind already scanned python installations by path
- Added py.typed to package
py.typed to packageDetect buildkit as docker as well
buildkit as docker as wellDon't capture passthrough runs when file handler given
Don't fake existence of PythonInstallation in dryrun mode
PythonInstallation in dryrun modeState when a run failed in runez.log.timeit()
State when a run failed in runez.log.timeit()
Show exit code for failed runez.run() even with pass-through
Don't highlight invoker python anymore
Don't highlight invoker python anymore
Consider "preferred" python only for explicit python3
symlinks in locations that otherwise have pythonM.m symlinks
Corrected side-effect determining preferred_python in PythonDepot
preferred_python in PythonDepotNo preferred python from PATH env var (only from explicitly configured locations)
Automatically determine a preferred_python in PythonDepot
Automatically determine a preferred_python in PythonDepot
More flexible PythonDepot scan for python binaries
Avoid using pkg_resources
- Test against python 3.12
Accept rc versions for in PythonSpec
rc versions for in PythonSpec- Corrected resolved_path()
resolved_path()Corrected bugs in PythonDepot and PythonSpec
PythonDepot and PythonSpecGeneralized PythonDepot specification (API change, PythonDepot now takes a locations specification instead of a scanner object)
Generalized PythonDepot specification
(API change, PythonDepot now takes a locations specification instead of a scanner object)
Added property Version.pep_440 (canonical PEP-440 version representation)
Removed Version.from_text, Version is parsed strictly by default
Accept dots in pypi package names
Pass through any http requests exceptions
requests exceptionsAdd an option in readlines() to skip call to rstrip().
readlines() to skip call to rstrip().Nothing published for this version
Fully implemented PEP-440 for Version ordering
Version orderingCorrected a serialization bug, where nested Serialized objects weren't properly serialized
Corrected a serialization bug, where nested Serialized objects weren't properly serialized
Report last_modified date and size in ArtifactInfo when available
Accept up to 5 version components (was up to 4 before)
Accept up to 5 version components (was up to 4 before)
Report on ignored part of a loosely parsed Version
Corrected comparison of Version-s (was not properly sorting .dev versions before)
Version-s (was not properly sorting .dev versions before)Corrected cli test fixture, avoid crashing when test deleted current working directory
cli test fixture, avoid crashing when test deleted current working directorySupport a simple optional cache for RestClient-s
Support a simple optional cache for RestClient-s
CVE-2007-4559
Avoid creating anything at import time (removed most globals)
Allow to configure a preferred_python in PythonDepot
preferred_python in PythonDepot- Added __repr__ to RunAudit - Corrected docstrings
Added __repr__ to RunAudit
Corrected docstrings
Nothing published for this version
More generic parsing of PythonSpec
More generic parsing of PythonSpec
Respect optional checksum in url, in decompress()
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Restore cwd after a cli test command run
cwd after a cli test command runNothing published for this version
Nothing published for this version
One column per quarter.