repomatic.humanize module

Conversions between raw machine quantities and their human forms.

Byte counts, modification times and service timestamps reach the user through more than one surface (the image-optimization summary, the repomatic cache tables, every dependency report), and each surface should spell them the same way. One home for those conversions keeps the wording consistent and keeps the formatters out of the modules that merely happen to be the first consumer; parse_iso_datetime() is the machine-to-datetime half the renderers start from.

A leaf module with no project-internal imports, so any module can import it without risking a cycle.

repomatic.humanize.SECONDS_PER_DAY = 86400

Divisor turning an mtime delta into whole days.

repomatic.humanize.parse_iso_datetime(value)

Parse an ISO 8601 / RFC 3339 timestamp into a timezone-aware datetime.

The package-wide parser for any timestamp an external service writes: repomatic.deps.dep_report reads PyPI upload times, repomatic.deps.uv lock timestamps, repomatic.cloudflare token expiries and repomatic.github.job_timings job clocks through it, so every consumer tolerates the same shapes.

Uses arrow, so a nanosecond fractional second and a Z suffix (both of which Python 3.10’s stdlib datetime.fromisoformat rejects) parse cleanly; sub-microsecond precision is truncated to fit datetime.

arrow also supplies the .humanize() relative-time phrasing used in the sync report.

Todo

Switch this parser back to whenever, the prior implementation, once it grows a humanizer: whenever#277.

Parameters:

value (str) – An ISO 8601 / RFC 3339 instant, or empty.

Return type:

datetime | None

Returns:

A timezone-aware datetime, or None when value is empty or not a valid instant.

repomatic.humanize.format_file_size(size_bytes)

Format a byte count as a human-readable string.

A thin binding of click_extra.format_size() to the JEDEC unit style (binary powers with the customary KB/MB symbols), matching the format produced by calibreapp/image-actions.

Return type:

str

repomatic.humanize.format_age(mtime)

Format a file mtime as a human-readable age string.

Rounds down to whole days, since the cache tables it feeds exist to answer “is this stale?”, not to time anything precisely.

Parameters:

mtime (float) – POSIX timestamp, as returned by Path.stat().st_mtime.

Return type:

str

Returns:

"today", "1 day", or "{n} days".