Metadata-Version: 2.4
Name: timesaver
Version: 0.1.0
Summary: A micro-library to instantly convert raw machine data into clean, human-readable strings.
Author-email: Roy Peters <roy.peters040@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ⏱️ timesaver

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

[![PyPI Version](https://img.shields.io/pypi/v/timesaver.svg)](https://pypi.org/project/timesaver/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🚀 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`:

```bash
pip install timesaver
```
## 💻 Quick Start & Examples
### Humanizing File Sizes (filesize)
Convert large integers of bytes into dynamically scaled, clean string readouts.

```Python
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.

```Python
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
```python
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.
```

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

```python
< 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
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Roy%20Peters-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/roy-p-74980b382/)

