microsecond 是 Python 中处理日期和时间时一个非常常见和重要的概念，它代表“微秒”，即百万分之一秒（1/1,000,000 秒）。

主要在哪些地方出现？

microsecond 主要与 Python 的 datetime 模块相关,具体体现在以下几个核心类中：

• datetime.datetime
• datetime.time
• datetime.timedelta

datetime 对象中的 microsecond

这是最常见的情况，当你创建一个 datetime 对象时,可以为其指定微秒部分。

a) 创建时指定

在构造 datetime 对象时，microsecond 是最后一个可选参数。

import datetime
# 创建一个包含微秒的 datetime 对象
# 格式: datetime(year, month, day, hour, minute, second, microsecond)
dt_with_micro = datetime.datetime(2025, 10, 26, 10, 30, 45, 123456)
print(dt_with_micro)
# 输出: 2025-10-26 10:30:45.123456
# 微秒部分会自动显示在秒后面，用点号隔开

b) 作为属性访问

每个 datetime 对象都有一个 .microsecond 属性,用于获取或设置微秒值。

import datetime
dt = datetime.datetime(2025, 10, 26, 10, 30, 45, 123456)
# 获取微秒
microseconds = dt.microsecond
print(f"微秒值是: {microseconds}")
# 输出: 微秒值是: 123456
# 设置微秒 (注意：这会返回一个新的对象，原对象不变)
# 注意：微秒值的范围是 0 到 999999
dt_new_micro = dt.replace(microsecond=999999)
print(f"设置后的新对象: {dt_new_micro}")
# 输出: 设置后的新对象: 2025-10-26 10:30:45.999999

c) 从字符串解析

如果你有一个包含微秒的日期时间字符串，可以使用 strptime 将其解析为 datetime 对象。

import datetime
date_string = "2025-10-26 10:30:45.123456"
# 格式说明符:
# %Y - 年
# %m - 月
# %d - 日
# %H - 时 (24小时制)
# %M - 分
# %S - 秒
# %f - 微秒 (6位数)
dt_from_str = datetime.datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S.%f")
print(f"从字符串解析出的对象: {dt_from_str}")
print(f"其微秒部分: {dt_from_str.microsecond}")
# 输出:
# 从字符串解析出的对象: 2025-10-26 10:30:45.123456
# 其微秒部分: 123456

d) 格式化输出

使用 strftime 方法，你可以将 datetime 对象格式化为字符串,并选择是否包含微秒。

import datetime
dt = datetime.datetime(2025, 10, 26, 10, 30, 45, 123456)
# 不包含微秒
print(dt.strftime("%Y-%m-%d %H:%M:%S"))
# 输出: 2025-10-26 10:30:45
# 包含微秒
print(dt.strftime("%Y-%m-%d %H:%M:%S.%f"))
# 输出: 2025-10-26 10:30:45.123456

time 对象中的 microsecond

time 类表示一天中的时间,同样也支持微秒。

import datetime
# 创建一个包含微秒的 time 对象
t_with_micro = datetime.time(15, 30, 45, 987654)
print(t_with_micro)
# 输出: 15:30:45.987654
# 访问微秒属性
print(t_with_micro.microsecond)
# 输出: 987654

timedelta 对象中的 microsecond

timedelta 用于表示时间差（两个时间点之间的间隔）,它也可以精确到微秒级别。

import datetime
# 创建一个间隔为 1 微秒的 timedelta
one_microsecond = datetime.timedelta(microseconds=1)
print(one_microsecond)
# 输出: 0:00:00.000001
# 创建一个间隔为 1500 微秒的 timedelta
# Python 会自动进行进位：1500 微秒 = 1 毫秒 + 500 微秒
one_point_five_ms = datetime.timedelta(microseconds=1500)
print(one_point_five_ms)
# 输出: 0:00:00.001500
# 在计算中使用
dt1 = datetime.datetime(2025, 1, 1, 0, 0, 0, 0)
dt2 = datetime.datetime(2025, 1, 1, 0, 0, 0, 500000)
time_difference = dt2 - dt1
print(f"时间差: {time_difference}")
print(f"时间差的微秒数: {time_difference.total_seconds() * 1_000_000}")
# 输出:
# 时间差: 0:00:00.500000
# 时间差的微秒数: 500000.0

重要注意事项

a) 取值范围

microsecond 的取值范围是 0 到 999999（包含），如果你尝试设置一个超出范围的值，Python 会抛出 ValueError。

import datetime
dt = datetime.datetime.now()
# 正确
dt_ok = dt.replace(microsecond=999999)
print(dt_ok)
# 错误
try:
    dt_bad = dt.replace(microsecond=1000000) # 超出范围
except ValueError as e:
    print(f"错误: {e}")
# 输出: 错误: microsecond must be in 0..999999

b) 进位处理

当你设置 microsecond 时，如果它超出了范围，Python 不会自动为你进位，你必须手动处理。1,000,000 微秒等于 1 秒，你需要手动将秒加 1，并将微秒设为 0。

import datetime
dt = datetime.datetime(2025, 1, 1, 0, 0, 0, 999999)
print(f"修改前: {dt}")
# 手动进位
# dt.microsecond + 1 = 1,000,000
# 秒加 1，微秒归零
dt_new = dt.replace(second=dt.second + 1, microsecond=0)
print(f"手动进位后: {dt_new}")
# 输出:
# 修改前: 2025-01-01 00:00:00.999999
# 手动进位后: 2025-01-01 00:00:01

c) 高精度计算

由于 Python 的 float 类型在存储非常大或非常小的数字时可能会有精度损失，在进行涉及微秒的精确计算时，推荐使用整数运算,而不是将总秒数转换为浮点数。

# 推荐做法：使用整数
delta = datetime.timedelta(microseconds=123456)
total_microseconds_int = delta.days * 24 * 3600 * 1_000_000 + delta.seconds * 1_000_000 + delta.microseconds
print(f"总微秒数 (整数): {total_microseconds_int}")
# 不推荐做法：可能引入浮点误差
total_seconds_float = delta.total_seconds()
total_microseconds_float = total_seconds_float * 1_000_000
print(f"总微秒数 (浮点): {total_microseconds_float}")
# 在大多数情况下结果相同，但对于极端高精度需求，整数更安全。

掌握 microsecond 的用法，是进行精确时间计算、日志分析、性能测量等任务的基础。