Humanize 项目技术文档

1. 安装指南

Humanize 是一个用于数据人性化的 Python 包，它可以将数字、日期和时间等转换为更易于理解的格式。以下是安装 Humanize 的步骤：

从 PyPI 安装

使用 pip 命令从 Python 包索引（PyPI）安装 Humanize：

pip install --upgrade humanize

从源代码安装

克隆 GitHub 仓库并从源代码安装：

git clone https://github.com/python-humanize/humanize.git
cd humanize
pip install -e

2. 项目的使用说明

Humanize 提供了多种实用函数来转换和格式化数据，以下是一些基本用法示例：

整数人性化

import humanize

print(humanize.intcomma(12345))       # 输出: '12,345'
print(humanize.intword(123455913))   # 输出: '123.5 million'
print(humanize.intword(12345591313)) # 输出: '12.3 billion'
print(humanize.apnumber(4))          # 输出: 'four'
print(humanize.apnumber(41))         # 输出: '41'

日期和时间人性化

import datetime as dt

print(humanize.naturalday(dt.datetime.now()))           # 输出: 'today'
print(humanize.naturaldelta(dt.timedelta(seconds=1001))) # 输出: '16 minutes'
print(humanize.naturalday(dt.datetime.now() - dt.timedelta(days=1))) # 输出: 'yesterday'
print(humanize.naturalday(dt.date(2007, 6, 5)))         # 输出: 'Jun 05'
print(humanize.naturaldate(dt.date(2007, 6, 5)))        # 输出: 'Jun 05 2007'
print(humanize.naturaltime(dt.datetime.now() - dt.timedelta(seconds=1))) # 输出: 'a second ago'
print(humanize.naturaltime(dt.datetime.now() - dt.timedelta(seconds=3600))) # 输出: 'an hour ago'

精确时间差

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

文件大小人性化

print(humanize.naturalsize(1_000_000))          # 输出: '1.0 MB'
print(humanize.naturalsize(1_000_000, binary=True)) # 输出: '976.6 KiB'
print(humanize.naturalsize(1_000_000, gnu=True)) # 输出: '976.6K'

可读的浮点数

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

科学记数法

print(humanize.scientific(0.3))        # 输出: '3.00 x 10⁻¹'
print(humanize.scientific(500))        # 输出: '5.00 x 10²'
print(humanize.scientific("20000"))    # 输出: '2.00 x 10⁴'
print(humanize.scientific(1**10))      # 输出: '1.00 x 10⁰'
print(humanize.scientific(1**10, precision=1)) # 输出: '1.0 x 10⁰'
print(humanize.scientific(1**10, precision=0)) # 输出: '1 x 10⁰'

3. 项目API使用文档

Humanize 的 API 文档可以在其官方文档网站查看，以下是部分 API 的简要说明：

• intcomma(number): 将数字转换为带有逗号的字符串。
• intword(number): 将数字转换为更易读的单词形式。
• apnumber(number): 将数字转换为其对应的英文单词，如果是大于 1 的数字则直接返回数字。
• naturalday(date): 返回一个相对于当前日期的人类可读的字符串。
• naturaldelta(timedelta): 将时间差转换为人类可读的字符串。
• precisedelta(timedelta, minimum_unit=None, suppress=None, format=None): 返回一个精确的时间差，可以指定最小单位和是否显示某些时间单位。
• naturalsize(size, binary=False, gnu=False): 将文件大小转换为人类可读的字符串。
• fractional(value): 将浮点数转换为分数形式的字符串。
• scientific(value, precision=2): 将数字转换为科学记数法形式的字符串。

4. 项目安装方式

Humanize 支持两种安装方式：从 PyPI 安装和从源代码安装。具体的安装步骤请参考本文档的“安装指南”部分。