Python datetime.md

datetime

datetime模块包含了一些用于时间解析、格式化、计算的函数.

Times

时间值由time类来表示, Times有小时, 分, 秒和微秒属性. 以及包含时区信息. 初始化time实例的参数是可选的, 但这样的话, 你将获得初始值0(也许不是你所想要的).

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)：所有参数都是可选的。tzinfo可以是None或tzinfo子类的实例。
类属性：
time.min：可表示的最早的time，time(0, 0, 0, 0)。
time.max：可表示的最晚的time，time(23, 59, 59, 999999)。
time.resolution：不相等的time对象之间的最小可能差，即timedelta(microseconds=1)，还要注意time不支持算术操作。
time.hour：在range(24)之间。
time.minute：在range(60)之间。
time.second：在range(60)之间。
time.microsecond：在range(1000000)之间。
time.tzinfo：作为tzinfo参数传递给time构造函数的对象，如果没有传递则为None。
举例

import datetime

t = datetime.time(10, 20, 30)
print(t)
print('hour       :', t.hour)
print('minute     :', t.minute)
print('second     :', t.second)
print('microsecond:', t.microsecond)
print('tzinfo     :', t.tzinfo)

输出：

10:20:30
hour       : 10
minute     : 20
second     : 30
microsecond: 0
tzinfo     : None

一个time实例只包含时间值, 不包含日期值.

print('Earliest     :', datetime.time.min)
print('Latest       :', datetime.time.max)
print('Resolution   :', datetime.time.resolution)

类属性中的最大最小值反应了一天中的时间范围.
输出：

Earliest     : 00:00:00
Latest       : 23:59:59.999999
Resolution   : 0:00:00.000001

实际中, 如果使用浮点型作为微秒参数, 那么将产生一些警告信息.

for m in [1, 0, 0.1, 0.6]:
    try:
        print('{:02.1f} :'.format(m), datetime.time(0, 0, 0, microsecond=m))
    except TypeError as err:
        print('ERROR:', err)

输出：

1.0 : 00:00:00.000001
0.0 : 00:00:00
ERROR: integer argument expected, got float
ERROR: integer argument expected, got float

Dates

日期值可以由date类来表示, 实例有年、月、日属性, 使用data类的 today() 方法可以方便的表示出今天的日期.

class datetime.date(year, month, day)：所有的参数都是必须的。
classmethod date.today()：返回当前本地的日期。这相当于date.fromtimestamp(time.time())。
classmethod date.fromtimestamp(timestamp)：返回与POSIX时间戳对应的本地日期，例如time.time()返回的时间戳。如果时间戳超出平台C localtime()函数支持的值的范围则引发OverflowError，如果localtime()失败则引发OSError。通常限制年份在1970 到 2038之间。请注意，在时间戳中包含闰秒的非POSIX系统上，fromtimestamp()会忽略闰秒。
classmethod date.fromordinal(ordinal)：返回对应于公历序数的日期，其中第一年的一月一日为序数1。如果不满足1 <= ordinal <= date.max.toordinal()，则引发ValueError。对于任何日期d，date.fromordinal(d.toordinal()) == d。

类属性：
date.min：可表示的最早日期，date(MINYEAR, 1, 1)。
date.max：可表示最晚的日期，date(MAXYEAR, 12, 31)。
date.resolution：不相等的日期对象之间的最小可能差异，timedelta(days=1)。

实例属性（只读）：
date.year：在MINYEAR和MAXYEAR之间，包括这两个值。
date.month：在 1 到 12 之间，包括 1 和 12。
date.day：在 1 到给出的年份和月份之间的天数。

实例方法：
date.replace(year, month, day)：依据关键字参数给出的新值，返回一个新的日期。例如，如果d == date(2002, 12, 31)，那么d.replace(day=26) == 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，是星期三。
date.isoweekday()：返回一星期中的第几天，其中星期一是1，星期日是7。 例如，date(2002, 12, 4).isoweekday() == 3，是星期三。
date.isoformat()：返回以ISO 8601 格式‘YYYY-MM-DD’表示日期的字符串。例如，date(2002, 12, 4).isoformat() == '2002-12-04'。
date.ctime()：返回表示日期的字符串，例如date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'。在原生的C函数ctime()（time.ctime()调用它，但是date.ctime() 不调用它）遵守C标准的平台上，d.ctime()等效于time.ctime(time.mktime(d.timetuple()))。
date.strftime(format)：返回一个表示日期的字符串，由显式的格式字符串控制。引用小时、分钟和秒的格式代码的值将为0。
举例

