Python 标准库提供 datetime、zoneinfo 和 time 等模块,用于日期计算、字符串解析、时间戳转换和时区处理。本文从基础对象讲到实际项目中最容易出错的时区问题。
一、datetime 模块的主要类型
| 类型 | 用途 | 示例 |
|---|---|---|
date | 只表示年月日 | 2026-11-13 |
time | 只表示时分秒和微秒 | 20:30:15 |
datetime | 同时表示日期和时间 | 2026-11-13 20:30:15 |
timedelta | 表示时间间隔 | 3 天 2 小时 |
timezone | 表示固定 UTC 偏移 | UTC+08:00 |
ZoneInfo | 使用 IANA 时区规则 | Asia/Shanghai |
二、获取当前日期和时间
from datetime import date, datetime, timezone print(date.today()) print(datetime.now()) # 当前系统本地时间,无时区信息 print(datetime.now(timezone.utc)) # 当前 UTC 时间,带时区信息
datetime.now() 返回的是 naive datetime,即对象本身不说明属于哪个时区。跨系统、接口和数据库传递时间时,建议使用带时区信息的 aware datetime。
三、创建日期时间对象
from datetime import date, datetime, time birthday = date(1995, 8, 20) meeting_time = time(14, 30, 0) meeting = datetime(2026, 11, 20, 14, 30, 0) print(birthday.year, birthday.month, birthday.day) print(meeting.hour, meeting.minute, meeting.second)
日期参数不合法会抛出 ValueError,例如 2 月 30 日。
四、日期时间格式化:strftime
strftime() 把日期时间对象转换为字符串:
from datetime import datetime
now = datetime.now()
print(now.strftime("%Y-%m-%d %H:%M:%S"))
print(now.strftime("%Y年%m月%d日"))
print(now.strftime("%H:%M"))
常用格式代码:
| 代码 | 含义 | 示例 |
|---|---|---|
%Y | 四位年份 | 2026 |
%m | 两位月份 | 11 |
%d | 两位日期 | 13 |
%H | 24 小时制小时 | 20 |
%M | 分钟 | 30 |
%S | 秒 | 15 |
%f | 微秒 | 123456 |
%z | UTC 偏移 | +0800 |
%Z | 时区名称 | CST |
五、解析字符串:strptime
strptime() 根据指定格式把字符串转换为 datetime:
from datetime import datetime text = "2026-11-13 20:30:15" value = datetime.strptime(text, "%Y-%m-%d %H:%M:%S") print(value) print(type(value))
字符串和格式不匹配时会抛出 ValueError,可以明确处理:
from datetime import datetime
def parse_date(text: str) -> datetime:
try:
return datetime.strptime(text, "%Y-%m-%d")
except ValueError as exc:
raise ValueError("日期必须使用 YYYY-MM-DD 格式") from exc
六、ISO 8601 格式
系统间交换时间时,优先使用 ISO 8601,而不是自定义格式:
from datetime import datetime, timezone now = datetime.now(timezone.utc) text = now.isoformat() restored = datetime.fromisoformat(text) print(text) print(restored) print(restored.tzinfo)
UTC 时间常写成以 Z 结尾的形式。兼容不同 Python 版本和外部接口时,应先确认解析器是否接受 Z,以及接口对微秒的要求。
七、日期加减:timedelta
from datetime import datetime, timedelta now = datetime.now() three_days_later = now + timedelta(days=3) two_hours_ago = now - timedelta(hours=2) expires_at = now + timedelta(minutes=30) print(three_days_later) print(two_hours_ago) print(expires_at)
timedelta 支持 weeks、days、hours、minutes、seconds、milliseconds 和 microseconds,但不支持“月”和“年”,因为每月天数和闰年并不固定。
八、计算两个日期的差值
from datetime import datetime
start = datetime.strptime("2026-11-01 09:00:00", "%Y-%m-%d %H:%M:%S")
end = datetime.strptime("2026-11-13 18:30:00", "%Y-%m-%d %H:%M:%S")
delta = end - start
print(delta.days)
print(delta.seconds)
print(delta.total_seconds())
print(delta.total_seconds() / 3600)
delta.seconds只表示不足一天部分的秒数,不是完整时间差。需要总秒数时应使用total_seconds()。
九、日期比较与排序
from datetime import datetime
start = datetime(2026, 11, 13, 9, 0)
end = datetime(2026, 11, 13, 18, 0)
if start < end:
print("开始时间早于结束时间")
values = [end, start]
print(sorted(values))
不要直接比较 naive datetime 和 aware datetime,它们的语义不同。参与比较的对象应使用一致的时区策略。
十、时间戳转换
Unix 时间戳表示从 1970-01-01 00:00:00 UTC 起经过的秒数。
from datetime import datetime, timezone now = datetime.now(timezone.utc) timestamp = now.timestamp() restored_utc = datetime.fromtimestamp(timestamp, tz=timezone.utc) restored_local = datetime.fromtimestamp(timestamp) print(timestamp) print(restored_utc) print(restored_local)
如果省略 tz,fromtimestamp() 使用系统本地时区。服务器与开发机时区不同时,结果可能看起来不一致,因此关键转换应显式指定时区。
十一、naive 与 aware datetime
from datetime import datetime, timezone naive = datetime.now() aware = datetime.now(timezone.utc) print(naive.tzinfo) # None print(aware.tzinfo) # UTC
- naive:没有时区信息,无法唯一对应全球时间线上的一个时刻。
- aware:包含 UTC 偏移或时区规则,可以明确表示一个时刻。
数据库和 API 的常见策略是:内部统一保存 UTC,需要展示时再转换为用户所在时区。
十二、使用 zoneinfo 处理真实时区
Python 3.9 起可使用标准库 zoneinfo。它支持夏令时和历史时区规则,比手写固定偏移更可靠。
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
shanghai = ZoneInfo("Asia/Shanghai")
new_york = ZoneInfo("America/New_York")
now_utc = datetime.now(timezone.utc)
now_shanghai = now_utc.astimezone(shanghai)
now_new_york = now_utc.astimezone(new_york)
print(now_utc.isoformat())
print(now_shanghai.isoformat())
print(now_new_york.isoformat())
Windows 等部分环境可能没有系统 IANA 时区数据库。跨平台项目可以声明官方维护的数据包:
python -m pip install tzdata
固定偏移与真实时区的区别
from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo
fixed_utc8 = timezone(timedelta(hours=8))
shanghai = ZoneInfo("Asia/Shanghai")
print(datetime.now(fixed_utc8))
print(datetime.now(shanghai))
固定 UTC+8 不包含地区历史规则。对用户地区、跨国日程和夏令时场景,应使用 IANA 名称,如 Asia/Shanghai,不要只保存 “CST” 这类含义不唯一的缩写。
十三、正确转换时区
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
utc_value = datetime(2026, 11, 13, 12, 0, tzinfo=timezone.utc)
shanghai_value = utc_value.astimezone(ZoneInfo("Asia/Shanghai"))
print(shanghai_value)
astimezone() 会转换时刻并调整显示时间。replace(tzinfo=...) 只是替换时区标签,不会换算时刻,不应把它当作时区转换:
from datetime import datetime
from zoneinfo import ZoneInfo
# 已知这个墙上时间本来就属于上海时区时,才可以附加时区
local_value = datetime(2026, 11, 13, 20, 0)
shanghai_value = local_value.replace(tzinfo=ZoneInfo("Asia/Shanghai"))
# 转换到纽约使用 astimezone
new_york_value = shanghai_value.astimezone(ZoneInfo("America/New_York"))
十四、数据库与接口中的时间
推荐策略
- 系统内部尽量使用 UTC aware datetime。
- 接口传输使用带偏移的 ISO 8601 字符串。
- 数据库字段类型和驱动行为要明确测试,不要假设它会自动处理时区。
- 如果保存用户预约的“当地时间”,同时保存 IANA 时区名称。
- 展示时再转换为用户时区。
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
# 写入前统一成 UTC
user_time = datetime(2026, 11, 13, 20, 0, tzinfo=ZoneInfo("Asia/Shanghai"))
stored_time = user_time.astimezone(timezone.utc)
# 展示时转换回来
shown_time = stored_time.astimezone(ZoneInfo("Asia/Shanghai"))
十五、测量程序耗时
测量持续时间不应使用 datetime.now(),因为系统时钟可能被校准。应使用单调时钟:
from time import perf_counter
start = perf_counter()
run_task()
elapsed = perf_counter() - start
print(f"耗时:{elapsed:.3f} 秒")
perf_counter() 适合性能计时,但它的返回值本身不表示真实日期。
十六、常见错误
- 把无时区 datetime 当作 UTC,又在另一台机器上按本地时间解析。
- 使用固定小时数处理会实行夏令时的地区。
- 用
replace(tzinfo=...)代替astimezone()做时区转换。 - 用
timedelta(days=30)表示一个自然月。 - 用
delta.seconds当作完整秒数。 - 只保存 CST、EST 等可能存在歧义的时区缩写。
- 依赖操作系统本地时区,使开发、测试和生产结果不同。
- 用墙上时间测量代码性能。
十七、实用工具函数
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
def utc_now() -> datetime:
"""返回带时区信息的当前 UTC 时间。"""
return datetime.now(timezone.utc)
def to_iso8601(value: datetime) -> str:
"""把 aware datetime 转成 ISO 8601 字符串。"""
if value.tzinfo is None or value.utcoffset() is None:
raise ValueError("value 必须包含时区信息")
return value.isoformat()
def display_in_timezone(value: datetime, zone_name: str) -> str:
"""把 aware datetime 转换到指定时区后显示。"""
if value.tzinfo is None or value.utcoffset() is None:
raise ValueError("value 必须包含时区信息")
local_value = value.astimezone(ZoneInfo(zone_name))
return local_value.strftime("%Y-%m-%d %H:%M:%S %Z")
更多内容可参考 Python datetime 官方文档和 Python zoneinfo 官方文档。