duck.utils.readable

Human readable formatting utilities.

Converts raw values – byte counts, durations, timestamps, and large numbers – into concise, human readable strings suitable for display in UIs, logs, and reports.

Functions: readable_size: Format a byte count as a storage size (e.g. “1.50 MB”). readable_duration: Format a duration in seconds (e.g. “2 hours 5 minutes”). readable_date: Format a datetime as relative or absolute (e.g. “3 days ago”). readable_count: Format a large number compactly (e.g. “1.2K”, “3.4M”).

Module Contents

Functions

readable_count

Convert a large number into a compact human readable string.

readable_date

Convert a datetime into a human readable relative or absolute string.

readable_duration

Convert a duration in seconds into a human readable string.

readable_size

Convert a byte count into a human readable storage size string.

Data

BINARY_BASE

BINARY_UNITS

COMPACT_COUNT_UNITS

DURATION_UNITS

RELATIVE_DATE_THRESHOLD_DAYS

API

duck.utils.readable.BINARY_BASE

1024

duck.utils.readable.BINARY_UNITS

(‘B’, ‘KB’, ‘MB’, ‘GB’, ‘TB’, ‘PB’, ‘EB’)

duck.utils.readable.COMPACT_COUNT_UNITS

((‘B’, 1000000000.0), (‘M’, 1000000.0), (‘K’, 1000.0))

duck.utils.readable.DURATION_UNITS

((‘year’,), (‘day’,), (‘hour’, 3600), (‘minute’, 60), (‘second’, 1))

duck.utils.readable.RELATIVE_DATE_THRESHOLD_DAYS

7

duck.utils.readable.readable_count(num: float, precision: int = 1) → str[source]

Convert a large number into a compact human readable string.

Parameters:

  • num – The number to format.

  • precision – Number of decimal places to show for scaled values.

Returns:

Human readable count, e.g. “1.2K”, “3.4M”, “980”.

duck.utils.readable.readable_date(dt: datetime.datetime, reference: datetime.datetime | None = None) → str[source]

Convert a datetime into a human readable relative or absolute string.

Parameters:

  • dt – The datetime to describe.

  • reference – The datetime to compare against. Defaults to now.

Returns:

Relative description for recent dates, e.g. “3 hours ago” or “in 2 days”; falls back to an absolute “%b %d, %Y” date once the gap exceeds RELATIVE_DATE_THRESHOLD_DAYS.

duck.utils.readable.readable_duration(total_seconds: float, max_units: int = 2) → str[source]

Convert a duration in seconds into a human readable string.

Parameters:

  • total_seconds – Duration in seconds. Must be non-negative.

  • max_units – Maximum number of time units to include, e.g. 2 gives “1 day 3 hours” instead of “1 day 3 hours 5 minutes”.

Returns:

Human readable duration, e.g. “2 hours 5 minutes”.

Raises:

ValueError – If total_seconds is negative.

duck.utils.readable.readable_size(num_bytes: int, precision: int = 2) → str[source]

Convert a byte count into a human readable storage size string.

Parameters:

  • num_bytes – Size in bytes. Must be non-negative.

  • precision – Number of decimal places to show.

Returns:

Human readable size, e.g. “1.50 MB”.

Raises:

ValueError – If num_bytes is negative.