Metadata-Version: 2.4
Name: philiprehberger-timeago
Version: 0.2.0
Summary: Convert timestamps to relative time phrases like '3 hours ago'
Project-URL: Homepage, https://github.com/philiprehberger/py-timeago#readme
Project-URL: Repository, https://github.com/philiprehberger/py-timeago
Project-URL: Issues, https://github.com/philiprehberger/py-timeago/issues
Project-URL: Changelog, https://github.com/philiprehberger/py-timeago/blob/main/CHANGELOG.md
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: datetime,human,relative,timeago,timestamp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-timeago

[![Tests](https://github.com/philiprehberger/py-timeago/actions/workflows/publish.yml/badge.svg)](https://github.com/philiprehberger/py-timeago/actions/workflows/publish.yml)
[![PyPI version](https://img.shields.io/pypi/v/philiprehberger-timeago.svg)](https://pypi.org/project/philiprehberger-timeago/)
[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/py-timeago)](https://github.com/philiprehberger/py-timeago/commits/main)

Convert timestamps to relative time phrases like "3 hours ago".

## Installation

```bash
pip install philiprehberger-timeago
```

## Usage

```python
from philiprehberger_timeago import timeago, timedelta_human
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

timeago(now - timedelta(seconds=30))  # "30 seconds ago"
timeago(now - timedelta(hours=3))     # "3 hours ago"
timeago(now - timedelta(days=1))      # "yesterday"
timeago(now + timedelta(days=7))      # "in 1 week"

# Unix timestamps
timeago(1709913600)

# Duration formatting
timedelta_human(timedelta(hours=3, minutes=25))  # "3 hours, 25 minutes"
```

### Compact age

```python
from philiprehberger_timeago import format_age
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

format_age(now - timedelta(seconds=5))    # "5s"
format_age(now - timedelta(minutes=3))    # "3m"
format_age(now - timedelta(hours=2))      # "2h"
format_age(now - timedelta(days=4))       # "4d"
format_age(now + timedelta(hours=1))      # "-1h" (future)
```

### Numeric mode

```python
from philiprehberger_timeago import timeago
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

timeago(now - timedelta(seconds=5), numeric=True)  # "5 seconds ago" (not "just now")
timeago(now - timedelta(days=1), numeric=True)     # "1 day ago" (not "yesterday")
timeago(now + timedelta(days=1), numeric=True)     # "in 1 day" (not "tomorrow")
```

## API

| Function / Class | Description |
|------------------|-------------|
| `timeago(dt, now=None, numeric=False)` | Relative time phrase from datetime, date, or Unix timestamp; `numeric=True` forces numeric phrasing |
| `format_age(dt, now=None)` | Compact age string like `5s`, `3m`, `2h`, `4d`, `1mo`, `2y` (future prefixed with `-`) |
| `timedelta_human(td)` | Format a timedelta as readable duration |

## Development

```bash
pip install -e .
python -m pytest tests/ -v
```

## Support

If you find this project useful:

⭐ [Star the repo](https://github.com/philiprehberger/py-timeago)

🐛 [Report issues](https://github.com/philiprehberger/py-timeago/issues?q=is%3Aissue+is%3Aopen+label%3Abug)

💡 [Suggest features](https://github.com/philiprehberger/py-timeago/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)

❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)

🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)

💻 [GitHub Profile](https://github.com/philiprehberger)

🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)

## License

[MIT](LICENSE)
