如何使用 datetime 模块处理日期时间？datetime 模块介绍

阅读 17:40·字数 5303·更新 2024-4-12

本节内容不涉及 Python 日期时间与字符串之间的转换，日期时间的格式化以及时区，要了解他们，你可以查看内容分类一段列出的章节。

datetime 模块

Python 的datetime模块拥有多个类，比如datetime，date，time，他们提供了与日期时间相关的功能，可完成绝大部分的日期时间操作。其中，类datetime继承自类date。

datetime 模块所允许的最小和最大日期时间

datetime模块的两个变量MINYEAR和MAXYEAR，分别表示所允许的最小年份和最大年份，其中MINYEAR为1，MAXYEAR为9999。

date类的类变量min和max，分别表示所允许的最小日期和最大日期，其中min等价于表达式date(MINYEAR,1,1)运算得到的date对象，max等价于表达式date(MAXYEAR,12,31)运算得到的date对象。

time类的类变量min和max，分别表示所允许的最小时间和最大时间，其中min等价于表达式time(0,0,0,0)运算得到的time对象，max等价于表达式time(23,59,59,999999)运算得到的time对象。

datetime类的类变量min和max，分别表示所允许的最小日期时间和最大日期时间，其中min等价于表达式datetime(MINYEAR,1,1,tzinfo=None)运算得到的datetime对象，max等价于表达式datetime(MAXYEAR,12,31,23,59,59,999999,tzinfo=None)运算得到的datetime对象。

date|time|datetime.min date|time|datetime.max

import datetime
# 最小年份
datetime.MINYEAR
1
# 最大年份
datetime.MAXYEAR
9999
# 最小日期
datetime.date.min
datetime.date(1, 1, 1)
# 最大日期
datetime.date.max
datetime.date(9999, 12, 31)
# 最小时间
datetime.time.min
datetime.time(0, 0)
# 最大时间
datetime.time.max
datetime.time(23, 59, 59, 999999)
# 最小日期时间
datetime.datetime.min
datetime.datetime(1, 1, 1, 0, 0)
# 最大日期时间
datetime.date.max
datetime.datetime(9999, 12, 31, 23, 59, 59, 999999)

datetime 模块的 date 类

date类用于表示一个日期，该日期包含了年，月和日的信息，其构造器的形式如下。如果传递给构造器的参数不能正确的表示一个日期，那么构造器将抛出异常ValueError。

date(year, month, day)

year 参数: year参数表示年份，其值需要大于或等于datetime模块的MINYEAR变量，并小于或等于datetime模块的MAXYEAR变量。
month 参数: month参数表示月份，其值需要大于或等于1，并小于或等于12。
day 参数: day参数表示datetime对象对应的日期是月份中的第几天，其值需要大于或等于1，并小于或等于月份允许的最大天数。

from datetime import date
# 创建 date 对象
date(9999, 1, 1)
datetime.date(9999, 1, 1)
# day 参数不正确
date(9999, 1, 100)
…
ValueError: day is out of range for month

datetime 模块的 time 类

time类用于表示一天中的某个特定时间，该时间包含了小时，分，秒，微秒等信息，其构造器的形式如下。如果传递给构造器的参数不能正确的表示一个时间，那么构造器将抛出异常ValueError。

time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

hour 参数: hour参数表示时间的小时部分，其值需要大于或等于0，并小于24。
minute 参数: minute参数表示时间的分钟部分，其值需要大于或等于0，并小于60。
second 参数: second参数表示时间的秒数部分，其值需要大于或等于0，并小于60。
microsecond 参数: microsecond参数表示时间的微秒部分，其值需要大于或等于0，并小于1000000。
tzinfo 参数: tzinfo参数为时间对应的时区对象。
fold 参数: fold参数用于消除歧义，其取值可以是0或1。如果参数tzinfo所指定的时区对象未在其相关方法中使用参数fold，那么fold的取值是无关紧要的。

from datetime import time
# 创建 time 对象
time(8, 59, 0, 123456)
datetime.time(8, 59, 0, 123456)
# second 参数不正确
time(15, 0, 60)
…
ValueError: second must be in 0..59

