Sizelib

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

🔗 PyPI Package  |  🆔 pip install sizelib or uv add sizelib

🐍 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 and expressions are fully supported
limit = 2
custom_limit = size.gib(limit)   # 2 GiB (2147483648 bytes)

print(MAX_UPLOAD_SIZE)           # Output: 10485760
print(type(MAX_UPLOAD_SIZE))     # Output: <class 'int'>

Time Helper Functions

from sizelib import time

TIMEOUT = time.s(30)          # 30 s
CACHE_TTL = time.min(15)      # 900 s
TOKEN_EXPIRY = time.hour(2)   # 7200 s
WORKER_WAIT = time.ms(500)    # 0.5 s

Humanize Byte Sizes (human_size)

from sizelib import human_size, size

# Default binary formatting (base 2 / 1024)
print(human_size(MAX_UPLOAD_SIZE))  # Output: 10 MiB
print(human_size(CACHE_LIMIT))      # Output: 2 GiB

# Decimal values are formatted up to 2 decimal places
TOTAL = CACHE_LIMIT + size.mib(500)
print(human_size(TOTAL))            # Output: 2.49 GiB

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

Humanize Times (human_time)

from sizelib import human_time, time

print(human_time(0.005))        # Output: 5 ms
print(human_time(time.s(45)))   # Output: 45 s
print(human_time(time.min(90))) # Output: 1.50 hour
print(human_time(time.hour(2))) # Output: 2 hour
print(human_time(time.day(1)))  # Output: 1 day

✨ Features

🏗️ System Architecture

Made with 📄 by Saptarshi Roy