目录
对象
date 对象代表一个理想化历法中的日期(年、月和日),即当今的格列高利历向前后两个方向无限延伸。
公元 1 年 1 月 1日是第 1 日,公元 1 年 1 月 2 日是第 2 日,依此类推。 2
class datetime.date(year, month, day)
所有参数都是必要的。 参数必须是在下面范围内的整数:
-
MINYEAR <= year <= MAXYEAR
-
1 <= month <= 12
-
1 <= 日期 <= 给定年月对应的天数
如果参数不在这些范围内,则抛出 ValueError 异常。
其它构造器,所有的类方法:
classmethod date.today()
返回当前的本地日期。
这等价于 date.fromtimestamp(time.time())
。
classmethod date.fromtimestamp(timestamp)
返回对应于 POSIX 时间戳的当地时间,例如 time.time() 返回的就是时间戳。
这可能引发 OverflowError,如果时间戳数值超出所在平台 C localtime()
函数的支持范围的话,并且会在 localtime()
出错时引发 OSError。 通常该数值会被限制在 1970 年至 2038 年之间。 请注意在时间戳概念包含闰秒的非 POSIX 系统上,闰秒会被 fromtimestamp() 所忽略。
在 3.3 版更改: 引发 OverflowError 而不是 ValueError,如果时间戳数值超出所在平台 C localtime()
函数的支持范围的话,并会在 localtime()
出错时引发 OSError 而不是 ValueError。
classmethod date.fromordinal(ordinal)
返回对应于预期格列高利历序号的日期,其中公元 1 年 1 月 1 日的序号为 1。
除非 1 <= ordinal <= date.max.toordinal()
否则会引发 ValueError。对于任意日期 d,date.fromordinal(d.toordinal()) == d
。
classmethod date.fromisoformat(date_string)
Return a date corresponding to a date_string given in any valid ISO 8601 format, except ordinal dates (e.g. YYYY-DDD
):
>>>
>>> from datetime import date >>> date.fromisoformat('2019-12-04') datetime.date(2019, 12, 4) >>> date.fromisoformat('20191204') datetime.date(2019, 12, 4) >>> date.fromisoformat('2021-W01-1') datetime.date(2021, 1, 4)
3.7 新版功能.
在 3.11 版更改: Previously, this method only supported the format YYYY-MM-DD
.
classmethod date.fromisocalendar(year, week, day)
返回指定 year, week 和 day 所对应 ISO 历法日期的 date。 这是函数 date.isocalendar() 的逆操作。
3.8 新版功能.
类属性:
date.min
最小的日期 date(MINYEAR, 1, 1)
。
date.max
最大的日期 ,date(MAXYEAR, 12, 31)
。
date.resolution
两个日期对象的最小间隔,timedelta(days=1)
。
实例属性(只读):
date.year
date.month
1 至 12(含)
date.day
返回1到指定年月的天数间的数字。
支持的运算:
运算 | 结果: |
---|---|
| date2 will be |
| 计算 date2 的值使得 |
| (3) |
| 如果 date1 的时间在 date2 之前则认为 date1 小于 date2 。 (4) |
注释:
-
如果
timedelta.days > 0
则 date2 将在时间线上前进,如果timedelta.days < 0
则将后退。 操作完成后date2 - date1 == timedelta.days
。timedelta.seconds
和timedelta.microseconds
会被忽略。 如果date2.year
将小于 MINYEAR 或大于 MAXYEAR 则会引发 OverflowError。 -
timedelta.seconds
和timedelta.microseconds
会被忽略。 -
此值完全精确且不会溢出。 操作完成后 timedelta.seconds 和 timedelta.microseconds 均为 0,并且 date2 + timedelta == date1。
-
换句话说,当且仅当
date1.toordinal() < date2.toordinal()
时date1 < date2
。 日期比较会引发 TypeError,如果比较目标不为 date 对象的话。 不过也可能会返回NotImplemented
,如果比较目标具有timetuple()
属性的话。 这个钩子给予其他日期对象类型实现混合类型比较的机会。 否则,当 date 对象与不同类型的对象比较时将会引发 TypeError,除非是==
或!=
比较。 后两种情况将分别返回 False 或 True。
在布尔运算中,所有 date 对象都会被视为真值。
实例方法:
date.replace(year=self.year, month=self.month, day=self.day)
返回一个具有同样值的日期,除非通过任何关键字参数给出了某些形参的新值。
示例:
>>>
>>> from datetime import date >>> d = date(2002, 12, 31) >>> d.replace(day=26) datetime.date(2002, 12, 26)
date.timetuple()
返回一个 time.struct_time,即 time.localtime() 所返回的类型。
hours, minutes 和 seconds 值均为 0,且 DST 旗标值为 -1。
d.timetuple()
等价于:
time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))
其中 yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1
是当前年份中的日期序号,1 月 1 日的序号为 1
。
date.toordinal()
返回日期的预期格列高利历序号,其中公元 1 年 1 月 1 日的序号为 1。 对于任意 date 对象 d,date.fromordinal(d.toordinal()) == d
。
date.weekday()
返回一个整数代表星期几,星期一为0,星期天为6。例如, date(2002, 12, 4).weekday() == 2
,表示的是星期三。参阅 isoweekday()。
date.isoweekday()
返回一个整数代表星期几,星期一为1,星期天为7。例如:date(2002, 12, 4).isoweekday() == 3
,表示星期三。参见 weekday(), isocalendar()。
date.isocalendar()
返回一个由三部分组成的 named tuple 对象: year
, week
和 weekday
。
ISO 历法是一种被广泛使用的格列高利历。 3
ISO 年由 52 或 53 个完整星期构成,每个星期开始于星期一结束于星期日。 一个 ISO 年的第一个星期就是(格列高利)历法的一年中第一个包含星期四的星期。 这被称为 1 号星期,这个星期四所在的 ISO 年与其所在的格列高利年相同。
例如,2004 年的第一天是星期四,因此 ISO 2004 年的第一个星期开始于 2003 年 12 月 29 日星期一,结束于 2004 年 1 月 4 日星期日:
>>>
>>> from datetime import date >>> date(2003, 12, 29).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=1) >>> date(2004, 1, 4).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
在 3.9 版更改: 结果由元组改为 named tuple。
date.isoformat()
返回一个以 ISO 8601 格式 YYYY-MM-DD
来表示日期的字符串:
>>>
>>> from datetime import date >>> date(2002, 12, 4).isoformat() '2002-12-04'
date.__str__()
对于日期对象 d, str(d)
等价于 d.isoformat()
。
date.ctime()
返回一个表示日期的字符串:
>>>
>>> from datetime import date >>> date(2002, 12, 4).ctime() 'Wed Dec 4 00:00:00 2002'
d.ctime()
等效于:
time.ctime(time.mktime(d.timetuple()))
在原生 C ctime()
函数 (time.ctime() 会发起调用该函数,但 date.ctime() 则不会) 遵循 C 标准的平台上。
date.strftime(format)
Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See also strftime() 和 strptime() 的行为 and date.isoformat().
date.__format__(format)
Same as date.strftime(). This makes it possible to specify a format string for a date object in formatted string literals and when using str.format(). See also strftime() 和 strptime() 的行为 and date.isoformat().
class:date 用法示例
计算距离特定事件天数的例子:
>>>
>>> import time >>> from datetime import date >>> today = date.today() >>> today datetime.date(2007, 12, 5) >>> today == date.fromtimestamp(time.time()) True >>> my_birthday = date(today.year, 6, 24) >>> if my_birthday < today: ... my_birthday = my_birthday.replace(year=today.year + 1) >>> my_birthday datetime.date(2008, 6, 24) >>> time_to_birthday = abs(my_birthday - today) >>> time_to_birthday.days 202
使用 date 的更多例子:
>>>
>>> from datetime import date >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001 >>> d datetime.date(2002, 3, 11) >>> # Methods related to formatting string output >>> d.isoformat() '2002-03-11' >>> d.strftime("%d/%m/%y") '11/03/02' >>> d.strftime("%A %d. %B %Y") 'Monday 11. March 2002' >>> d.ctime() 'Mon Mar 11 00:00:00 2002' >>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month") 'The day is 11, the month is March.' >>> # Methods for to extracting 'components' under different calendars >>> t = d.timetuple() >>> for i in t: ... print(i) 2002 # year 3 # month 11 # day 0 0 0 0 # weekday (0 = Monday) 70 # 70th day in the year -1 >>> ic = d.isocalendar() >>> for i in ic: ... print(i) 2002 # ISO year 11 # ISO week number 1 # ISO day number ( 1 = Monday ) >>> # A date object is immutable; all operations produce a new object >>> d.replace(year=2005) datetime.date(2005, 3, 11)