datetime 模块的 datetime 类

datetime类用于表示一个特定的日期时间，该日期时间包含了年，月，日，小时，分，秒，微秒等信息，其构造器的形式如下，构造器的参数的含义与date，time类的构造器相同。如果传递给构造器的参数不能正确的表示一个日期时间，那么构造器将抛出异常ValueError。

datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

from datetime import datetime
# 创建 datetime 对象
datetime(2024, 12, 30)
datetime.datetime(2024, 12, 30, 0, 0)

获取日期时间信息

date，time和datetime对象具有以下只读属性，可用于获取与日期时间相关的信息。其中，year属性表示年份，month属性表示月份（1至12），day属性表示一月中的第几天，hour属性表示小时（0至23），minute属性表示分钟（0至59），second属性表示秒数（0至59），microsecond属性表示微秒数（0至999999），tzinfo属性是表示时区信息的tzinfo对象，fold属性的取值为0或1，表示如何消除歧义。

datetime对象的date方法，可用于获取日期时间对应的日期，其返回值是一个新的date对象，拥有与原datetime对象相同的year，month以及day属性。

datetime对象的timetz方法，可用于获取日期时间对应的时间，其返回值是一个新的time对象，拥有与原datetime对象相同的hour，minute，second，microsecond，tzinfo以及fold（需要 Python 3.6 或更高版本）属性。datetime对象的time方法与timetz方法类似，只不过其返回的time对象的tzinfo属性为空值None。

datetime.date() datetime.timetz() datetime.time()

date和datetime对象的timetuple方法，其返回值是time模块的struct_time对象，该对象包含了一些与日期时间相关的属性。

date|datetime.timetuple()

from datetime import date, time, datetime, timezone
# 获取年份
date(2024, 1, 1).year
2024
# 获取微秒数
datetime.today().microsecond
573657
# 获取秒数
time(1, 30, 59).second
59
dt = datetime(2024, 9, 25, 8, 30, 0, 1234, timezone.utc, fold=1)
# 获取日期时间中的时间，不带时区
dt.time()
datetime.time(8, 30, 0, 1234, fold=1)
# 获取日期时间中的时间，带时区
dt.timetz()
datetime.time(8, 30, 0, 1234, tzinfo=datetime.timezone.utc, fold=1)
# 获取 struct_time
dt.timetuple()
time.struct_time(tm_year=2024, tm_mon=9, tm_mday=25, tm_hour=8, tm_min=30, tm_sec=0, tm_wday=2, tm_yday=269, tm_isdst=-1)

修改日期时间

date，time和datetime对象的replace方法会使用原有对象来创建新的对象，并根据给出的参数来替换原有的日期时间信息，其参数含义与相关类的构造器的参数含义相同。

date.replace(year=self.year, month=self.month, day=self.day) time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold) datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold)

你无法修改 date，time，datetime 对象所表示的日期时间

你无法通过date，time和datetime对象的相关属性来修改日期时间，这些属性是只读的，比如year属性。Python 的设计者并不希望日期时间被改动，即便通过date，time和datetime对象的replace方法，因为该方法会返回一个新的对象。

时区

如果你希望将datetime对象转换为某个时区对应的日期时间而不是简单的替换时区信息，那么可以查看为日期时间转换时区一段。

from datetime import date, time, datetime
# 根据原有日期时间创建新的日期时间
date(2024, 1, 1).replace(2023)
datetime.date(2023, 1, 1)
time(23, 59, 59, 1234).replace(microsecond=4321)
datetime.time(23, 59, 59, 4321)
datetime(2024, 1, 1, 23, 59, 59, fold=1).replace(month=3)
datetime.datetime(2024, 3, 1, 23, 59, 59, fold=1)

获取日期时间的 POSIX 时间戳

datetime对象的方法timestamp，可用于获取datetime对象所表示的日期时间的 POSIX 时间戳，该方法的返回值是一个浮点数。

datetime.timestamp()

Python 中的 POSIX 时间戳

