hbutils.scale.size

Utilities for converting and formatting memory size values.

This module provides helpers to normalize size representations into integer byte counts and to format sizes into human-readable strings using binary (NIST) or decimal (SI) prefixes. It builds on bitmath to parse and format values while ensuring integer byte counts, issuing warnings when floating-point rounding is required.

The module contains the following public components:

size_to_bytes() - Convert size representations to integer bytes
size_to_bytes_str() - Format sizes into a readable string
SizeSystem - Enumerated size systems for formatting

Note

Floating-point byte values are rounded to the nearest integer with a warning when the rounding is non-negligible.

Example:

>>> from hbutils.scale.size import size_to_bytes, size_to_bytes_str, SizeSystem
>>> size_to_bytes('3.54 GB')
3540000000
>>> size_to_bytes_str('3.54 GB')
'3.296881914138794 GiB'
>>> size_to_bytes_str('3.54 GB', system='si')
'3.54 GB'
>>> SizeSystem.loads('nist')  # Enum lookup for formatting system
<SizeSystem.NIST: 2>

all

hbutils.scale.size.__all__ = ['size_to_bytes', 'size_to_bytes_str']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

SizeSystem

class hbutils.scale.size.SizeSystem(value)[source]

Enumeration of size systems used for formatting.

The enumeration is enhanced by hbutils.model.int_enum_loads(), providing a loads() class method for convenient lookup by name or value.

Variables:

NIST – Uses binary prefixes (KiB, MiB, GiB, etc.).
SI – Uses decimal prefixes (KB, MB, GB, etc.).

Example:

>>> SizeSystem.loads('nist') is SizeSystem.NIST
True
>>> SizeSystem.loads('si') is SizeSystem.SI
True
>>> SizeSystem.loads(2) is SizeSystem.NIST
True

size_to_bytes

hbutils.scale.size.size_to_bytes(size: int | float | str | Byte) → int[source]

Convert any type of memory size representation to an integer value in bytes.

Parameters:

size (Union[int, float, str, Byte]) – Any type of size information.

Returns:

Size in bytes as an integer.

Return type:

int

Raises:

TypeError – If size is not an int, float, str, or bitmath.Byte.
ValueError – If a string cannot be parsed by bitmath.parse_string_unsafe().

This function can handle various input types:

Integers and floats are treated as byte values.
Strings are parsed as size representations (e.g., "23356 KB").
bitmath.Byte objects are converted to their byte value.

Examples:

>>> from hbutils.scale import size_to_bytes
>>> size_to_bytes(23344)
23344
>>> size_to_bytes('23356 KB')
23356000
>>> size_to_bytes('3.54 GB')
3540000000
>>> size_to_bytes('3.54 GiB')
__main__:1: UserWarning: Float detected in variable in bytes (3801046056.96), rounded integer value (3801046057) is used.
3801046057

size_to_bytes_str

Convert any type of memory size to a string value in the most appropriate unit.

Parameters:

size (Union[int, float, str, Byte]) – Any type of size information.
precision (Optional[int]) – Precision for float values. When None, the default string representation from bitmath is used.
sigfigs (Optional[int]) – Number of significant figures to use. If specified, this overrides precision.
system (Literal['nist', 'si']) – The unit system to use, either 'nist' (binary) or 'si' (decimal). Default is 'nist'.

Returns:

String formatted size value in the best unit.

Return type:

str

Raises:

ValueError – If an invalid system type is provided.
TypeError – If size is not an int, float, str, or bitmath.Byte.
ValueError – If a string cannot be parsed by bitmath.parse_string_unsafe().

This function provides a human-readable representation of size values. It automatically chooses the most appropriate unit (B, KB/KiB, MB/MiB, etc.) based on the size.

The system parameter allows choosing between NIST (binary, e.g., KiB) and SI (decimal, e.g., KB) units.