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