POSIX 时间戳是一个数值，他表示某个日期时间与协调世界日期时间（UTC） 1970 年 1 月 1 日 0 时 0 分 0 秒之间的差值。在 Python 中，POSIX 时间戳被表示为浮点数，浮点数的整数部分对应了秒数，浮点数的小数部分对应了微秒。

from datetime import datetime
# 获取本地日期时间的时间戳
datetime.today().timestamp()
1727179679.344979

获取 POSIX 时间戳对应的日期时间

date类的类方法fromtimestamp，可用于获取某个 POSIX 时间戳对应的日期（不包含时间信息），该方法的返回值是一个date对象。

date.fromtimestamp(timestamp)

timestamp 参数: timestamp参数为表示 POSIX 时间戳的浮点数。

datetime类的类方法fromtimestamp，可用于获取某个 POSIX 时间戳对应的日期时间，该方法的返回值是一个datetime对象。

datetime.fromtimestamp(timestamp, tz=None)

timestamp 参数: timestamp参数为表示 POSIX 时间戳的浮点数。
tz 参数: tz参数为表示时区信息的tzinfo对象，方法会将 POSIX 时间戳转换为对应时区的日期时间并返回。如果忽略该参数或将该参数设置为None，则直接返回当前的本地日期时间。

在 Python 3.12 和之后的版本中，datetime类的类方法utcfromtimestamp已经被弃用，他可用于获取 POSIX 时间戳对应的协调世界日期时间（UTC）。

datetime 模块不能转换所有的 POSIX 时间戳

datetime模块不能将所有 POSIX 时间戳转换为日期时间，比如，时间戳对应的浮点数太大，将小于0的时间戳转换为小于 1970 年 1 月 1 日 0 时 0 分 0 秒的协调世界日期时间（可以转换时间戳0）。如果时间戳转换失败，那么可能会抛出异常OSError。

from datetime import date, datetime, timezone
# 将时间戳转换为日期
date.fromtimestamp(1727246240.124616)
datetime.date(2024, 9, 25)
# 将时间戳转换为日期时间
datetime.fromtimestamp(1727246240.124616)
datetime.datetime(2024, 9, 25, 14, 37, 20, 124616)
datetime.fromtimestamp(1727246240.124616, timezone.utc)
datetime.datetime(2024, 9, 25, 6, 37, 20, 124616, tzinfo=datetime.timezone.utc)
# 时间戳不能小于 0
date.fromtimestamp(-1)
…
OSError: [Errno …] Invalid argument

获取当前的日期时间

date类的类方法today，可用于获取当前的本地日期（不包含时间信息），该方法的返回值是一个date对象。

date.today()

datetime类的类方法today和now，可用于获取当前的本地日期时间或其在指定时区对应的日期时间，该方法的返回值是一个datetime对象。

datetime.today() datetime.now(tz=None)

tz 参数: tz参数为表示时区信息的tzinfo对象，方法会将当前的本地日期时间转换为对应时区的日期时间并返回。如果忽略该参数或将该参数设置为None，则直接返回当前的本地日期时间。

在 Python 3.12 和之后的版本中，datetime类的类方法utcnow已经被弃用，他可用于获取当前的协调世界日期时间（UTC）。

from datetime import date, datetime, timezone
# 获取当前的本地日期
date.today()
datetime.date(2024, 9, 24)
# 获取当前的本地日期时间
datetime.today()
datetime.datetime(2024, 9, 24, 20, 53, 38, 244890)
datetime.now()
datetime.datetime(2024, 9, 24, 20, 54, 9, 974196)
# 获取当前的本地日期时间对应的 UTC 日期时间
datetime.now(timezone.utc)
datetime.datetime(2024, 9, 24, 12, 54, 51, 164800)

获取日期时间是一周中的第几天

date和datetime对象的方法weekday，其返回值是一个整数，该整数表示日期时间是一周中的第几天，即星期几（0表示星期一，6表示星期日）。

date和datetime对象的方法isoweekday与方法weekday类似，只不过返回1表示星期一而不是星期二（7表示星期日）。

date|datetime.weekday() date|datetime.isoweekday()

from datetime import date, datetime
# 获取星期几
date(2024, 9, 25).weekday()
2
datetime(2024, 9, 25, 23, 59, 59).isoweekday()
3