today = datetime.date.today()
print(today)
print('ctime  :', today.ctime())
tt = today.timetuple()
print('tuple   : tm_year  =', tt.tm_year)
print('          tm_mon   =', tt.tm_mon)
print('          tm_mday  =', tt.tm_mday)
print('          tm_hour  =', tt.tm_hour)
print('          tm_min   =', tt.tm_min)
print('          tm_sec   =', tt.tm_sec)
print('          tm_wday  =', tt.tm_wday)
print('          tm_yday  =', tt.tm_yday)
print('          tm_isdst =', tt.tm_isdst)
print('ordinal:', today.toordinal())
print('Year   :', today.year)
print('Mon    :', today.month)
print('Day    :', today.day)

输出：

2017-07-02
ctime  : Sun Jul  2 00:00:00 2017
tuple   : tm_year  = 2017
          tm_mon   = 7
          tm_mday  = 2
          tm_hour  = 0
          tm_min   = 0
          tm_sec   = 0
          tm_wday  = 6
          tm_yday  = 183
          tm_isdst = -1
ordinal: 736512
Year   : 2017
Mon    : 7
Day    : 2

显示了函数 fromordinal() 和 fromtimestamp() 返回了不同的结果.

import datetime
import time
o = 733114
print('o               :', o)
print('fromordinal(o)  :', datetime.datetime.fromordinal(o))

t = time.time()
print('t               :', t)
print('fromtimestamp(t):', datetime.date.fromtimestamp(t))

输出:

o               : 733114
fromordinal(o)  : 2008-03-13 00:00:00
t               : 1499002982.592
fromtimestamp(t): 2017-07-02

对于一个存在的日期, 可使用replace函数可以创建出一个新的日期实例. 比如你可以改变年数, 只保留月份和日.

d1 = datetime.date(2012, 12, 31)
print('d1:', d1)
print('d1:', d1.ctime())
d2 = d1.replace(year=2008)
print('d2:', d2)
print('d2:', d2.ctime())

输出：

d1: 2012-12-31
d1: Mon Dec 31 00:00:00 2012
d2: 2008-12-31
d2: Wed Dec 31 00:00:00 2008

timedeltas

可以使用两个datetime对象的基本算法来计算未来和过去的日期，或者将一个datetime和一个时间增量组合在一起。减去日期产生一个时间增量，并且可以从一个日期中添加或减去一个时间增量来生成另一个日期。时间增量的内部值存储在几天、几秒和几微秒内。

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天。

类属性有：
timedelta.min：最小的timedelta对象，timedelta(-999999999)。
timedelta.max：最大的timedelta对象，timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)。
timedelta.resolution：不相等的timedelta对象之间的最小可能差值，timedelta(microseconds=1)。

实例属性（只读）：

属性	值
days	介于-999999999和999999999之间（包括-999999999和999999999）
seconds	介于0和86399之间（包括0和86399）
microseconds	介于0和999999之间（包括0和999999）

实例方法：
timedelta.total_seconds()：返回时间差中包含的总的秒数。等同于td / timedelta(seconds=1)。

举例

print('microseconds:', datetime.timedelta(microseconds=1))
print('milliseconds:', datetime.timedelta(milliseconds=1))
print('seconds     :', datetime.timedelta(seconds=1))
print('minutes     :', datetime.timedelta(minutes=1))
print('hours       :', datetime.timedelta(hours=1))
print('days        :', datetime.timedelta(days=1))
print('weeks       :', datetime.timedelta(weeks=1))

传递给构造函数的中间值被转换为几天、几秒和几微秒。
输出：

microseconds: 0:00:00.000001
milliseconds: 0:00:00.001000
seconds     : 0:00:01
minutes     : 0:01:00
hours       : 1:00:00
days        : 1 day, 0:00:00
weeks       : 7 days, 0:00:00

使用total_seconds()可以将一个时间增量的完整持续时间恢复为几秒。

