技术 · 思考 · 实践 · 成长

首页/Python专栏/正文

Python 日期与时间详解:datetime、时间戳与时区处理

Python专栏388 次阅读

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
%H24 小时制小时20
%M分钟30
%S秒15
%f微秒123456
%zUTC 偏移+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 官方文档。

所有的努力,不是为了让别人觉得你了不起,而是为了能让自己打心眼里看得起自己。

评论交流

0 条评论 · 支持多级回复
验证码
暂无评论,来说说你的想法吧

相关文章

继续阅读