获取日期时间的日历信息

date和datetime对象的方法isocalendar，其返回值是一个具名元组（可通过元组变量来访问元组中的元素），该元组包含变量year，week，weekday，他们分别表示日期时间的年份，是一年中的第几周（1表示第一周），是一周中的第几天（1表示星期一）。

date|datetime.isocalendar()

from datetime import date, datetime
# 获取日历信息
date(2024, 9, 25).isocalendar()
datetime.IsoCalendarDate(year=2024, week=39, weekday=3)
datetime(2024, 9, 25, 23, 59, 59).isocalendar()
datetime.IsoCalendarDate(year=2024, week=39, weekday=3)

获取日历信息对应的日期时间

date和datetime类的类方法fromisocalendar（需要 Python 3.8 或更高版本），将根据给出的日历信息，返回其对应的日期（date对象）或日期时间（datetime对象）。

date|datetime.fromisocalendar(year, week, day)

year 参数: year参数表示年份，最终得到的日期或日期时间的年份可能与year参数不同。
week 参数: week参数表示日期时间是一年中的第几周（1表示第一周）。
day 参数: day参数表示日期时间是一周中的第几天（1表示星期一）。

from datetime import date, datetime
# 获取日历信息对应的日期
date.fromisocalendar(2024, 39, 3)
datetime.date(2024, 9, 25)
# 获取日历信息对应的日期时间
datetime.fromisocalendar(2024, 39, 3)
datetime.datetime(2024, 9, 25, 0, 0)

获取日期，时间，时区对应的日期时间

datetime类的类方法combine，可根据已有的日期（date对象），时间（time对象）以及时区信息创建新的日期时间（datetime对象）。

datetime.combine(date, time, tzinfo=time.tzinfo)

date 参数: date参数为用来创建日期时间的date对象。
time 参数: time参数为用来创建日期时间的time对象。
tzinfo 参数: tzinfo参数为用来创建日期时间的时区信息对象，如果忽略该参数，则将采用time参数的tzinfo属性。

from datetime import date, time, datetime, timezone
# 根据日期，时间，时区创建日期时间
datetime.combine(date(2024, 9, 25), time(0, 0, 0, tzinfo=timezone.utc))
datetime.datetime(2024, 9, 25, 0, 0, tzinfo=datetime.timezone.utc)
datetime.combine(date(2024, 9, 25), time(0, 0, 0, tzinfo=timezone.utc), None)
datetime.datetime(2024, 9, 25, 0, 0)

获取日期时间在公元纪年法中的序号

date和datetime对象的方法toordinal，其返回值是一个整数，可用于获取日期时间在公元纪年法中的序号（公元 1 年 1 月 1 日对应的序号为1，以此类推）。

date|datetime.toordinal()

from datetime import date, datetime
# 2024 年 9 月 25 日在公元纪年法中的序号
date(2024, 9, 25).toordinal()
739154
# 2024 年 9 月 25 日 23 时 59 分 59 秒在公元纪年法中的序号
datetime(2024, 9, 25, 23, 59, 59).toordinal()
739154

获取公元纪年序号对应的日期时间

date和datetime类的类方法fromordinal，可用于获取公元纪年序号（1对应公元 1 年 1 月 1 日，以此类推）对应的日期时间，其返回值是一个date或datetime对象。如果返回值是datetime对象，那么其表示的时，分，秒，微秒均为0，其属性tzinfo为None。

date|datetime.fromordinal(ordinal)

ordinal 参数: ordinal参数为表示公元纪年序号的整数，该值不能小于1或大于表达式datetime.max.toordinal()的计算结果，否则可能会引发异常ValueError。

from datetime import date, datetime
# 获取公元纪年法序号 1 对应的日期
date.fromordinal(1)
datetime.date(1, 1, 1)
# 获取公元纪年法序号 2 对应的日期时间
datetime.fromordinal(2)
datetime.datetime(1, 1, 2, 0, 0)
# 序号不能小于 1
datetime.fromordinal(0)
…
ValueError: ordinal must be >= 1