datetime
--- 基本日期和时间类型¶
源代码: Lib/datetime.py
The datetime
module supplies classes for manipulating dates and times.
在支持日期时间数学运算的同时,实现的关注点更着重于如何能够更有效地解析其属性用于格式化输出和数据操作。
小技巧
跳到 格式代码。
参见
感知型对象和简单型对象¶
日期和时间对象可以根据它们是否包含时区信息而分为“感知型”和“简单型”两类。
充分掌握应用性算法和政治性时间调整信息例如时区和夏令时的情况下,一个 感知型 对象就能相对于其他感知型对象来精确定位自身时间点。 感知型对象是用来表示一个没有解释空间的固定时间点。 [1]
简单型 对象没有包含足够多的信息来无歧义地相对于其他 date/time 对象来定位自身时间点。 不论一个简单型对象所代表的是世界标准时间(UTC)、当地时间还是某个其他时区的时间完全取决于具体程序,就像一个特定数字所代表的是米、英里还是质量完全取决于具体程序一样。 简单型对象更易于理解和使用,代价则是忽略了某些现实性考量。
对于要求感知型对象的应用,datetime
和 time
对象具有一个可选的时区信息属性 tzinfo
,它可被设为抽象类 tzinfo
的子类的一个实例。 这些 tzinfo
对象会捕获与 UTC 时间的差值、时区名称以及夏令时是否生效等信息。
Only one concrete tzinfo
class, the timezone
class, is
supplied by the datetime
module. The timezone
class can
represent simple timezones with fixed offsets from UTC, such as UTC itself or
North American EST and EDT timezones. Supporting timezones at deeper levels of
detail is up to the application. The rules for time adjustment across the
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.
常量¶
The datetime
module exports the following constants:
- datetime.UTC¶
UTC 时区单例
datetime.timezone.utc
的别名。在 3.11 版本加入.
有效的类型¶
- class datetime.time
一个独立于任何特定日期的理想化时间,它假设每一天都恰好等于 24*60*60 秒。 (这里没有“闰秒”的概念。) 包含属性:
hour
,minute
,second
,microsecond
和tzinfo
。
- class datetime.datetime
日期和时间的结合。属性:
year
,month
,day
,hour
,minute
,second
,microsecond
, andtzinfo
.
- class datetime.timezone
一个实现了
tzinfo
抽象基类的子类,用于表示相对于 世界标准时间(UTC)的偏移量。在 3.2 版本加入.
这些类型的对象都是不可变的。
子类关系
object
timedelta
tzinfo
timezone
time
date
datetime
通用的特征属性¶
确定一个对象是感知型还是简单型¶
date
类型的对象都是简单型的。
time
或 datetime
类型的对象可以是感知型或者简单型。
一个 datetime
对象 d 在以下条件同时成立时将是感知型的:
d.tzinfo
不为None
d.tzinfo.utcoffset(d)
不返回None
在其他情况下,d 将是简单型的。
一个 time
对象 t 在以下条件同时成立时将是感知型的:
t.tzinfo
不为None
t.tzinfo.utcoffset(None)
不返回None
。
在其他情况下,t 将是简单型的。
感知型和简单型之间的区别不适用于 timedelta
对象。
timedelta
类对象¶
timedelta
对象表示两个 date 或者 time 的时间间隔。
- class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)¶
所有参数都是可选的并且默认为
0
。 这些参数可以是整数或者浮点数,也可以是正数或者负数。只有 days, seconds 和 microseconds 会存储在内部。 参数单位的换算规则如下:
1毫秒会转换成1000微秒。
1分钟会转换成60秒。
1小时会转换成3600秒。
1星期会转换成7天。
日期、秒、微秒都是标准化的,所以它们的表达方式也是唯一的,例:
0 <= microseconds < 1000000
0 <= seconds < 3600*24
(一天的秒数)-999999999 <= days <= 999999999
下面的例子演示了如何对 days, seconds 和 microseconds 以外的任意参数执行“合并”操作并标准化为以上三个结果属性:
>>> from datetime import timedelta >>> delta = timedelta( ... days=50, ... seconds=27, ... microseconds=10, ... milliseconds=29000, ... minutes=5, ... hours=8, ... weeks=2 ... ) >>> # Only days, seconds, and microseconds remain >>> delta datetime.timedelta(days=64, seconds=29156, microseconds=10)
在有任何参数为浮点型并且 microseconds 值为小数的情况下,从所有参数中余下的微秒数将被合并,并使用四舍五入偶不入奇的规则将总计值舍入到最接近的整数微秒值。 如果没有任何参数为浮点型的情况下,则转换和标准化过程将是完全精确的(不会丢失信息)。
如果标准化后的 days 数值超过了指定范围,将会抛出
OverflowError
异常。请注意对负数值进行标准化的结果可能会令人感到惊讶。 例如:
>>> from datetime import timedelta >>> d = timedelta(microseconds=-1) >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999)
类属性:
- timedelta.max¶
The most positive
timedelta
object,timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)
.
需要注意的是,因为标准化的缘故,timedelta.max
> -timedelta.min
,-timedelta.max
不可以表示一个 timedelta
类对象。
实例属性(只读):
属性 |
值 |
---|---|
|
-999999999 至 999999999 ,含999999999 |
|
0 至 86399,包含86399 |
|
0 至 999999,包含999999 |
支持的运算:
运算 |
结果: |
---|---|
|
t2 和 t3 的和。 运算后 t1-t2 == t3 and t1-t3 == t2 必为真值。(1) |
|
t2 减 t3 的差。 运算后 t1 == t2 - t3 and t2 == t1 + t3 必为真值。 (1)(6) |
|
乘以一个整数。运算后假如 |
In general, t1 * i == t1 * (i-1) + t1 is true. (1) |
|
|
乘以一个浮点数,结果会被舍入到 timedelta 最接近的整数倍。 精度使用四舍五偶入奇不入规则。 |
|
总时间 t2 除以间隔单位 t3 (3)。 返回一个 |
|
除以一个浮点数或整数。 结果会被舍入到 timedelta 最接近的整数倍。 精度使用四舍五偶入奇不入规则。 |
|
计算底数,其余部分(如果有)将被丢弃。在第二种情况下,将返回整数。 (3) |
|
余数为一个 |
|
通过 : |
|
返回一个相同数值的 |
|
等价于 |
|
当 |
|
返回一个形如 |
|
返回一个 |
注释:
结果正确,但可能会溢出。
结果正确,不会溢出。
除以0将会抛出异常
ZeroDivisionError
。-timedelta.max 不是一个
timedelta
类对象。timedelta
对象的字符串表示形式类似于其内部表示形式被规范化。对于负时间增量,这会导致一些不寻常的结果。例如:>>> timedelta(hours=-5) datetime.timedelta(days=-1, seconds=68400) >>> print(_) -1 day, 19:00:00
表达式
t2 - t3
通常与t2 + (-t3)
是等价的,除非 t3 等于timedelta.max
; 在这种情况下前者会返回结果,而后者则会溢出。
除了上面列举的操作以外,timedelta
对象还支持与 date
和 datetime
对象进行特定的相加和相减运算(见下文)。
在 3.2 版本发生变更: 现在已支持 timedelta
对象与另一个 timedelta
对象相整除或相除,包括求余运算和 divmod()
函数。 现在也支持 timedelta
对象加上或乘以一个 float
对象。
支持 timedelta
对象之间进行比较,但其中有一些注意事项。
==
或 !=
比较 总是 返回一个 bool
对象,无论被比较的对象是什么类型:
>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False
对于所有其他比较 (例如 <
和 >
),当一个 timedelta
对象与其他类型的对象比较时,将引发 TypeError
:
>>> delta2 > delta1
True
>>> delta2 > 5
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'
在布尔运算中,timedelta
对象当且仅当其不等于 timedelta(0)
时则会被视为真值。
实例方法:
- timedelta.total_seconds()¶
返回期间占用了多少秒。等价于
td / timedelta(seconds=1)
。对于秒以外的间隔单位,直接使用除法形式 (例如td / timedelta(microseconds=1)
)。需要注意的是,时间间隔较大时,这个方法的结果中的微秒将会失真(大多数平台上大于270年视为一个较大的时间间隔)。
在 3.2 版本加入.
timedelta
用法示例¶
一个标准化的附加示例:
>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
... minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0
timedelta
算术运算的示例:
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
date
对象¶
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
,如果时间戳数值超出所在平台 Clocaltime()
函数的支持范围的话,并且会在localtime()
出错时引发OSError
。 通常该数值会被限制在 1970 年至 2038 年之间。 请注意在时间戳概念包含闰秒的非 POSIX 系统上,闰秒会被fromtimestamp()
所忽略。在 3.3 版本发生变更: 引发
OverflowError
而不是ValueError
,如果时间戳数值超出所在平台 Clocaltime()
函数的支持范围的话,并会在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)¶
返回一个对应于以任何有效的 ISO 8601 格式给出的 date_string 的
date
,序数日期除外 (如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 版本发生变更: 在之前版本中,此方法仅支持一种格式
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.month¶
1 至 12(含)
- date.day¶
返回1到指定年月的天数间的数字。
支持的运算:
运算 |
结果: |
---|---|
|
date2 将为 date1 之后的 |
|
计算 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。
In other words,
date1 < date2
if and only ifdate1.toordinal() < date2.toordinal()
. Date comparison raisesTypeError
if the other comparand isn't also adate
object. However,NotImplemented
is returned instead if the other comparand has atimetuple
attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when adate
object is compared to an object of a different type,TypeError
is raised unless the comparison is==
or!=
. The latter cases returnFalse
orTrue
, respectively.
在布尔运算中,所有 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)¶
返回一个由显式格式字符串所控制的,代表日期的字符串。 表示时、分或秒的格式代码值将为 0。 另请参阅 strftime() and strptime() Behavior 和
date.isoformat()
。
- date.__format__(format)¶
与
date.strftime()
相同。 此方法使得在 格式化字符串字面值 中以及使用str.format()
时为date
对象指定格式字符串成为可能。 另请参阅 strftime() and strptime() Behavior 和date.isoformat()
。
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)
datetime
对象¶
datetime
对象是包含来自 date
对象和 time
对象的所有信息的单一对象。
与 date
对象一样,datetime
假定当前的格列高利历向前后两个方向无限延伸;与 time
对象一样,datetime
假定每一天恰好有 3600*24 秒。
构造器 :
- class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶
year, month 和 day 参数是必须的。 tzinfo 可以是
None
或者是一个tzinfo
子类的实例。 其余的参数必须是在下面范围内的整数:MINYEAR <= year <= MAXYEAR
,1 <= month <= 12
,1 <= day <= 指定年月的天数
,0 <= hour < 24
,0 <= minute < 60
,0 <= second < 60
,0 <= microsecond < 1000000
,fold in [0, 1]
.
如果参数不在这些范围内,则抛出
ValueError
异常。在 3.6 版本发生变更: 增加了 fold 形参。
其它构造器,所有的类方法:
- classmethod datetime.today()¶
返回表示当前地方时的 datetime 对象,其中
tzinfo
为None
。等价于:
datetime.fromtimestamp(time.time())
另请参阅
now()
,fromtimestamp()
。此方法的功能等价于
now()
,但是不带tz
形参。
- classmethod datetime.now(tz=None)¶
返回表示当前地方时的 date 和 time 对象。
如果可选参数 tz 为
None
或未指定,这就类似于today()
,但该方法会在可能的情况下提供比通过time.time()
时间戳所获时间值更高的精度(例如,在提供了 Cgettimeofday()
函数的平台上就可以做到这一点)。如果 tz 不为
None
,它必须是tzinfo
子类的一个实例,并且当前日期和时间将被转换到 tz 时区。
- classmethod datetime.utcnow()¶
返回表示当前 UTC 时间的 date 和 time,其中
tzinfo
为None
。这类似于
now()
,但返回的是当前 UTC 日期和时间,类型为简单型datetime
对象。 感知型的当前 UTC 日期时间可通过调用datetime.now(timezone.utc)
来获得。 另请参阅now()
。警告
由于简单型
datetime
对象会被许多datetime
方法当作本地时间来处理,最好是使用感知型日期时间对象来表示 UTC 时间。 因此,创建表示当前 UTC 时间的对象的推荐方式是通过调用datetime.now(timezone.utc)
。自 3.12 版本弃用: 请用带
UTC
的datetime.now()
代替。
- classmethod datetime.fromtimestamp(timestamp, tz=None)¶
返回 POSIX 时间戳对应的本地日期和时间,如
time.time()
返回的。 如果可选参数 tz 指定为None
或未指定,时间戳将转换为平台的本地日期和时间,并且返回的datetime
对象将为简单型。如果 tz 不为
None
,它必须是tzinfo
子类的一个实例,并且时间戳将被转换到 tz 指定的时区。fromtimestamp()
可能会引发OverflowError
,如果时间戳数值超出所在平台 Clocaltime()
或gmtime()
函数的支持范围的话,并会在localtime()
或gmtime()
报错时引发OSError
。 通常该数值会被限制在 1970 年至 2038 年之间。 请注意在时间戳概念包含闰秒的非 POSIX 系统上,闰秒会被fromtimestamp()
所忽略,结果可能导致两个相差一秒的时间戳产生相同的datetime
对象。 相比utcfromtimestamp()
更推荐使用此方法。在 3.3 版本发生变更: 引发
OverflowError
而不是ValueError
,如果时间戳数值超出所在平台 Clocaltime()
或gmtime()
函数的支持范围的话。 并会在localtime()
或gmtime()
出错时引发OSError
而不是ValueError
。在 3.6 版本发生变更:
fromtimestamp()
可能返回fold
值设为 1 的实例。
- classmethod datetime.utcfromtimestamp(timestamp)¶
返回对应于 POSIX 时间戳的 UTC
datetime
,其中tzinfo
值为None
。 (结果为简单型对象。)这可能引发
OverflowError
,如果时间戳数值超出所在平台 Cgmtime()
函数的支持范围的话,并会在gmtime()
报错时引发OSError
。 通常该数值会被限制在 1970 至 2038 年之间。要得到一个感知型
datetime
对象,应调用fromtimestamp()
:datetime.fromtimestamp(timestamp, timezone.utc)
在 POSIX 兼容的平台上,它等价于以下表达式:
datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)
不同之处在于后一种形式总是支持完整年份范围:从
MINYEAR
到MAXYEAR
的开区间。警告
由于简单型
datetime
对象会被许多datetime
方法当作本地时间来处理,最好是使用感知型日期时间对象来表示 UTC 时间。 因此,创建表示特定 UTC 时间戳的日期时间对象的推荐方式是通过调用datetime.fromtimestamp(timestamp, tz=timezone.utc)
。在 3.3 版本发生变更: 引发
OverflowError
而不是ValueError
,如果时间戳数值超出所在平台 Cgmtime()
函数的支持范围的话。 并会在gmtime()
出错时引发OSError
而不是ValueError
。自 3.12 版本弃用: 请用带
UTC
的datetime.fromtimestamp()
代替。
- classmethod datetime.fromordinal(ordinal)¶
返回对应于预期格列高利历序号的
datetime
,其中公元 1 年 1 月 1 日的序号为 1。 除非1 <= ordinal <= datetime.max.toordinal()
否则会引发ValueError
。 结果的 hour, minute, second 和 microsecond 值均为 0,并且tzinfo
值为None
。
- classmethod datetime.combine(date, time, tzinfo=time.tzinfo)¶
返回一个新的
datetime
对象,其日期部分等于给定的date
对象的值,而其时间部分等于给定的time
对象的值。 如果提供了 tzinfo 参数,其值会被用来设置结果的tzinfo
属性,否则将使用 time 参数的tzinfo
属性。 如果 date 参数是一个datetime
对象,则其时间部分和tzinfo
属性将被忽略。对于任意
datetime
对象 d,d == datetime.combine(d.date(), d.time(), d.tzinfo)
。在 3.6 版本发生变更: 增加了 tzinfo 参数。
- classmethod datetime.fromisoformat(date_string)¶
返回一个对应于以任何有效的 8601 格式给出的 date_string 的
datetime
,下列格式除外:时区时差可能会有带小数的秒值。
T
分隔符可以用任何单个 unicode 字符来替换。目前不支持序数日期。
带小数的时和分是不受支持的。
示例:
>>> from datetime import datetime >>> datetime.fromisoformat('2011-11-04') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('20111104') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('2011-11-04T00:05:23') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-11-04T00:05:23Z') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('20111104T000523') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-W01-2T00:05:23.283') datetime.datetime(2011, 1, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('2011-11-04T00:05:23+04:00') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
在 3.7 版本加入.
在 3.11 版本发生变更: 在之前版本中,此方法仅支持可以由
date.isoformat()
或datetime.isoformat()
发出的格式。
- classmethod datetime.fromisocalendar(year, week, day)¶
返回以 year, week 和 day 值指明的 ISO 历法日期所对应的
datetime
。 该datetime 对象的非日期部分将使用其标准默认值来填充。 这是函数datetime.isocalendar()
的逆操作。在 3.8 版本加入.
- classmethod datetime.strptime(date_string, format)¶
返回一个对应于 date_string,根据 format 进行解析得到的
datetime
对象。如果 format 不包含微秒或时区信息,这将等价于:
datetime(*(time.strptime(date_string, format)[0:6]))
如果 date_string 和 format 无法被
time.strptime()
解析或它返回一个不是时间元组的值则将引发ValueError
。 另请参阅 strftime() and strptime() Behavior 和datetime.fromisoformat()
。
类属性:
实例属性(只读):
- datetime.month¶
1 至 12(含)
- datetime.day¶
返回1到指定年月的天数间的数字。
- datetime.hour¶
取值范围是
range(24)
。
- datetime.minute¶
取值范围是
range(60)
。
- datetime.second¶
取值范围是
range(60)
。
- datetime.microsecond¶
取值范围是
range(1000000)
。
- datetime.fold¶
取值范围是
[0, 1]
。 用于在重复的时间段中消除边界时间歧义。 (当夏令时结束时回拨时钟或由于政治原因导致当明时区的 UTC 时差减少就会出现重复的时间段。) 取值 0 (1) 表示两个时刻早于(晚于)所代表的同一边界时间。在 3.6 版本加入.
支持的运算:
运算 |
结果: |
---|---|
|
(1) |
|
(2) |
|
(3) |
|
datetime2 是从 datetime1 去掉了一段 timedelta 的结果,如果
timedelta.days
> 0 则是在时间线上前进,如果timedelta.days
< 0 则是在时间线上后退。 该结果具有与输入的 datetime 相同的tzinfo
属性,并且操作完成后 datetime2 - datetime1 == timedelta。 如果 datetime2.year 将要小于MINYEAR
或大于MAXYEAR
则会引发OverflowError
。 请注意即使输入的是一个感知型对象,该方法也不会进行时区调整。计算 datetime2 使得 datetime2 + timedelta == datetime1。 与相加操作一样,结果具有与输入的 datetime 相同的
tzinfo
属性,即使输入的是一个感知型对象,该方法也不会进行时区调整。从一个
datetime
减去一个datetime
仅对两个操作数均为简单型或均为感知型时有定义。 如果一个是感知型而另一个是简单型,则会引发TypeError
。如果两个操作数都是简单型,或都是感知型并且具有相同的
tzinfo
属性,则tzinfo
属性会被忽略,并且结果会是一个使得datetime2 + t == datetime1
的timedelta
对象 t。 在此情况下不会进行时区调整。如果两个操作数都是感知型且具有不同的
tzinfo
属性,a-b
操作的效果就如同 a 和 b 首先被转换为简单型 UTC 日期时间。 结果将是(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())
,除非具体实现绝对不溢出。当 datetime1 的时间在 datetime2 之前则认为 datetime1 小于 datetime2。
如果比较的一方是简单型而另一方是感知型,则如果尝试进行顺序比较将引发
TypeError
。 对于相等比较,简单型实例将永远不等于感知型实例。如果两个比较方都是感知型,且具有相同的
tzinfo
属性,则相同的tzinfo
属性会被忽略并对基本日期时间值进行比较。 如果两个比较方都是感知型且具有不同的tzinfo
属性,则两个比较方将首先通过减去它们的 UTC 差值(使用self.utcoffset()
获取)来进行调整。备注
In order to stop comparison from falling back to the default scheme of comparing object addresses, datetime comparison normally raises
TypeError
if the other comparand isn't also adatetime
object. However,NotImplemented
is returned instead if the other comparand has atimetuple
attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when adatetime
object is compared to an object of a different type,TypeError
is raised unless the comparison is==
or!=
. The latter cases returnFalse
orTrue
, respectively.
实例方法:
- datetime.time()¶
返回具有同样 hour, minute, second, microsecond 和 fold 值的
time
对象。tzinfo
值为None
。 另请参见timetz()
方法。在 3.6 版本发生变更: fold 值会被复制给返回的
time
对象。
- datetime.timetz()¶
返回具有同样 hour, minute, second, microsecond, fold 和 tzinfo 属性性的
time
对象。 另请参见time()
方法。在 3.6 版本发生变更: fold 值会被复制给返回的
time
对象。
- 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=0)¶
返回一个具有同样属性值的 datetime,除非通过任何关键字参数为某些属性指定了新值。 请注意可以通过指定
tzinfo=None
来从一个感知型 datetime 创建一个简单型 datetime 而不必转换日期和时间数据。在 3.6 版本发生变更: 增加了 fold 形参。
- datetime.astimezone(tz=None)¶
返回一个具有新的
tzinfo
属性 tz 的datetime
对象,并会调整日期和时间数据使得结果对应的 UTC 时间与 self 相同,但为 tz 时区的本地时间。如果给出了 tz,则它必须是一个
tzinfo
子类的实例,并且其utcoffset()
和dst()
方法不可返回None
。 如果 self 为简单型,它会被假定为基于系统时区表示的时间。如果调用时不传入参数 (或传入
tz=None
) 则将假定目标时区为系统的本地时区。 转换后 datetime 实例的.tzinfo
属性将被设为一个timezone
实例,时区名称和时差值将从 OS 获取。如果
self.tzinfo
为 tz,self.astimezone(tz)
等于 self: 不会对日期或时间数据进行调整。 否则结果为 tz 时区的本地时间,代表的 UTC 时间与 self 相同:在astz = dt.astimezone(tz)
之后,astz - astz.utcoffset()
将具有与dt - dt.utcoffset()
相同的日期和时间数据。如果你只是想要附加一个时区对象 tz 到一个 datetime 对象 dt 而不调整日期和时间数据,请使用
dt.replace(tzinfo=tz)
。 如果你只想从一个感知型 datetime 对象 dt 移除时区对象,请使用dt.replace(tzinfo=None)
。请注意默认的
tzinfo.fromutc()
方法在tzinfo
的子类中可以被重写,从而影响astimezone()
的返回结果。 如果忽略出错的情况,astimezone()
的行为就类似于:def astimezone(self, tz): if self.tzinfo is tz: return self # Convert self to UTC, and attach the new time zone object. utc = (self - self.utcoffset()).replace(tzinfo=tz) # Convert from UTC to tz's local time. return tz.fromutc(utc)
在 3.3 版本发生变更: tz 现在可以被省略。
在 3.6 版本发生变更:
astimezone()
方法可以由简单型实例调用,这将假定其表示本地时间。
- datetime.utcoffset()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.utcoffset(self)
,并且在后者不返回None
或者一个幅度小于一天的timedelta
对象时将引发异常。在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
- datetime.dst()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.dst(self)
,并且在后者不返回None
或者一个幅度小于一天的timedelta
对象时将引发异常。在 3.7 版本发生变更: DST 差值不再限制为一个整数分钟值。
- datetime.tzname()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.tzname(self)
,如果后者不返回None
或者一个字符串对象则将引发异常。
- datetime.timetuple()¶
返回一个
time.struct_time
,即time.localtime()
所返回的类型。d.timetuple()
等价于:time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst))
where
yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1
is the day number within the current year starting with1
for January 1st. Thetm_isdst
flag of the result is set according to thedst()
method:tzinfo
isNone
ordst()
returnsNone
,tm_isdst
is set to-1
; else ifdst()
returns a non-zero value,tm_isdst
is set to1
; elsetm_isdst
is set to0
.
- datetime.utctimetuple()¶
If
datetime
instance d is naive, this is the same asd.timetuple()
except thattm_isdst
is forced to 0 regardless of whatd.dst()
returns. DST is never in effect for a UTC time.If d is aware, d is normalized to UTC time, by subtracting
d.utcoffset()
, and atime.struct_time
for the normalized time is returned.tm_isdst
is forced to 0. Note that anOverflowError
may be raised if d.year wasMINYEAR
orMAXYEAR
and UTC adjustment spills over a year boundary.警告
由于简单型
datetime
对象会被许多datetime
方法当作本地时间来处理,最好是使用感知型日期时间来表示 UTC 时间;因此,使用datetime.utctimetuple()
可能会给出误导性的结果。 如果你有一个表示 UTC 的简单型datetime
,请使用datetime.replace(tzinfo=timezone.utc)
将其改为感知型,这样你才能使用datetime.timetuple()
。
- datetime.toordinal()¶
返回日期的预期格列高利历序号。 与
self.date().toordinal()
相同。
- datetime.timestamp()¶
返回对应于
datetime
实例的 POSIX 时间戳。 此返回值是与time.time()
返回值类似的float
对象。简单型
datetime
实例会被假定为代表本地时间并且此方法依赖于平台的 Cmktime()
函数来执行转换。 由于在许多平台上datetime
支持的取值范围比mktime()
更广,对于极其遥远的过去或未来此方法可能会引发OverflowError
或OSError
。对于感知型
datetime
实例,返回值的计算方式为:(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
在 3.3 版本加入.
在 3.6 版本发生变更:
timestamp()
方法使用fold
属性来消除重复间隔中的时间歧义。备注
没有一个方法能直接从表示 UTC 时间的简单型
datetime
实例获取 POSIX 时间戳。 如果你的应用程序使用此惯例并且你的系统时区不是设为 UTC,你可以通过提供tzinfo=timezone.utc
来获取 POSIX 时间戳:timestamp = dt.replace(tzinfo=timezone.utc).timestamp()
或者通过直接计算时间戳:
timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
- datetime.weekday()¶
返回一个整数代表星期几,星期一为 0,星期天为 6。 相当于
self.date().weekday()
。 另请参阅isoweekday()
。
- datetime.isoweekday()¶
返回一个整数代表星期几,星期一为 1,星期天为 7。 相当于
self.date().isoweekday()
。 另请参阅weekday()
,isocalendar()
。
- datetime.isocalendar()¶
返回一个由三部分组成的 named tuple:
year
,week
和weekday
。 等同于self.date().isocalendar()
。
- datetime.isoformat(sep='T', timespec='auto')¶
返回一个以 ISO 8601 格式表示的日期和时间字符串:
YYYY-MM-DDTHH:MM:SS.ffffff
,如果microsecond
不为 0YYYY-MM-DDTHH:MM:SS
,如果microsecond
为 0
如果
utcoffset()
返回值不为None
,则添加一个字符串来给出 UTC 时差:YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
,如果microsecond
不为 0YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]
,如果microsecond
为 0
示例:
>>> from datetime import datetime, timezone >>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat() '2019-05-18T15:17:08.132263' >>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat() '2019-05-18T15:17:00+00:00'
可选参数 sep (默认为
'T'
) 为单个分隔字符,会被放在结果的日期和时间两部分之间。 例如:>>> from datetime import tzinfo, timedelta, datetime >>> class TZ(tzinfo): ... """A time zone with an arbitrary, constant -06:39 offset.""" ... def utcoffset(self, dt): ... return timedelta(hours=-6, minutes=-39) ... >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') '2002-12-25 00:00:00-06:39' >>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat() '2009-11-27T00:00:00.000100-06:39'
可选参数 timespec 要包含的额外时间组件值 (默认为
'auto'
)。它可以是以下值之一:'auto'
: 如果microsecond
为 0 则与'seconds'
相同,否则与'microseconds'
相同。'hours'
: 以两个数码的HH
格式 包含hour
。'milliseconds'
: 包含完整时间,但将秒值的小数部分截断至毫秒。 格式为HH:MM:SS.sss
。'microseconds'
: 以HH:MM:SS.ffffff
格式包含完整时间。
备注
排除掉的时间部分将被截断,而不是被舍入。
对于无效的 timespec 参数将引发
ValueError
:>>> from datetime import datetime >>> datetime.now().isoformat(timespec='minutes') '2002-12-25T00:00' >>> dt = datetime(2015, 1, 1, 12, 30, 59, 0) >>> dt.isoformat(timespec='microseconds') '2015-01-01T12:30:59.000000'
在 3.6 版本发生变更: 增加了 timespec 形参。
- datetime.ctime()¶
返回一个表示日期和时间的字符串:
>>> from datetime import datetime >>> datetime(2002, 12, 4, 20, 30, 40).ctime() 'Wed Dec 4 20:30:40 2002'
输出字符串将 并不 包括时区信息,无论输入的是感知型还是简单型。
d.ctime()
等效于:time.ctime(time.mktime(d.timetuple()))
在原生 C
ctime()
函数 (time.ctime()
会发起调用该函数,但datetime.ctime()
则不会) 遵循 C 标准的平台上。
- datetime.strftime(format)¶
返回一个由显式格式字符串所控制的,代表日期和时间的字符串。 另请参阅 strftime() and strptime() Behavior 和
datetime.isoformat()
。
- datetime.__format__(format)¶
与
datetime.strftime()
相同。 此方法使得在 格式化字符串字面值 中以及使用str.format()
时为datetime
对象指定格式字符串成为可能。 另请参阅 strftime() and strptime() Behavior 和datetime.isoformat()
。
用法示例: datetime
¶
Examples of working with datetime
objects:
>>> from datetime import datetime, date, time, timezone
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
>>> datetime.now(timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
... print(it)
...
2006 # year
11 # month
21 # day
16 # hour
30 # minute
0 # second
1 # weekday (0 = Monday)
325 # number of days since 1st January
-1 # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
... print(it)
...
2006 # ISO year
47 # ISO week
2 # ISO weekday
>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
以下示例定义了一个 tzinfo
子类,它捕获 Kabul, Afghanistan 时区的信息,该时区使用 +4 UTC 直到 1945 年,之后则使用 +4:30 UTC:
from datetime import timedelta, datetime, tzinfo, timezone
class KabulTz(tzinfo):
# Kabul used +4 until 1945, when they moved to +4:30
UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)
def utcoffset(self, dt):
if dt.year < 1945:
return timedelta(hours=4)
elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
# An ambiguous ("imaginary") half-hour range representing
# a 'fold' in time due to the shift from +4 to +4:30.
# If dt falls in the imaginary range, use fold to decide how
# to resolve. See PEP495.
return timedelta(hours=4, minutes=(30 if dt.fold else 0))
else:
return timedelta(hours=4, minutes=30)
def fromutc(self, dt):
# Follow same validations as in datetime.tzinfo
if not isinstance(dt, datetime):
raise TypeError("fromutc() requires a datetime argument")
if dt.tzinfo is not self:
raise ValueError("dt.tzinfo is not self")
# A custom implementation is required for fromutc as
# the input to this function is a datetime with utc values
# but with a tzinfo set to self.
# See datetime.astimezone or fromtimestamp.
if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
return dt + timedelta(hours=4, minutes=30)
else:
return dt + timedelta(hours=4)
def dst(self, dt):
# Kabul does not observe daylight saving time.
return timedelta(0)
def tzname(self, dt):
if dt >= self.UTC_MOVE_DATE:
return "+04:30"
return "+04"
上述 KabulTz
的用法:
>>> tz1 = KabulTz()
>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00
>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True
time
对象¶
A time
object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a tzinfo
object.
- class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶
所有参数都是可选的。 tzinfo 可以是
None
,或者是一个tzinfo
子类的实例。 其余的参数必须是在下面范围内的整数:0 <= hour < 24
,0 <= minute < 60
,0 <= second < 60
,0 <= microsecond < 1000000
,fold in [0, 1]
.
如果给出一个此范围以外的参数,则会引发
ValueError
。 所有参数值默认为0
,只有 tzinfo 默认为None
。
类属性:
实例属性(只读):
- time.hour¶
取值范围是
range(24)
。
- time.minute¶
取值范围是
range(60)
。
- time.second¶
取值范围是
range(60)
。
- time.microsecond¶
取值范围是
range(1000000)
。
- time.fold¶
取值范围是
[0, 1]
。 用于在重复的时间段中消除边界时间歧义。 (当夏令时结束时回拨时钟或由于政治原因导致当明时区的 UTC 时差减少就会出现重复的时间段。) 取值 0 (1) 表示两个时刻早于(晚于)所代表的同一边界时间。在 3.6 版本加入.
time
对象支持 time
与 time
的比较,当 a 时间在 b 之前时,则认为 a 小于 b。 如果比较的一方是简单型而另一方是感知型,则如果尝试进行顺序比较将引发 TypeError
。 对于相等比较,简单型实例将永远不等于感知型实例。
If both comparands are aware, and have
the same tzinfo
attribute, the common tzinfo
attribute is
ignored and the base times are compared. If both comparands are aware and
have different tzinfo
attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from self.utcoffset()
). In order
to stop mixed-type comparisons from falling back to the default comparison by
object address, when a time
object is compared to an object of a
different type, TypeError
is raised unless the comparison is ==
or
!=
. The latter cases return False
or True
, respectively.
在布尔运算时,time
对象总是被视为真值。
在 3.5 版本发生变更: 在 Python 3.5 之前,如果一个 time
对象代表 UTC 午夜零时则会被视为假值。 此行为被认为容易引发困惑和错误,因此从 Python 3.5 起已被去除。 详情参见 bpo-13936。
其他构造方法:
- classmethod time.fromisoformat(time_string)¶
返回一个对应于以任何有效的 ISO 8601 格式给出的 time_string 的
time
,下列格式除外:时区时差可能会有带小数的秒值。
打头的
T
,通常在当日期和时间之间可能存在歧义时才有必要,不是必需的。带小数的秒值可以有任意多位数码(超过 6 位将被截断)。
带小数的时和分是不受支持的。
示例:
.. doctest::
>>> from datetime import time >>> time.fromisoformat('04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T042301') datetime.time(4, 23, 1) >>> time.fromisoformat('04:23:01.000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01,000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01+04:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400))) >>> time.fromisoformat('04:23:01Z') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc) >>> time.fromisoformat('04:23:01+00:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
在 3.7 版本加入.
在 3.11 版本发生变更: 在之前版本中,此方法仅支持可由
time.isoformat()
发出的格式。
实例方法:
- time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶
返回一个具有同样属性值的
time
,除非通过任何关键字参数指定了某些属性值。 请注意可以通过指定tzinfo=None
从一个感知型time
创建一个简单型time
,而不必转换时间数据。在 3.6 版本发生变更: 增加了 fold 形参。
- time.isoformat(timespec='auto')¶
返回表示为下列 ISO 8601 格式之一的时间字符串:
HH:MM:SS.ffffff
,如果microsecond
不为 0HH:MM:SS
,如果microsecond
为 0HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
,如果utcoffset()
不返回None
HH:MM:SS+HH:MM[:SS[.ffffff]]
,如果microsecond
为 0 并且utcoffset()
不返回None
可选参数 timespec 要包含的额外时间组件值 (默认为
'auto'
)。它可以是以下值之一:'auto'
: 如果microsecond
为 0 则与'seconds'
相同,否则与'microseconds'
相同。'hours'
: 以两个数码的HH
格式 包含hour
。'milliseconds'
: 包含完整时间,但将秒值的小数部分截断至毫秒。 格式为HH:MM:SS.sss
。'microseconds'
: 以HH:MM:SS.ffffff
格式包含完整时间。
备注
排除掉的时间部分将被截断,而不是被舍入。
对于无效的 timespec 参数将引发
ValueError
。示例:
>>> from datetime import time >>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes') '12:34' >>> dt = time(hour=12, minute=34, second=56, microsecond=0) >>> dt.isoformat(timespec='microseconds') '12:34:56.000000' >>> dt.isoformat(timespec='auto') '12:34:56'
在 3.6 版本发生变更: 增加了 timespec 形参。
- time.__str__()¶
对于时间对象 t,
str(t)
等价于t.isoformat()
。
- time.strftime(format)¶
返回一个由显式格式字符串所控制的,代表时间的字符串。 另请参阅 strftime() and strptime() Behavior 和
time.isoformat()
。
- time.__format__(format)¶
与
time.strftime()
相同。 此方法使得在 格式化字符串字面值 中以及使用str.format()
时为time
对象指定格式字符串成为可能。 另请参阅 strftime() and strptime() Behavior 和time.isoformat()
。
- time.utcoffset()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.utcoffset(None)
,并且在后者不返回None
或一个幅度小于一天的 atimedelta
对象时将引发异常。在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
- time.dst()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.dst(None)
,并且在后者不返回None
或者一个幅度小于一天的timedelta
对象时将引发异常。在 3.7 版本发生变更: DST 差值不再限制为一个整数分钟值。
- time.tzname()¶
如果
tzinfo
为None
,则返回None
,否则返回self.tzinfo.tzname(None)
,如果后者不返回None
或者一个字符串对象则将引发异常。
用法示例: time
¶
使用 time
对象的例子:
>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=1)
... def dst(self, dt):
... return timedelta(0)
... def tzname(self,dt):
... return "+01:00"
... def __repr__(self):
... return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'
tzinfo
对象¶
- class datetime.tzinfo¶
这是一个抽象基类,也就是说该类不应被直接实例化。 请定义
tzinfo
的子类来捕获有关特定时区的信息。tzinfo
的(某个实体子类)的实例可以被传给datetime
和time
对象的构造器。 这些对象会将它们的属性视为对应于本地时间,并且tzinfo
对象支持展示本地时间与 UTC 的差值、时区名称以及 DST 差值的方法,都是与传给它们的日期或时间对象的相对值。You need to derive a concrete subclass, and (at least) supply implementations of the standard
tzinfo
methods needed by thedatetime
methods you use. Thedatetime
module providestimezone
, a simple concrete subclass oftzinfo
which can represent timezones with fixed offset from UTC such as UTC itself or North American EST and EDT.对于封存操作的特殊要求:一个
tzinfo
子类必须具有可不带参数调用的__init__()
方法,否则它虽然可以被封存,但可能无法再次解封。 这是个技术性要求,在未来可能会被取消。A concrete subclass of
tzinfo
may need to implement the following methods. Exactly which methods are needed depends on the uses made of awaredatetime
objects. If in doubt, simply implement all of them.
- tzinfo.utcoffset(dt)¶
将本地时间与 UTC 时差返回为一个
timedelta
对象,如果本地时区在 UTC 以东则为正值。 如果本地时区在 UTC 以西则为负值。这表示与 UTC 的 总计 时差;举例来说,如果一个
tzinfo
对象同时代表时区和 DST 调整,则utcoffset()
应当返回两者的和。 如果 UTC 时差不确定则返回None
。 在其他情况下返回值必须为一个timedelta
对象,其取值严格限制于-timedelta(hours=24)
和timedelta(hours=24)
之间(差值的幅度必须小于一天)。 大多数utcoffset()
的实现看起来可能像是以下两者之一:return CONSTANT # fixed-offset class return CONSTANT + self.dst(dt) # daylight-aware class
如果
utcoffset()
返回值不为None
,则dst()
也不应返回None
。默认的
utcoffset()
实现会引发NotImplementedError
。在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
- tzinfo.dst(dt)¶
将夏令时(DST)调整返回为一个
timedelta
对象,如果 DST 信息未知则返回None
。Return
timedelta(0)
if DST is not in effect. If DST is in effect, return the offset as atimedelta
object (seeutcoffset()
for details). Note that DST offset, if applicable, has already been added to the UTC offset returned byutcoffset()
, so there's no need to consultdst()
unless you're interested in obtaining DST info separately. For example,datetime.timetuple()
calls itstzinfo
attribute'sdst()
method to determine how thetm_isdst
flag should be set, andtzinfo.fromutc()
callsdst()
to account for DST changes when crossing time zones.一个可以同时处理标准时和夏令时的
tzinfo
子类的实例 tz 必须在此情形中保持一致:tz.utcoffset(dt) - tz.dst(dt)
must return the same result for every
datetime
dt withdt.tzinfo == tz
For sanetzinfo
subclasses, this expression yields the time zone's "standard offset", which should not depend on the date or the time, but only on geographic location. The implementation ofdatetime.astimezone()
relies on this, but cannot detect violations; it's the programmer's responsibility to ensure it. If atzinfo
subclass cannot guarantee this, it may be able to override the default implementation oftzinfo.fromutc()
to work correctly withastimezone()
regardless.大多数
dst()
的实现可能会如以下两者之一:def dst(self, dt): # a fixed-offset class: doesn't account for DST return timedelta(0)
或者:
def dst(self, dt): # Code to set dston and dstoff to the time zone's DST # transition times based on the input dt.year, and expressed # in standard local time. if dston <= dt.replace(tzinfo=None) < dstoff: return timedelta(hours=1) else: return timedelta(0)
默认的
dst()
实现会引发NotImplementedError
。在 3.7 版本发生变更: DST 差值不再限制为一个整数分钟值。
- tzinfo.tzname(dt)¶
Return the time zone name corresponding to the
datetime
object dt, as a string. Nothing about string names is defined by thedatetime
module, and there's no requirement that it mean anything in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. ReturnNone
if a string name isn't known. Note that this is a method rather than a fixed string primarily because sometzinfo
subclasses will wish to return different names depending on the specific value of dt passed, especially if thetzinfo
class is accounting for daylight time.默认的
tzname()
实现会引发NotImplementedError
。
这些方法会被 datetime
或 time
对象调用,用来与它们的同名方法相对应。 datetime
对象会将自身作为传入参数,而 time
对象会将 None
作为传入参数。 这样 tzinfo
子类的方法应当准备好接受 dt 参数值为 None
或是 datetime
类的实例。
当传入 None
时,应当由类的设计者来决定最佳回应方式。 例如,返回 None
适用于希望该类提示时间对象不参与 tzinfo
协议处理。 让 utcoffset(None)
返回标准 UTC 时差也许会更有用处,因为并没有其他可用于发现标准时差的约定惯例。
当传入一个 datetime
对象来回应 datetime
方法时,dt.tzinfo
与 self 是同一对象。 tzinfo
方法可以依赖这一点,除非用户代码直接调用了 tzinfo
方法。 此行为的目的是使得 tzinfo
方法将 dt 解读为本地时间,而不需要担心其他时区的相关对象。
还有一个额外的 tzinfo
方法,某个子类可能会希望重写它:
- tzinfo.fromutc(dt)¶
此方法会由默认的
datetime.astimezone()
实现来调用。 当被其调用时,dt.tzinfo
为 self,并且 dt 的日期和时间数据会被视为表示 UTC 时间,fromutc()
的目标是调整日期和时间数据,返回一个等价的 datetime 来表示 self 的本地时间。Most
tzinfo
subclasses should be able to inherit the defaultfromutc()
implementation without problems. It's strong enough to handle fixed-offset time zones, and time zones accounting for both standard and daylight time, and the latter even if the DST transition times differ in different years. An example of a time zone the defaultfromutc()
implementation may not handle correctly in all cases is one where the standard offset (from UTC) depends on the specific date and time passed, which can happen for political reasons. The default implementations ofastimezone()
andfromutc()
may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes.忽略针对错误情况的代码,默认
fromutc()
实现的行为方式如下:def fromutc(self, dt): # raise ValueError error if dt.tzinfo is not self dtoff = dt.utcoffset() dtdst = dt.dst() # raise ValueError if dtoff is None or dtdst is None delta = dtoff - dtdst # this is self's standard offset if delta: dt += delta # convert to standard local time dtdst = dt.dst() # raise ValueError if dtdst is None if dtdst: return dt + dtdst else: return dt
在以下 tzinfo_examples.py
文件中有一些 tzinfo
类的例子:
from datetime import tzinfo, timedelta, datetime
ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)
# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
# timezones where UTC offset and/or the DST rules had
# changed in the past.)
import time as _time
STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
DSTOFFSET = STDOFFSET
DSTDIFF = DSTOFFSET - STDOFFSET
class LocalTimezone(tzinfo):
def fromutc(self, dt):
assert dt.tzinfo is self
stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
args = _time.localtime(stamp)[:6]
dst_diff = DSTDIFF // SECOND
# Detect fold
fold = (args == _time.localtime(stamp - dst_diff))
return datetime(*args, microsecond=dt.microsecond,
tzinfo=self, fold=fold)
def utcoffset(self, dt):
if self._isdst(dt):
return DSTOFFSET
else:
return STDOFFSET
def dst(self, dt):
if self._isdst(dt):
return DSTDIFF
else:
return ZERO
def tzname(self, dt):
return _time.tzname[self._isdst(dt)]
def _isdst(self, dt):
tt = (dt.year, dt.month, dt.day,
dt.hour, dt.minute, dt.second,
dt.weekday(), 0, 0)
stamp = _time.mktime(tt)
tt = _time.localtime(stamp)
return tt.tm_isdst > 0
Local = LocalTimezone()
# A complete implementation of current DST rules for major US time zones.
def first_sunday_on_or_after(dt):
days_to_go = 6 - dt.weekday()
if days_to_go:
dt += timedelta(days_to_go)
return dt
# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006
def us_dst_range(year):
# Find start and end times for US DST. For years before 1967, return
# start = end for no DST.
if 2006 < year:
dststart, dstend = DSTSTART_2007, DSTEND_2007
elif 1986 < year < 2007:
dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
elif 1966 < year < 1987:
dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
else:
return (datetime(year, 1, 1), ) * 2
start = first_sunday_on_or_after(dststart.replace(year=year))
end = first_sunday_on_or_after(dstend.replace(year=year))
return start, end
class USTimeZone(tzinfo):
def __init__(self, hours, reprname, stdname, dstname):
self.stdoffset = timedelta(hours=hours)
self.reprname = reprname
self.stdname = stdname
self.dstname = dstname
def __repr__(self):
return self.reprname
def tzname(self, dt):
if self.dst(dt):
return self.dstname
else:
return self.stdname
def utcoffset(self, dt):
return self.stdoffset + self.dst(dt)
def dst(self, dt):
if dt is None or dt.tzinfo is None:
# An exception may be sensible here, in one or both cases.
# It depends on how you want to treat them. The default
# fromutc() implementation (called by the default astimezone()
# implementation) passes a datetime with dt.tzinfo is self.
return ZERO
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
# Can't compare naive to aware objects, so strip the timezone from
# dt first.
dt = dt.replace(tzinfo=None)
if start + HOUR <= dt < end - HOUR:
# DST is in effect.
return HOUR
if end - HOUR <= dt < end:
# Fold (an ambiguous hour): use dt.fold to disambiguate.
return ZERO if dt.fold else HOUR
if start <= dt < start + HOUR:
# Gap (a non-existent hour): reverse the fold rule.
return HOUR if dt.fold else ZERO
# DST is off.
return ZERO
def fromutc(self, dt):
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
start = start.replace(tzinfo=self)
end = end.replace(tzinfo=self)
std_time = dt + self.stdoffset
dst_time = std_time + HOUR
if end <= dst_time < end + HOUR:
# Repeated hour
return std_time.replace(fold=1)
if std_time < start or dst_time >= end:
# Standard time
return std_time
if start <= std_time < end - HOUR:
# Daylight saving time
return dst_time
Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
Central = USTimeZone(-6, "Central", "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
请注意同时负责标准时和夏令时的 tzinfo
子类在每年两次的 DST 转换点上会出现不可避免的微妙问题。具体而言,考虑美国东部时区 (UTC -0500),它的 EDT 从三月的第二个星期天 1:59 (EST) 之后一分钟开始,并在十一月的第一天星期天 1:59 (EDT) 之后一分钟结束:
UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
当 DST 开始时(即 "start" 行),本地时钟从 1:59 跳到 3:00。 形式为 2:MM 的时间值在那一天是没有意义的,因此在 DST 开始那一天 astimezone(Eastern)
不会输出包含 hour == 2
的结果。 例如,在 2016 年春季时钟向前调整时,我们得到:
>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
... print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT
When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
astimezone()
mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then. In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times
have the fold
attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get:
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0
Note that the datetime
instances that differ only by the value of the
fold
attribute are considered equal in comparisons.
Applications that can't bear wall-time ambiguities should explicitly check the
value of the fold
attribute or avoid using hybrid
tzinfo
subclasses; there are no ambiguities when using timezone
,
or any other fixed-offset tzinfo
subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
参见
zoneinfo
The
datetime
module has a basictimezone
class (for handling arbitrary fixed offsets from UTC) and itstimezone.utc
attribute (a UTC timezone instance).
zoneinfo
为 Python 带来了 IANA时区数据库 (也被称为 Olson 数据库),推荐使用它。
- IANA 时区数据库
该时区数据库 (通常称为 tz, tzdata 或 zoneinfo) 包含大量代码和数据用来表示全球许多有代表性的地点的本地时间的历史信息。 它会定期进行更新以反映各政治实体对时区边界、UTC 差值和夏令时规则的更改。
timezone
对象¶
timezone
类是 tzinfo
的子类,它的每个实例都代表一个以与 UTC 的固定时差来定义的时区。
此类的对象不可被用于代表某些特殊地点的时区信息,这些地点在一年的不同日期会使用不同的时差,或是在历史上对民用时间进行过调整。
- class datetime.timezone(offset, name=None)¶
offset 参数必须指定为一个
timedelta
对象,表示本地时间与 UTC 的时差。 它必须严格限制于-timedelta(hours=24)
和timedelta(hours=24)
之间,否则会引发ValueError
。name 参数是可选的。 如果指定则必须为一个字符串,它将被用作
datetime.tzname()
方法的返回值。在 3.2 版本加入.
在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
- timezone.utcoffset(dt)¶
返回当
timezone
实例被构造时指定的固定值。dt 参数会被忽略。 返回值是一个
timedelta
实例,其值等于本地时间与 UTC 之间的时差。在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
- timezone.tzname(dt)¶
返回当
timezone
实例被构造时指定的固定值。如果没有在构造器中提供 name,则
tzname(dt)
所返回的名称将根据offset
值按以下规则生成。 如果 offset 为timedelta(0)
,则名称为“UTC”,否则为字符串UTC±HH:MM
,其中 ± 为offset
的正负符号,HH 和 MM 分别为表示offset.hours
和offset.minutes
的两个数码。在 3.6 版本发生变更: 由
offset=timedelta(0)
生成的名称现在是简单的'UTC'
,而不是'UTC+00:00'
。
- timezone.dst(dt)¶
总是返回
None
。
类属性:
- timezone.utc¶
UTC 时区,
timezone(timedelta(0))
。
strftime()
and strptime()
Behavior¶
date
, datetime
和 time
对象都支持 strftime(format)
方法,可用来创建由一个显式格式字符串所控制的表示时间的字符串。
相反地,datetime.strptime()
类会根据表示日期和时间的字符串和相应的格式字符串来创建一个 datetime
对象。
The table below provides a high-level comparison of strftime()
versus strptime()
:
|
|
|
---|---|---|
用法 |
根据给定的格式将对象转换为字符串 |
将字符串解析为给定相应格式的 |
方法类型 |
实例方法 |
类方法 |
方法 |
||
签名 |
|
|
strftime()
and strptime()
Format Codes¶
这些方法接受可被用于解析和格式化日期的格式代码:
>>> datetime.strptime('31/01/22 23:59:59.999999',
... '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
以下列表显示了 1989 版 C 标准所要求的全部格式代码,它们在带有标准 C 实现的所有平台上均可用。
指令 |
含意 |
示例 |
备注 |
---|---|---|---|
|
当地工作日的缩写。 |
Sun, Mon, ..., Sat
(en_US);
So, Mo, ..., Sa
(de_DE)
|
(1) |
|
本地化的星期中每日的完整名称。 |
Sunday, Monday, ...,
Saturday (en_US);
Sonntag, Montag, ...,
Samstag (de_DE)
|
(1) |
|
以十进制数显示的工作日,其中0表示星期日,6表示星期六。 |
0, 1, ..., 6 |
|
|
补零后,以十进制数显示的月份中的一天。 |
01, 02, ..., 31 |
(9) |
|
当地月份的缩写。 |
Jan, Feb, ..., Dec
(en_US);
Jan, Feb, ..., Dez
(de_DE)
|
(1) |
|
本地化的月份全名。 |
January, February,
..., December (en_US);
Januar, Februar, ...,
Dezember (de_DE)
|
(1) |
|
补零后,以十进制数显示的月份。 |
01, 02, ..., 12 |
(9) |
|
补零后,以十进制数表示的,不带世纪的年份。 |
00, 01, ..., 99 |
(9) |
|
十进制数表示的带世纪的年份。 |
0001, 0002, ..., 2013, 2014, ..., 9998, 9999 |
(2) |
|
以补零后的十进制数表示的小时(24 小时制)。 |
00, 01, ..., 23 |
(9) |
|
以补零后的十进制数表示的小时(12 小时制)。 |
01, 02, ..., 12 |
(9) |
|
本地化的 AM 或 PM 。 |
AM, PM (en_US);
am, pm (de_DE)
|
(1), (3) |
|
补零后,以十进制数显示的分钟。 |
00, 01, ..., 59 |
(9) |
|
补零后,以十进制数显示的秒。 |
00, 01, ..., 59 |
(4), (9) |
|
微秒作为一个十进制数,零填充到 6 位。 |
000000, 000001, ..., 999999 |
(5) |
|
UTC 偏移量,格式为 |
(空), +0000, -0400, +1030, +063415, -030712.345216 |
(6) |
|
时区名称(如果对象为简单型则为空字符串)。 |
(空), UTC, GMT |
(6) |
|
以补零后的十进制数表示的一年中的日序号。 |
001, 002, ..., 366 |
(9) |
|
以补零后的十进制数表示的一年中的周序号(星期日作为每周的第一天)。 在新的一年中第一个星期日之前的所有日子都被视为是在第 0 周。 |
00, 01, ..., 53 |
(7), (9) |
|
以补零后的十进制数表示的一年中的周序号(星期一作为每周的第一天)。 在新的一年中第一个星期一之前的所有日子都被视为是在第 0 周。 |
00, 01, ..., 53 |
(7), (9) |
|
本地化的适当日期和时间表示。 |
Tue Aug 16 21:30:00
1988 (en_US);
Di 16 Aug 21:30:00
1988 (de_DE)
|
(1) |
|
本地化的适当日期表示。 |
08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)
|
(1) |
|
本地化的适当时间表示。 |
21:30:00 (en_US);
21:30:00 (de_DE)
|
(1) |
|
字面的 |
% |
为了方便起见,还包括了C89标准不需要的其他一些指令。这些参数都对应于ISO 8601日期值。
指令 |
含意 |
示例 |
备注 |
---|---|---|---|
|
带有世纪的 ISO 8601 年份,表示包含大部分 ISO 星期 ( |
0001, 0002, ..., 2013, 2014, ..., 9998, 9999 |
(8) |
|
以十进制数显示的 ISO 8601 星期中的日序号,其中 1 表示星期一。 |
1, 2, ..., 7 |
|
|
以十进制数显示的 ISO 8601 星期,以星期一作为每周的第一天。 第 01 周为包含 1 月 4 日的星期。 |
01, 02, ..., 53 |
(8), (9) |
|
|
(空), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216 |
(6) |
These may not be available on all platforms when used with the strftime()
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
with the year and week number directives above. Calling strptime()
with
incomplete or ambiguous ISO 8601 directives will raise a ValueError
.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's strftime()
function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the strftime(3) documentation. There are also
differences between platforms in handling of unsupported format specifiers.
在 3.6 版本加入: 增加了 %G
, %u
和 %V
。
在 3.12 版本加入: 增加了 %:z
。
技术细节¶
Broadly speaking, d.strftime(fmt)
acts like the time
module's
time.strftime(fmt, d.timetuple())
although not all objects support a
timetuple()
method.
For the datetime.strptime()
class method, the default value is
1900-01-01T00:00:00.000
: any components not specified in the format string
will be pulled from the default value. [4]
使用 datetime.strptime(date_string, format)
等价于:
datetime(*(time.strptime(date_string, format)[0:6]))
除非格式中包含秒以下的部分或时区差值信息,它们在 datetime.strptime
中受支持但会被 time.strptime
所丢弃。
For time
objects, the format codes for year, month, and day should not
be used, as time
objects have no such values. If they're used anyway,
1900
is substituted for the year, and 1
for the month and day.
对于 date
对象,时、分、秒和微秒的格式代码不应被使用,因为 date
对象没有这些值。 如果它们被使用,则它们都将被替换为 0
。
出于相同的原因,对于包含当前区域设置字符集所无法表示的 Unicode 码位的格式字符串的处理方式也取决于具体平台。 在某些平台上这样的码位会不加修改地原样输出,而在其他平台上 strftime
则可能引发 UnicodeError
或只返回一个空字符串。
注释:
因为该格式依赖于当前语言区域,所以在假定输出值时应当仔细考虑。 字段顺序可能会有变化(例如 "month/day/year" 和 "day/month/year"),并且输出还可能包含非 ASCII 字符。
The
strptime()
method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width.在 3.2 版本发生变更: In previous versions,
strftime()
method was restricted to years >= 1900.在 3.3 版本发生变更: In version 3.2,
strftime()
method was restricted to years >= 1000.When used with the
strptime()
method, the%p
directive only affects the output hour field if the%I
directive is used to parse the hour.Unlike the
time
module, thedatetime
module does not support leap seconds.When used with the
strptime()
method, the%f
directive accepts from one to six digits and zero pads on the right.%f
is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).对于简单型对象,
%z
,%:z
和%Z
格式代码会被替换为空字符串。对于一个感知型对象而言:
%z
utcoffset()
is transformed into a string of the form±HHMM[SS[.ffffff]]
, whereHH
is a 2-digit string giving the number of UTC offset hours,MM
is a 2-digit string giving the number of UTC offset minutes,SS
is a 2-digit string giving the number of UTC offset seconds andffffff
is a 6-digit string giving the number of UTC offset microseconds. Theffffff
part is omitted when the offset is a whole number of seconds and both theffffff
and theSS
part is omitted when the offset is a whole number of minutes. For example, ifutcoffset()
returnstimedelta(hours=-3, minutes=-30)
,%z
is replaced with the string'-0330'
.
在 3.7 版本发生变更: UTC 时差不再限制为一个整数分钟值。
在 3.7 版本发生变更: When the
%z
directive is provided to thestrptime()
method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example,'+01:00:00'
will be parsed as an offset of one hour. In addition, providing'Z'
is identical to'+00:00'
.%:z
行为与
%z
相同,但在时,分和秒之间有冒号分隔符。%Z
In
strftime()
,%Z
is replaced by an empty string iftzname()
returnsNone
; otherwise%Z
is replaced by the returned value, which must be a string.strptime()
only accepts certain values for%Z
:你的机器的区域设置可以是
time.tzname
中的任何值硬编码的值
UTC
和GMT
这样生活在日本的人可用的值为
JST
,UTC
和GMT
,但可能没有EST
。 它将引发ValueError
表示无效的值。
在 3.2 版本发生变更: When the
%z
directive is provided to thestrptime()
method, an awaredatetime
object will be produced. Thetzinfo
of the result will be set to atimezone
instance.When used with the
strptime()
method,%U
and%W
are only used in calculations when the day of the week and the calendar year (%Y
) are specified.Similar to
%U
and%W
,%V
is only used in calculations when the day of the week and the ISO year (%G
) are specified in astrptime()
format string. Also note that%G
and%Y
are not interchangeable.When used with the
strptime()
method, the leading zero is optional for formats%d
,%m
,%H
,%I
,%M
,%S
,%j
,%U
,%W
, and%V
. Format%y
does require a leading zero.
备注