Sizelib

sizelib is a lightweight, type-safe Python Library for working with and humanizing file sizes, time durations, and frequencies. It offers clean, type-preserving unit helpers (supporting both int and float) and loop-based human-readable string conversions.

✳️ SDK

Installation

pip install sizelib
# or
uv add sizelib

Size Helper Functions

from sizelib import size

# Define constraints using binary (base 2 / 1024) or decimal (base 10 / 1000) helper methods
MAX_UPLOAD_SIZE = size.mib(10)  # 10 MiB (10485760 bytes)
CACHE_LIMIT = size.gib(2)  # 2 GiB (2147483648 bytes)
USER_QUOTA = size.gb(50)  # 50 GB (50000000000 bytes)

# Variables, expressions, and type preservation (int/float) are supported
limit = 2
custom_limit = size.gib(limit)  # 2 GiB (2147483648 bytes)
print(type(size.mib(10)))  # Output: <class 'int'>
print(type(size.kb(1.5)))  # Output: <class 'float'>

Humanize Byte Sizes (human_size)

from sizelib import human_size, size

# Default binary formatting (base 2 / 1024)
print(human_size(10485760))  # Output: 10 MiB
print(human_size(size.gib(2.5)))  # Output: 2.50 GiB

# Decimal formatting (base 10 / 1000)
print(human_size(size.gb(50), base=10))  # Output: 50 GB

Time Helper Functions

from sizelib import time

# Define time constraints cleanly in seconds (supports ms, s, m, h, d, w, m28..m31, y, ly)
TIMEOUT = time.s(30)  # 30 s
CACHE_TTL = time.m(15)  # 900 s
TOKEN_EXPIRY = time.h(2)  # 7200 s
FEB_NON_LEAP = time.m28(1)  # 2419200 s (28 days)

# Variables, expressions, and type preservation (int/float) are supported
limit = 5
custom_timeout = time.m(limit)  # 300 s
print(type(time.s(30)))  # Output: <class 'int'>
print(type(time.s(1.5)))  # Output: <class 'float'>

Humanize Times (human_time)

from sizelib import human_time, time

# Duration formatting across ms, s, m, h, d, w
print(human_time(0.005))  # Output: 5 ms
print(human_time(time.s(45)))  # Output: 45 s
print(human_time(time.m(90)))  # Output: 1.50 h

# Auto-rounds and formats fractional durations up to 2 decimal places
print(human_time(time.h(2.5)))  # Output: 2.50 h

Frequency Helper Functions

from sizelib import freq

# Define frequency constraints cleanly in Hz (supports hz, khz, mhz, ghz, thz, phz, ehz, zhz, yhz)
CPU_BASE_CLOCK = freq.ghz(3.2)  # 3.2 GHz (3200000000.0 Hz)
RAM_SPEED = freq.mhz(3200)  # 3200 MHz (3200000000 Hz)
AUDIO_SAMPLE_RATE = freq.khz(44.1)  # 44.1 kHz (44100.0 Hz)

# Variables, expressions, and type preservation (int/float) are supported
multiplier = 4.5
custom_clock = freq.ghz(multiplier)  # 4.5 GHz (4500000000.0 Hz)
print(type(freq.mhz(800)))  # Output: <class 'int'>
print(type(freq.ghz(4.8)))  # Output: <class 'float'>

Humanize Frequencies (human_freq)

from sizelib import freq, human_freq

# Frequency formatting across Hz through YHz
print(human_freq(44100))  # Output: 44.10 kHz
print(human_freq(freq.mhz(800)))  # Output: 800 MHz
print(human_freq(freq.ghz(3.2)))  # Output: 3.20 GHz
print(human_freq(freq.thz(1.5)))  # Output: 1.50 THz

✳️ Features

✳️ Architecture

Made with 📄 by Saptarshi Roy