for delta in [
                datetime.timedelta(microseconds=1),
                datetime.timedelta(milliseconds=1),
                datetime.timedelta(seconds=1),
                datetime.timedelta(minutes=1),
                datetime.timedelta(hours=1),
                datetime.timedelta(days=1),
                datetime.timedelta(weeks=1),
                ]:
    print(' {:15} = {:8} seconds'.format(str(delta), delta.total_seconds()))

输出：

 0:00:00.000001  =    1e-06 seconds
 0:00:00.001000  =    0.001 seconds
 0:00:01         =      1.0 seconds
 0:01:00         =     60.0 seconds
 1:00:00         =   3600.0 seconds
 1 day, 0:00:00  =  86400.0 seconds
 7 days, 0:00:00 = 604800.0 seconds

Date Arithmetic

举例
使用date对象的这个例子演示了使用timedelta对象来计算新的日期，并减去日期实例来产生时间增量(包括一个负的delta值)。

today = datetime.date.today()
print('Today     :', today)

one_day = datetime.timedelta(days=1)
print('One day   :', one_day)

yesterday = today - one_day
print('Yesterday :', yesterday)

tomorrow = today + one_day
print('Tomorrow  :', tomorrow)

print()
print('tomorrow - yesterday:', tomorrow - yesterday)
print('yesterday - tomorrow:', yesterday - tomorrow)

输出：

Today     : 2017-07-02
One day   : 1 day, 0:00:00
Yesterday : 2017-07-01
Tomorrow  : 2017-07-03

tomorrow - yesterday: 2 days, 0:00:00
yesterday - tomorrow: -2 days, 0:00:00

一个timedelta对象还支持整数、浮点数和其他时间增量实例的算术。

one_day = datetime.timedelta(days=1)
print('1 day     :', one_day)
print('5 days    :', one_day * 5)
print('1.5 days  :', one_day * 1.5)
print('1/4 day   :', one_day / 4)

work_day = datetime.timedelta(hours=7)
meeting_length = datetime.timedelta(hours=1)
print('meetings per day :', work_day / meeting_length)

输出：

1 day     : 1 day, 0:00:00
5 days    : 5 days, 0:00:00
1.5 days  : 1 day, 12:00:00
1/4 day   : 6:00:00
meetings per day : 7.0

Comparing Values

可以使用标准比较运算符来比较日期和时间值，以确定哪个时间更早或更晚。
举例

print('Times:')
t1 = datetime.time(12, 55, 0)
print('    t1:', t1)
t2 = datetime.time(13, 5, 0)
print('    t2:', t2)
print('    t1 < t2:', t1 < t2)

print('Dates:')
d1 = datetime.date.today()
print('    d1:', d1)
d2 = datetime.date.today() + datetime.timedelta(days=1)
print('    d2:', d2)
print('    d1 > d2:', d1 > d2)

输出：

Times:
    t1: 12:55:00
    t2: 13:05:00
    t1 < t2: True
Dates:
    d1: 2017-07-02
    d2: 2017-07-03
    d1 > d2: False

Combining Dates and Times

使用datetime类来保存包含日期和时间组件的值。与date一样，有几种方便的类方法可以从其他公共值创建datetime实例。
classmethod datetime.now(tz=None)：返回本地当前的日期和时间。如果可选参数tz为None或未指定，则这类似于today()，但如果可能，通过time.time()时间戳提供更高的精度（例如，这在提供C gettimeofday()函数的平台上是可能的）。如果tz不为None，则必须是tzinfo子类的实例，当前日期和时间将转换为tz的时区。在这种情况下，结果等效于tz.fromutc(datetime.utcnow().replace(tzinfo=tz))。
classmethod datetime.utcnow()：返回当前UTC日期和时间，其中tzinfo为None。这类似now()，但返回当前UTC日期和时间，作为一个naive的datetime对象。可以通过调用datetime.now(timezone.utc)来得到aware的当前UTC datetime。
classmethod datetime.combine(date, time)：返回一个新的datetime对象，其日期部分等于给定的date对象，其时间部分和tzinfo属性等于给定time对象。对于任何datetime对象d，d == datetime.combine(d.date(), d.timetz())。如果date是一个datetime对象，则会忽略其时间部分和tzinfo属性。
classmethod datetime.today()：返回当前本地日期时间，其中tzinfo为None。这相当于datetime.fromtimestamp(time.time())。
classmethod date.today()：返回当前本地的日期。这相当于date.fromtimestamp(time.time())。

举例

