⏱️ timesaver

A lightning-fast, zero-dependency micro-library to instantly convert messy machine data (raw bytes, seconds, and dates) into sleek, human-readable strings.

🚀 Why timesaver?

Most "humanizing" packages suffer from feature creep—carrying heavy translation files, scientific formulas, and massive footprints. timesaver is built for developers who just want sleek, dashboard-ready strings with zero bloat.

• Ultra-lightweight: Zero external dependencies. Perfect for AWS Lambda or microservices.
• Smart Types: Automatically handles both Python datetime and pure calendar date objects.
• Tech-Friendly: Formats strings cleanly (15m ago instead of fifteen minutes ago) to fit beautiful UI layouts.

📦 Installation

Install it instantly via pip:

pip install timesaver

💻 Quick Start & Examples

Humanizing File Sizes (filesize)

Convert large integers of bytes into dynamically scaled, clean string readouts.

import timesaver

print(timesaver.filesize(1024))       # Output: "1.0 KB"
print(timesaver.filesize(5432100))    # Output: "5.2 MB"
print(timesaver.filesize(1200000000)) # Output: "1.1 GB"

Smart Relative Time (ago)

Pass either a high-precision datetime object or a standard calendar date object. The engine will automatically calculate the difference relative to right now.

import timesaver
import datetime as dt

# Example A: Using a precise datetime (e.g., 15 minutes ago)
past_datetime = dt.datetime.now() - dt.timedelta(minutes=15)
print(timesaver.ago(past_datetime))  # Output: "15m ago"

# Example B: Using a pure calendar date (e.g., 5 days ago)
past_date = dt.date.today() - dt.timedelta(days=5)
print(timesaver.ago(past_date))      # Output: "5d ago"

🛠️ API Reference

timesaver.filesize(bytes_count: int) -> str
Takes an integer representing bytes. Scaled automatically across B, KB, MB, GB, TB, and PB. Raises a ValueError if the number is negative.

timesaver.ago(timestamp: Union[datetime, date]) -> str
Calculates distance from the current time. Breaks down into thresholds:

< 60 seconds -> "just now"

< 1 hour -> "Xm ago"

< 24 hours -> "Xh ago"

< 30 days -> "Xd ago"

< 12 months -> "Xmo ago"

> 1 year -> "Xy ago"

• Built by Roy Peters