Ctrl+K

rics.strings#

Utility functions that act on or produce strings.

Functions

format_bytes(n, *[, binary, long, decimals])

Format bytes as a string.

format_perf_counter(start, *[, end])

Format performance counter output.

format_seconds(t, *[, allow_negative])

Format performance counter output.
format_bytes(n: int, *, binary: bool = True, long: bool = False, decimals: int = 2) → str[source]#

Format bytes as a string.

Parameters:

  • n – Number of bytes. Must be positive.

  • binary – Output binary prefixes if True, use metric (SI) prefixes otherwise.

  • long – Output out full unit and prefix if True, use abbreviated versions otherwise.

  • decimals – Number of decimals to include. Ignored for when n < base.

Returns:

Formatted number of bytes.

Examples

Formatting on prefix bounds

The jump as made at base / 2, where base is one of 1024 and 1000 (when binary=False).

>>> format_bytes(512 * 1024)
'512.00 KiB'
>>> format_bytes(512 * 1024 + 1)
'0.50 MiB'

This rule does not apply when n <= base.

>>> format_bytes(1024, long=True)
1024 bytes
>>> format_bytes(1024 + 1)
'1.00 KiB'

Output flags

>>> format_bytes(20190511, binary=False, long=False)
'20.19 MB'
>>> format_bytes(20190511, binary=False, long=True)
'20.19 megabytes'
>>> format_bytes(20190511, binary=True, long=False)
'19.26 MiB'
>>> format_bytes(20190511, binary=True, long=True)
'19.26 mebibytes'

Large outputs

Metric and binary have different upper limits.

>>> format_bytes(21**21, binary=True)
'2416.44 YiB'
>>> format_bytes(21**21, binary=True, long=True)
'2416.44 yobibytes'
>>> format_bytes(21**21, binary=False)
'5.84 RB'
>>> format_bytes(21**21, binary=False, long=True)
'5.84 ronnabytes'

If you ever see output like this, please let me know so that I can brag that someone important is using my little library.

format_perf_counter(start: float, *, end: float | None = None) → str[source]#

Format performance counter output.

This function formats performance counter output based on the time elapsed. This is a thin wrapper around the format_seconds() function.

Parameters:
Returns:

A formatted performance counter time.

Examples

Basic usage.

>>> import time
>>> start = time.perf_counter()
>>> time.sleep(1219.0)  
>>> format_perf_counter(start)  
'20m 19s'

With no end argument given, the current time is retrieved using time.perf_counter().

format_seconds(t: float, *, allow_negative: bool = False) → str[source]#

Format performance counter output.

Parameters:

  • t – Time in seconds.

  • allow_negative – If True, format negative t with a leading minus sign.

Returns:

A formatted performance counter time.

Examples

Basic usage.

>>> format_seconds(0.0000154)
'15μs'
>>> format_seconds(0.154)
'154ms'
>>> format_seconds(31.39)
'31.4s'

Clock units are used for t > 60 seconds.

>>> format_seconds(59.99)
'60.0s'
>>> format_seconds(60.00)
'60.0s'
>>> format_seconds(60.01)
'1m'
>>> format_seconds(309613.49)
'3d 14h 0m 13s'
Raises:

ValueError – If t < 0 and allow_negative=False (the default).

On this page