print('Now    :', datetime.datetime.now())
print('Today  :', datetime.datetime.today())
print('UTC Now:', datetime.datetime.utcnow())
print()

FIELDS = ['year', 'month', 'day', 'hour', 'minute', 'second', 'microsecond',]

d = datetime.datetime.now()
for attr in FIELDS:
    print(' {:15}: {}'.format(attr, getattr(d, attr)))

输出：

Now    : 2017-07-02 22:40:09.835000
Today  : 2017-07-02 22:40:09.835000
UTC Now: 2017-07-02 14:40:09.835000

 year           : 2017
 month          : 7
 day            : 2
 hour           : 22
 minute         : 40
 second         : 9
 microsecond    : 835000

与date一样，datetime为创建新实例提供了方便的类方法。它还包括fromordinal()和fromtimestamp()。

t = datetime.time(1, 2, 3)
print('t :', t)

d = datetime.date.today()
print('d :', d)

dt = datetime.datetime.combine(d, t)
print('dt:', dt)

输出：

t : 01:02:03
d : 2017-07-02
dt: 2017-07-02 01:02:03

Formatting and Parsing

datetime对象的默认字符串表示使用了iso-8601格式(yyymm-MM-ddthh:MM:ss.mmmmmm)。可以使用strftime()生成替代格式。

classmethod datetime.strptime(date_string, format)：返回对应于date_string的datetime，根据format进行解析。这相当于datetime(*(time.strptime(date_string, format)[0:6]))如果time.strptime()无法解析date_string和format，或者如果返回的值不是时间元组，则会引发ValueError。
datetime.strftime(format)：返回一个表示日期和时间的字符串，由显式的格式字符串控制。

举例

format = "%a %b %d %H:%M:%S %Y"

today = datetime.datetime.today()
print('ISO     :', today)
print('format(): {:%a %b %d %H:%M:%S %Y}'.format(today))

s = today.strftime(format)
print('strftime:', s)

d = datetime.datetime.strptime(s, format)
print('strptime:', d.strftime(format))

输出：

ISO     : 2017-07-02 23:14:27.446000
format(): Sun Jul 02 23:14:27 2017
strftime: Sun Jul 02 23:14:27 2017
strptime: Sun Jul 02 23:14:27 2017

strptime/strftime format codes

Symbol	Meaning	Example
%a	Abbreviated weekday name	'Wed'
%A	Full weekday name	'Wednesday'
%w	Weekday number – 0 (Sunday) through 6 (Saturday)	'3'
%d	Day of the month (zero padded)	'13'
%b	Abbreviated month name	'Jan'
%B	Full month name	'January'
%m	Month of the year	'01'
%y	Year without century	'16'
%Y	Year with century	'2016'
%H	Hour from 24-hour clock	'17'
%I	Hour from 12-hour clock	'05'
%p	AM/PM	'PM'
%M	Minutes	'00'
%S	Seconds	'00'
%f	Microseconds	'000000'
%z	UTC offset for time zone-aware objects	'-0500'
%Z	Time Zone name	'EST'
%j	Day of the year	'013'
%W	Week of the year	'02'
%c	Date and time representation for the current locale	'Wed Jan 13 17:00:00 2016'
%x	Date representation for the current locale	'01/13/16'
%X	Time representation for the current locale	'17:00:00'
%%	A literal % character	'%'

Time Zones

在datetime中，时区由tzinfo的子类表示。由于tzinfo是一个抽象的基类，所以应用程序需要定义一个子类，并为一些方法提供适当的实现以使其有用。
举例

min6 = datetime.timezone(datetime.timedelta(hours=6))
plus6 = datetime.timezone(datetime.timedelta(hours=6))
d = datetime.datetime.now(min6)

print(min6, ':', d)
print(datetime.timezone.utc, ':', d.astimezone(datetime.timezone.utc))
print(plus6, ':', d.astimezone(plus6))

d_system = d.astimezone()
print(d_system.tzinfo, '      :', d_system)

Uninx输出：

UTC+06:00 : 2017-07-02 21:32:11.492124+06:00
UTC+00:00 : 2017-07-02 15:32:11.492124+00:00
UTC+06:00 : 2017-07-02 21:32:11.492124+06:00
CST       : 2017-07-02 23:32:11.492124+08:00

URL：https://pymotw.com/3/datetime/index.html

扩展学习库：pytz