Exploring Python's humanize Module

In the world of software development, representing data in a way that's clear and easy for humans to understand can make a significant difference in user experience. This is where the Python humanize module comes in—a utility that is as useful as it is straightforward. Whether you're formatting dates, numbers, or units of measure, humanize provides the tools necessary to make your data approachable.

Getting Started with humanize

To begin using humanize, you first need to install the module. You can add it to your Python environment with a simple command.

Installation

Install humanize using pip:

pip install humanize

With humanize installed, you're ready to start transforming data into human-friendly strings. Let's explore some of its core functionalities.

Converting Numbers to Words

One of the most common tasks is converting numbers into text. This can help users quickly comprehend the magnitude of a number, whether they are integers or floating-point values.

import humanize

# Convert an integer to words
number = 1234567
print(humanize.intword(number))  # Output: '1.2 million'

# Convert an ordinal
ordinal_number = 1
print(humanize.ordinal(ordinal_number))  # Output: '1st'

ordinal_number = 2
print(humanize.ordinal(ordinal_number))  # Output: '2nd'

# Convert a large floating-point number to an approximate word format
float_number = 1234.56
print(humanize.intword(int(float_number)))  # Output: '1.2 thousand'

By converting numbers into approximate words, humanize helps ensure that figures are instantly understandable, especially when dealing with large values in non-technical contexts.

Making Dates Human-Friendly

Dates and times are central to many applications, yet they often need clarification when presented in raw formats. humanize offers functions to make date information more readable.

import humanize
from datetime import datetime, timedelta

# Make human-friendly relative time
now = datetime.now()
print(humanize.naturaltime(now - timedelta(days=3)))  # Output: '3 days ago'
print(humanize.naturaltime(now + timedelta(days=3)))  # Output: '2 days from now'
print(humanize.naturaltime(now - timedelta(seconds=60)))  # Output: 'a minute ago'
print(humanize.naturaltime(now - timedelta(days=120)))  # Output: '3 months ago'
print(humanize.naturaltime(now - timedelta(days=365)))  # Output: 'a year ago'

print(humanize.naturalday(now - timedelta(days=1)))  # Output: 'yesterday'
print(humanize.naturalday(now - timedelta(days=10), format="%B %d, %Y"))  # Output: 'April 18, 2025'

Through natural language, humanize turns abstract temporal data into information that feels tangible and intuitive to users.

Localization of Dates

To cater to a global audience, humanize allows date localization. Here’s how you can localize dates for Spanish:

import humanize
from datetime import datetime, timedelta

# Set locale
humanize.i18n.activate("es_ES")

# Make a human-friendly relative time
now = datetime.now()

print(humanize.naturaltime(now - timedelta(days=3)))  # Output: 'hace 3 días'
print(humanize.naturalday(now - timedelta(days=1)))  # Output: 'ayer'

Handling Durations

For applications displaying time durations, such as task completion times or countdowns, humanize simplifies these into easily digestible formats.

import humanize
from datetime import timedelta

duration = timedelta(seconds=5457)
print(humanize.precisedelta(duration))  # Output: '1 hour, 30 minutes and 57 seconds'

By presenting time intervals clearly, humanize enhances the usability of applications that manage or display durations.

Handling File Sizes

File sizes often need to be presented in a manner users find easy to interpret. With humanize, you can swiftly convert raw byte counts into readable file size expressions.

import humanize

# Convert bytes to human-readable file size
size_in_bytes = 1572864
print(humanize.naturalsize(size_in_bytes, binary=True))  # Output: '1.5 MiB'

Offering a usable, comprehensible file size requires only a straightforward function call with humanize.

Human-Readable Floating Point Numbers

humanize also provides functionality to convert floating-point numbers into human-readable fractions, making them easier to comprehend:

import humanize

print(humanize.fractional(1/3))    # Output: '1/3'
print(humanize.fractional(1.5))    # Output: '1 1/2'
print(humanize.fractional(0.3))    # Output: '3/10'
print(humanize.fractional(0.333))  # Output: '333/1000'
print(humanize.fractional(1))      # Output: '1'

This feature is especially useful for representing fractional values in a format that is more intuitive and relatable, improving clarity and understanding in your application outputs.

Conclusion

Python's humanize module turns complex data into readily understandable information, enhancing how users interact with software. By converting numbers, dates, and durations into more relatable formats, you can improve clarity and communication in your projects.