Dealing with time and date formatting is a common task in many software applications. When presenting timestamps to users, it's often preferable to show them in a more human-readable format, such as "2 hours ago" or "3 days ago," rather than an exact timestamp. The 'timeago' Python package provides a straightforward way to accomplish this. In this article, we'll explore how to use this handy library to simplify date and time representation in Python.

What is 'timeago'?

timeago is a Python library that facilitates the conversion of datetime objects or timestamps into human-readable relative times. Instead of displaying "2023-10-15 14:40:00," with 'timeago', you can show "15 minutes ago," making it more intuitive for end-users.

Installation

Before we dive into using 'timeago', you'll need to install it. Use pip for a quick installation:

pip install timeago

Basic Usage

Here's how you can convert a datetime object to a human-readable format using 'timeago':

import timeago
import datetime

# Create a datetime object for a time in the past
past_date = datetime.datetime.now() - datetime.timedelta(hours=2, minutes=15)

# Convert to a human-readable format
formatted_time = timeago.format(past_date, datetime.datetime.now())
print(formatted_time)
2 hours ago

Note that the timeago.format() function requires two arguments: the past datetime and the current datetime. The difference between them is calculated and then presented in a user-friendly format.

Handling Different Locales

One of the advantages of 'timeago' is its support for various languages. This feature is particularly useful if you're developing a multi-language application. Here's how you can display the relative time in Spanish:

# Ensure you set the right locale
formatted_time_es = timeago.format(past_date, datetime.datetime.now(), 'es')
print(formatted_time_es)
hace 2 horas

You can get list of all locales from timeago repository.

https://github.com/hustcc/timeago/tree/master/src/timeago/locales

Advanced Features

'timeago' also comes with several additional features and utilities to customize its behavior.

1. Using with Timestamps

If you have a timestamp instead of a datetime object, you can still use 'timeago' without any issues:

import time

# Current time as a timestamp
now_timestamp = time.time()

# A timestamp for 45 seconds ago
past_timestamp = now_timestamp - 45

# Format it
formatted_time_seconds = timeago.format(datetime.datetime.fromtimestamp(past_timestamp), datetime.datetime.fromtimestamp(now_timestamp))
print(formatted_time_seconds)
45 seconds ago

2. Limiting Time Frames

If you want to limit the maximum unit used, you can achieve this by setting the max_seconds parameter:

formatted_time_limit = timeago.format(past_date, datetime.datetime.now(), max_seconds=3600)
print(formatted_time_limit)  # Outputs: "135 minutes ago" instead of "2 hours ago"

The timeago library in Python offers a convenient solution for displaying time in a format that's more intuitive and user-friendly. Whether you're working on a web application, a CLI tool, or any other software, presenting time as "2 hours ago" or "3 days ago" enhances user experience and comprehension. With timeago, achieving this is just a few lines of code away.

For more details and documentation, visit timeago official repository.

https://github.com/hustcc/timeago