humanize API全解析：开发者必备的参数与使用技巧

humanize API全解析：开发者必备的参数与使用技巧

【免费下载链接】humanizePython humanize functions项目地址: https://gitcode.com/gh_mirrors/human/humanize

humanize是一个强大的Python库，提供了丰富的人性化处理函数，能将数字、时间、文件大小等数据转换为更易读的格式。无论是开发用户界面还是生成报告，掌握这些API都能让你的应用更具专业感和用户友好性。

核心功能概览 🚀

humanize库的核心功能集中在几个关键模块中，每个模块都针对特定类型的数据处理：

• 文件大小处理：src/humanize/filesize.py
• 时间格式化：src/humanize/time.py
• 数字处理：src/humanize/number.py
• 国际化支持：src/humanize/i18n.py
• 列表格式化：src/humanize/lists.py

文件大小转换：naturalsize详解

naturalsize函数是处理文件大小的利器，能将字节数转换为人类可读的格式。其定义如下：

def naturalsize( value: NumberOrString, binary: bool = False, gnu: bool = False, format: str | None = None, precision: int | None = None, ) -> str:

关键参数：

• binary：设置为True时使用二进制前缀（KiB、MiB），默认使用十进制（KB、MB）
• precision：控制小数点后显示的位数
• gnu：启用GNU风格，在小于1024时显示字节数

实用示例：

naturalsize(3000000) # 输出 '3.0 MB' naturalsize(3000, False, True) # 输出 '3.0K' naturalsize(10**28) # 输出 '10.0 YB'

时间处理：naturaltime与naturaldelta

naturaltime：智能时间描述

naturaltime函数能将时间戳转换为自然语言描述，如"3分钟前"或"2小时后"。

def naturaltime( value: dt.datetime | dt.timedelta | float, future: bool = False, months: bool = True, minimum_unit: str = "seconds", when: dt.datetime | None = None, ) -> str:

核心参数：

• minimum_unit：设置最小时间单位（seconds/minutes/hours等）
• when：自定义参考时间，默认为当前时间
• months：是否启用月份级别的精度

naturaldelta：时间差格式化

对于时间间隔的处理，naturaldelta提供了清晰的描述方式：

def naturaldelta( value: dt.timedelta | float, minimum_unit: str = "seconds", precision: int = 0, suppress: Iterable[str] | None = None, format: str | None = None, ) -> str:

使用场景：

• 显示任务执行时间
• 计算两个事件之间的间隔
• 倒计时功能实现

数字格式化：让数字更易读

ordinal：序数转换

ordinal函数将数字转换为序数形式，支持多语言性别规则：

def ordinal(value: NumberOrString, gender: str = "male") -> str:

示例：

ordinal(1) # 输出 '1st' ordinal(2, gender="female") # 输出 '2nd'（部分语言有性别差异）

intcomma：千位分隔符

为大数字添加千位分隔符，提升可读性：

def intcomma(value: NumberOrString, ndigits: int | None = None) -> str:

示例：

intcomma(1234567) # 输出 '1,234,567' intcomma(1234.567, ndigits=2) # 输出 '1,234.57'

国际化支持：多语言处理

humanize提供了完善的国际化支持，通过i18n.py模块实现：

def activate(locale: str, path: str | pathlib.Path | None = None) -> None: def deactivate() -> None:

支持的语言：

• 中文：src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po
• 英文：src/humanize/locale/en/LC_MESSAGES/humanize.po
• 日文：src/humanize/locale/ja_JP/LC_MESSAGES/humanize.po
• 更多语言：src/humanize/locale/

使用方法：

activate('zh_CN') # 激活中文本地化 naturaltime(datetime.now() - timedelta(days=1)) # 输出 '1天前'

实用技巧与最佳实践

1. 安装与配置

通过pip安装humanize：

pip install humanize

2. 组合使用函数

结合多个函数创建更丰富的格式化效果：

# 格式化文件大小和修改时间 def format_file_info(size, mtime): return f"文件大小: {naturalsize(size)}, 修改于: {naturaltime(mtime)}"

3. 自定义格式

通过format参数自定义输出格式：

naturalsize(3000, format="%.3f") # 输出 '3.000 KB'

总结

humanize库为Python开发者提供了全面的人性化数据格式化解决方案，通过简单直观的API，就能让你的应用呈现专业级的用户体验。无论是处理时间、数字还是文件大小，这些工具函数都能大大减少开发工作量，同时提升输出质量。

要深入了解更多功能，可以查阅官方文档：docs/，或查看源代码中的详细注释。

获取项目：

git clone https://gitcode.com/gh_mirrors/human/humanize

【免费下载链接】humanizePython humanize functions项目地址: https://gitcode.com/gh_mirrors/human/humanize