jmoiron/humanize · 上手攻略

• 仓库：jmoiron/humanize
• 链接：https://github.com/jmoiron/humanize
• 分类：python
• 作者：Tom
• 更新：2026-08-22

是什么

humanize 是 Python 标准数据类型的"人性化"转换库——把机器友好格式转为人类可读文字。数字、日期、时间增量、文件大小、分数、科学计数法，统统转成自然语言输出。覆盖 24 种语言本地化（含简体中文、繁体中文）。

解决什么问题

后端日志、API 响应、Admin 面板里，原始数字/时间戳对用户不友好：123455913 看起来费劲，1703275200 不知所云。humanize 填补了"数据已格式化但还不够 human-friendly"这个中间地带——比 strftime 多一步语义化，比前端库轻一个量级。

快速安装

pip install humanize
# 或
uv add humanize

要求 Python ≥ 3.8（⚠️ 未实测验证最低版本，README 原文如此）。

核心用法

数字人性化

import humanize

humanize.intcomma(12345)       # '12,345'
humanize.intword(123455913)     # '123.5 million'
humanize.intword(12345591313)   # '12.3 billion'
humanize.apnumber(4)            # 'four'
humanize.apnumber(41)           # '41'
humanize.fractional(1/3)        # '1/3'
humanize.fractional(1.5)        # '1 1/2'
humanize.scientific(0.3)         # '3.00 x 10⁻¹'
humanize.scientific(500)        # '5.00 x 10²'

⚠️ apnumber 对 0-9 返回英文单词，10 及以上返回数字字符串（README 示例 41 → '41'）。

日期与时间

import datetime as dt

humanize.naturalday(dt.datetime.now())               # 'today'
humanize.naturalday(dt.datetime.now() - dt.timedelta(days=1))  # 'yesterday'
humanize.naturalday(dt.date(2007, 6, 5))             # 'Jun 05'

humanize.naturaldate(dt.date(2007, 6, 5))            # 'Jun 05 2007'

humanize.naturaldelta(dt.timedelta(seconds=1001))    # '16 minutes'
humanize.naturaldelta(dt.timedelta(seconds=2))        # '2 seconds'
humanize.naturaldelta(dt.timedelta(milliseconds=4))  # 'a moment'

humanize.precisedelta(
    dt.timedelta(seconds=3633, days=2, microseconds=123000),
    minimum_unit="microseconds"
)  # '2 days, 1 hour, 33 seconds and 123 milliseconds'

文件大小

humanize.naturalsize(1_000_000)           # '1.0 MB'（SI 十进制）
humanize.naturalsize(1_000_000, binary=True)  # '976.6 KiB'（IEC 二进制）
humanize.naturalsize(1_000_000, gnu=True)    # '976.6K'（GNU ls 风格）

⚠️ 默认是 SI 十进制（1 KB = 1000 B），binary=True 才是 1024 进制，容易搞混。

本地化（多语言）

import humanize

humanize.naturaltime(dt.timedelta(seconds=3))        # '3 seconds ago'
_t = humanize.i18n.activate("ru_RU")
humanize.naturaltime(dt.timedelta(seconds=3))        # '3 секунды назад'
humanize.i18n.deactivate()

支持语言：ar, bn, br, ca, da, de, en, es, fa, fi, fr, id, it, ja, ko, nl, pl, pt_BR, ru, sk, sl, sv, tr, uk, vi, zh_CN, zh_TW 等 24+ 种。

典型适用场景

• 日志/监控界面：把毫秒时间戳显示为"3 minutes ago"
• 数据表格：把字节数显示为"2.3 GB"而非"2415919104"
• 内容发布平台：文章列表显示"Jun 05"而非 datetime 对象
• 多语言 SaaS：切换 locale 输出对应语言的数字/日期格式
• AI 提示词上下文：把数字嵌入 prompt 前做 humanize 预处理

坑与注意

1. SI vs IEC 混淆：默认 naturalsize 是十进制（1 KB = 1000 B），不是 Linux ls -lh 的二进制；需要 binary=True。
2. apnumber 边界行为：0-9 英文单词，10+ 直接返回数字字符串，不是"第 4 个"这种序数。
3. locale 文件需额外安装：部分语言（如 pt_BR）可能需要通过 humanize.i18n.activate("xx_XX", path="...") 加载自定义路径。
4. microseconds 精度损失：Python timedelta 本身对纳秒有限精度，大数值微秒可能有舍入。
5. 非线程安全：i18n.activate() 修改全局状态，多线程环境下注意 deactivate() 清理。

与同类对比

humanize 的优势是轻量 + 全覆盖 + 即装即用，没有 babel 那么重，又比 dateutil 功能全。

一句话推荐结论

Python 数据 humanize 轻量首选库，24+ 语言覆盖，后台/监控/AI 上下文中把数字和时间戳变可读文字一行搞定。

来源

• GitHub README：https://github.com/jmoiron/humanize
• Python READTHEDOCS：https://python-humanize.readthedocs.io