datetime — Basic date and time types基本日期和时间类型

Source code: Lib/datetime.py

The datetime module supplies classes for manipulating dates and times.datetime模块提供用于操作日期和时间的类。

While date and time arithmetic is supported, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation.虽然支持日期和时间算法，但实现的重点是高效的属性提取，用于输出格式和操作。

See also

Module calendar

General calendar related functions.通用日历相关功能。

Module time

Time access and conversions.时间访问和转换。

Module zoneinfo

Concrete time zones representing the IANA time zone database.代表IANA时区数据库的具体时区。

Package dateutil

Third-party library with expanded time zone and parsing support.具有扩展时区和解析支持的第三方库。

Aware and Naive Objects感知对象和原生对象

Date and time objects may be categorized as “aware” or “naive” depending on whether or not they include timezone information.根据日期和时间对象是否包含时区信息，可以将其分类为“感知”或“原生”。

With sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, an aware object can locate itself relative to other aware objects. 通过充分了解适用的算法和政治时间调整，例如时区和夏令时信息，感知对象可以相对于其他感知对象定位自身。An aware object represents a specific moment in time that is not open to interpretation. 一个感知的对象代表了一个不可解释的特定时刻。1

A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. 原生对象包含的信息不足，无法相对于其他日期/时间对象明确定位自身。Whether a naive object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, just like it is up to the program whether a particular number represents metres, miles, or mass. 一个简单的对象是否代表协调世界时（UTC）、本地时间或其他时区的时间完全取决于程序，就像特定数字是否代表米、英里或质量取决于程序一样。Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.原生的对象很容易理解和使用，但代价是忽略了现实的某些方面。

For applications requiring aware objects, datetime and time objects have an optional time zone information attribute, tzinfo, that can be set to an instance of a subclass of the abstract tzinfo class. 对于需要感知对象的应用程序，datetime和time对象具有可选的时区信息属性tzinfo，可以将其设置为抽象tzinfo类的子类的实例。These tzinfo objects capture information about the offset from UTC time, the time zone name, and whether daylight saving time is in effect.这些tzinfo对象捕获有关与UTC时间的偏移量、时区名称以及夏令时是否生效的信息。

Only one concrete tzinfo class, the timezone class, is supplied by the datetime module. datetime模块只提供了一个具体的tzinfo类，即timezone类。The timezone class can represent simple timezones with fixed offsets from UTC, such as UTC itself or North American EST and EDT timezones. timezone类可以表示与UTC具有固定偏移量的简单时区，例如UTC本身或北美EST和EDT时区。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.世界各地的时间调整规则更具政治性，而非理性，经常发生变化，除UTC外，没有适用于所有应用程序的标准。

Constants常量

The datetime module exports the following constants:datetime模块导出以下常量：

datetime.MINYEAR

The smallest year number allowed in a date or datetime object. date对象或datetime对象中允许的最小年份数。MINYEAR is 1.是1。

datetime.MAXYEAR

The largest year number allowed in a date or datetime object. date对象或datetime对象中允许的最大年份数。MAXYEAR is 9999.是9999。

Available Types可用类型

classdatetime.date

An idealized naive date, assuming the current Gregorian calendar always was, and always will be, in effect. 一个理想的天真日期，假设当前的公历一直有效，也将永远有效。Attributes: year, month, and day.属性：year、month和day。

classdatetime.time

An idealized time, independent of any particular day, assuming that every day has exactly 24*60*60 seconds. 一个理想的时间，独立于任何一天，假设每天正好有24*60*60秒。(There is no notion of “leap seconds” here.) （这里没有“闰秒”的概念。）Attributes: hour, minute, second, microsecond, and tzinfo.属性：hour,、minute、second、microsecond和tzinfo。

classdatetime.datetime

A combination of a date and a time. 日期和时间的组合。Attributes: year, month, day, hour, minute, second, microsecond, and tzinfo.属性：year、month、day、hour,、minute、second、microsecond和tzinfo。

classdatetime.timedelta

A duration expressing the difference between two date, time, or datetime instances to microsecond resolution.以微秒分辨率表示两个date、time或datetime实例之间差异的持续时间。

classdatetime.tzinfo

An abstract base class for time zone information objects. 时区信息对象的抽象基类。These are used by the datetime and time classes to provide a customizable notion of time adjustment (for example, to account for time zone and/or daylight saving time).datetime类和time类使用它们来提供可自定义的时间调整概念（例如，考虑时区和/或夏令时）。

classdatetime.timezone

A class that implements the tzinfo abstract base class as a fixed offset from the UTC.将tzinfo抽象基类实现为UTC的固定偏移量的类。

New in version 3.2.版本3.2中新增。

Objects of these types are immutable.这些类型的对象是不可变的。

Subclass relationships:子类关系：

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Common Properties通用属性

The date, datetime, time, and timezone types share these common features:date、datetime、time和timezone类型具有以下共同特征：

  • Objects of these types are immutable.这些类型的对象是不可变的。

  • Objects of these types are hashable, meaning that they can be used as dictionary keys.这些类型的对象是可散列的，这意味着它们可以用作字典键。

  • Objects of these types support efficient pickling via the pickle module.这些类型的对象支持通过pickle模块进行有效的酸洗。

Determining if an Object is Aware or Naive确定对象是感知的还是原生的

Objects of the date type are always naive.date类型的对象总是原生的。

An object of type time or datetime may be aware or naive.类型为time或datetime的对象可能感知的或原生的。

A datetime object d is aware if both of the following hold:datetime对象d知道以下两项是否成立：

  1. d.tzinfo is not 不是None

  2. d.tzinfo.utcoffset(d) does not return 不能返回None

Otherwise, d is naive.否则，d是在原生的。

A time object t is aware if both of the following hold:如果以下两项均成立，则time对象t会意识到：

  1. t.tzinfo is not 不是None

  2. t.tzinfo.utcoffset(None) does not return 不能返回None

Otherwise, t is naive.否则，t是原生的。

The distinction between aware and naive doesn’t apply to timedelta objects.感知和原生之间的区别不适用于timedelta对象。

timedelta Objects对象

A timedelta object represents a duration, the difference between two dates or times.timedelta对象表示持续时间，即两个日期或时间之间的差。

classdatetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

All arguments are optional and default to 0. 所有参数都是可选的，默认为0。Arguments may be integers or floats, and may be positive or negative.参数可以是整数或浮点，也可以是正的或负的。

Only days, seconds and microseconds are stored internally. 内部只存储days、seconds和microseconds。Arguments are converted to those units:参数转换为以下单位：

  • A millisecond is converted to 1000 microseconds.毫秒转换为1000微秒。

  • A minute is converted to 60 seconds.一分钟转换为60秒。

  • An hour is converted to 3600 seconds.一小时转换为3600秒。

  • A week is converted to 7 days.一周转换为7天。

and days, seconds and microseconds are then normalized so that the representation is unique, with然后对天、秒和微秒进行归一化，使表示是唯一的，具有

  • 0 <= microseconds < 1000000

  • 0 <= seconds < 3600*24 (the number of seconds in one day)（一天中的秒数）

  • -999999999 <= days <= 999999999

The following example illustrates how any arguments besides days, seconds and microseconds are “merged” and normalized into those three resulting attributes:以下示例说明了如何将除days、seconds和microsoftseconds之外的任何参数“合并”并归一化为这三个结果属性：

>>> 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)

If any argument is a float and there are fractional microseconds, the fractional microseconds left over from all arguments are combined and their sum is rounded to the nearest microsecond using round-half-to-even tiebreaker. 如果任何参数是浮点且存在分数微秒，则合并所有参数剩余的分数微秒，并使用舍入半到偶数的分界符将其总和舍入到最近的微秒。If no argument is a float, the conversion and normalization processes are exact (no information is lost).如果没有参数是浮点，则转换和规范化过程是精确的（不会丢失任何信息）。

If the normalized value of days lies outside the indicated range, OverflowError is raised.如果天数的归一化值不在指示范围内，则会引发OverflowError。

Note that normalization of negative values may be surprising at first. 请注意，负值的归一化一开始可能会令人惊讶。For example:例如：

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Class attributes:类属性：

timedelta.min

The most negative timedelta object, timedelta(-999999999).最负的timedelta对象，timedelta(-999999999)。

timedelta.max

The most positive timedelta object, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).最正的timedelta对象，timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)。

timedelta.resolution

The smallest possible difference between non-equal timedelta objects, timedelta(microseconds=1).非相等的timedelta对象之间可能存在的最小差异，timedelta(microseconds=1)。

Note that, because of normalization, timedelta.max > -timedelta.min. 注意，由于标准化，timedelta.max>-timedelta.min。-timedelta.max is not representable as a timedelta object.不能表示为timedelta对象。

Instance attributes (read-only):实例属性（只读）：

Attribute属性

Value值

days

Between -999999999 and 999999999 inclusive介于-999999999和999999999之间（含）

seconds

Between 0 and 86399 inclusive介于0和86399之间（含0和86399）

microseconds

Between 0 and 999999 inclusive介于0和999999之间（含0和999999）

Supported operations:支持的操作：

Operation操作

Result结果

t1 = t2 + t3

Sum of t2 and t3. t2和t3之和。Afterwards t1-t2 == t3 and t1-t3 == t2 are true. 之后t1-t2==t3和t1-t3==t2为true。(1)

t1 = t2 - t3

Difference of t2 and t3. t2和t3之差。Afterwards t1 == t2 - t3 and t2 == t1 + t3 are true.之后t1==t2-t3和t2==t1+t3为true。 (1)(6)

t1 = t2 * i or t1 = i * t2

Delta multiplied by an integer. 增量乘以整数。Afterwards t1 // i == t2 is true, provided i != 0.之后t1//i==t2为true，前提是i!=0

In general, t1 * i == t1 * (i-1) + t1 is true. 一般来说，t1*i==t1*(i-1)+t1为true。(1)

t1 = t2 * f or t1 = f * t2

Delta multiplied by a float. 增量乘以浮点。The result is rounded to the nearest multiple of timedelta.resolution using round-half-to-even.使用半到偶数取整，将结果取整为timedelta.resolution（时间差分解）的最接近倍数。

f = t2 / t3

Division (3) of overall duration t2 by interval unit t3. 总持续时间t2除以间隔单元t3。Returns a float object.返回float对象。

t1 = t2 / f or t1 = t2 / i

Delta divided by a float or an int. 增量除以浮点或整数。The result is rounded to the nearest multiple of timedelta.resolution using round-half-to-even.使用半到偶数取整，将结果取整为timedelta.resolution（时间差分解）的最接近倍数。

t1 = t2 // i or t1 = t2 // t3

The floor is computed and the remainder (if any) is thrown away. In the second case, an integer is returned. 计算向下取整，并丢弃剩余部分（如果有）。在第二种情况下，返回一个整数。(3)

t1 = t2 % t3

The remainder is computed as a timedelta object. 余数作为timedelta（时间增量）对象计算。(3)

q, r = divmod(t1, t2)

Computes the quotient and the remainder: q = t1 // t2 (3) and r = t1 % t2. 计算商和余数：q = t1 // t2 (3)和r = t1 % t2。q is an integer and r is a timedelta object.q是整数，r是timedelta对象。

+t1

Returns a timedelta object with the same value. 返回具有相同值的timedelta对象。(2)

-t1

equivalent to timedelta(-t1.days, -t1.seconds, -t1.microseconds), and to t1* -1.相当于时timedelta（-t1.days，-t1.seconds，-t1.microseconds），和t1*-1。 (1)(4)

abs(t)

equivalent to +t when t.days >= 0, and to -t when t.days < 0. 当t.days >= 0时等于+t，当t.days<0时等于-t。(2)

str(t)

Returns a string in the form [D day[s], ][H]H:MM:SS[.UUUUUU], where D is negative for negative t.返回格式为[D day[s], ][H]H:MM:SS[.UUUUUU]的字符串，其中D表示负t。 (5)

repr(t)

Returns a string representation of the timedelta object as a constructor call with canonical attribute values.返回timedelta对象的字符串表示形式，作为具有规范属性值的构造函数调用。

Notes:笔记：

  1. This is exact but may overflow.这是准确的，但可能会溢出。

  2. This is exact and cannot overflow.这是准确的，不能溢出。

  3. Division by 0 raises ZeroDivisionError.被0除会产生ZeroDivisionError。

  4. -timedelta.max is not representable as a timedelta object.不能表示为timedelta对象。

  5. String representations of timedelta objects are normalized similarly to their internal representation. timedelta对象的字符串表示与其内部表示类似。This leads to somewhat unusual results for negative timedeltas. 这导致负时间增量的结果有些不寻常。For example:例如：

    >>> timedelta(hours=-5)
    datetime.timedelta(days=-1, seconds=68400)
    >>> print(_)
    -1 day, 19:00:00

  6. The expression t2 - t3 will always be equal to the expression t2 + (-t3) except when t3 is equal to timedelta.max; in that case the former will produce a result while the latter will overflow.表达式t2-t3始终等于表达式t2 + (-t3)，除非t3等于timedelta.max；在这种情况下，前者将产生结果，而后者将溢出。

In addition to the operations listed above, timedelta objects support certain additions and subtractions with date and datetime objects (see below).除了上面列出的操作之外，timedelta对象还支持对date和datetime对象进行某些加减运算（见下文）。

Changed in version 3.2:版本3.2中更改： Floor division and true division of a timedelta object by another timedelta object are now supported, as are remainder operations and the divmod() function. 现在支持用另一个timedelta对象对一个timedelta对象进行底除和真除，以及余数操作和divmod()函数。True division and multiplication of a timedelta object by a float object are now supported.现在支持timedelta对象与float对象的真正除法和乘法。

Comparisons of timedelta objects are supported, with some caveats.支持对timedelta对象进行比较，但有一些注意事项。

The comparisons == or != always return a bool, no matter the type of the compared object:比较==或!=无论比较对象的类型如何，始终返回bool：

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False

For all other comparisons (such as < and >), when a timedelta object is compared to an object of a different type, TypeError is raised:对于所有其他比较（例如<和>），当将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'

In Boolean contexts, a timedelta object is considered to be true if and only if it isn’t equal to timedelta(0).在布尔上下文中，timedelta对象被认为是真的，当且仅当它不等于timedelta(0)。

Instance methods:实例方法：

timedelta.total_seconds()

Return the total number of seconds contained in the duration. 返回持续时间中包含的总秒数。Equivalent to td / timedelta(seconds=1). 相当于td / timedelta(seconds=1)。For interval units other than seconds, use the division form directly (e.g. td / timedelta(microseconds=1)).对于秒以外的间隔单位，直接使用除法形式（例如td / timedelta(microseconds=1)）。

Note that for very large time intervals (greater than 270 years on most platforms) this method will lose microsecond accuracy.注意，对于非常大的时间间隔（在大多数平台上大于270年），该方法将失去微秒精度。

New in version 3.2.版本3.2中新增。

Examples of usage: 用法示例：timedelta

An additional example of normalization:规范化的另一个示例：

>>> # 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

Examples of timedelta arithmetic: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 Objects对象

A date object represents a date (year, month and day) in an idealized calendar, the current Gregorian calendar indefinitely extended in both directions.date对象表示理想日历中的日期（年、月和日），当前的公历在两个方向上无限扩展。

January 1 of year 1 is called day number 1, January 2 of year 1 is called day number 2, and so on. 第一年的1月1日称为第1天，第1年的1月2日称为第2天，依此类推。2

classdatetime.date(year, month, day)

All arguments are required. 所有参数都是必需的。Arguments must be integers, in the following ranges:参数必须是整数，范围如下：

  • MINYEAR <= year <= MAXYEAR

  • 1 <= month <= 12

  • 1 <= day <= number of days in the given month and year

If an argument outside those ranges is given, ValueError is raised.如果给定的参数超出这些范围，则会引发ValueError。

Other constructors, all class methods:其他构造函数，所有类方法：

classmethoddate.today()

Return the current local date.返回当前本地日期。

This is equivalent to date.fromtimestamp(time.time()).这相当于date.fromtimestamp(time.time())。

classmethoddate.fromtimestamp(timestamp)

Return the local date corresponding to the POSIX timestamp, such as is returned by time.time().返回与POSIX时间戳对应的本地日期，例如由time.time()返回。

This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() function, and OSError on localtime() failure. 如果时间戳超出平台C localtime()函数支持的值范围，并且在localtime()失败时出现OSError，则这可能会引发OverflowError。It’s common for this to be restricted to years from 1970 through 2038. 这通常被限制在1970年到2038年之间。Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by fromtimestamp().注意，在时间戳概念中包含闰秒的非POSIX系统上，闰秒被fromtimestamp()忽略。

Changed in version 3.3:版本3.3中更改： Raise OverflowError instead of ValueError if the timestamp is out of the range of values supported by the platform C localtime() function. 如果时间戳超出平台C localtime()函数支持的值范围，则引发OverflowError而不是ValueError。Raise OSError instead of ValueError on localtime() failure.在localtime()失败时引发OSError而不是ValueError。

classmethoddate.fromordinal(ordinal)

Return the date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1.返回与序数公历序号对应的日期，其中第1年的1月1日具有序号1。

ValueError is raised unless 1 <= ordinal <= date.max.toordinal(). 除非1 <= ordinal <= date.max.toordinal()，否则将引发ValueError。For any date d, date.fromordinal(d.toordinal()) == d.

classmethoddate.fromisoformat(date_string)

Return a date corresponding to a date_string given in the format YYYY-MM-DD:返回与格式为YYYY-MM-DD的日期字符串相对应的date：

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)

This is the inverse of date.isoformat(). 这与date.isoformat()相反。It only supports the format YYYY-MM-DD.它只支持YYYY-MM-DD格式。

New in version 3.7.版本3.7中新增。

classmethoddate.fromisocalendar(year, week, day)

Return a date corresponding to the ISO calendar date specified by year, week and day. 返回与年、周和日指定的ISO日历日期相对应的date。This is the inverse of the function date.isocalendar().这是函数date.isocalendar()的逆函数。

New in version 3.8.版本3.8中新增。

Class attributes:类属性：

date.min

The earliest representable date, date(MINYEAR, 1, 1).最早的可代表日期，date(MINYEAR, 1, 1)。

date.max

The latest representable date, date(MAXYEAR, 12, 31).最新的可代表日期，date(MAXYEAR, 12, 31)。

date.resolution

The smallest possible difference between non-equal date objects, timedelta(days=1).非相等日期对象之间可能存在的最小差异，timedelta(days=1)。

Instance attributes (read-only):实例属性（只读）：

date.year

Between MINYEAR and MAXYEAR inclusive.在MINYEAR和MAXYEAR之间（含MINYEAR和MAXYEAR）。

date.month

Between 1 and 12 inclusive.介于1和12之间（含1和12）。

date.day

Between 1 and the number of days in the given month of the given year.介于1和给定年份给定月份的天数之间。

Supported operations:支持的操作：

Operation操作

Result结果

date2 = date1 + timedelta

date2 is timedelta.days days removed from date1. date2是从date1中删除的timedelta.days天。(1)

date2 = date1 - timedelta

Computes date2 such that date2 + timedelta == date1.计算date2，使date2+timedelta==date1。 (2)

timedelta = date1 - date2

(3)

date1 < date2

date1 is considered less than date2 when date1 precedes date2 in time.当date1在时间上先于date2时，date1被视为小于date2。 (4)

Notes:笔记：

  1. date2 is moved forward in time if timedelta.days > 0, or backward if timedelta.days < 0. 如果timedelta.days > 0，则date2在时间上向前移动，如果 timedelta.days < 0，则向后移动。Afterward date2 - date1 == timedelta.days. 之后的date2 - date1 == timedelta.days。timedelta.seconds and timedelta.microseconds are ignored. timedelta.seconds和timedelta.microseconds被忽略。OverflowError is raised if date2.year would be smaller than MINYEAR or larger than MAXYEAR.如果date2.year小于MINYEAR或大于MAXYEAR，则会引发OverflowError。

  2. timedelta.seconds and timedelta.microseconds are ignored.timedelta.seconds和timedelta.microseconds被忽略。

  3. This is exact, and cannot overflow. 这是准确的，不能溢出。timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after.timedelta.seconds和timedelta.microseconds为0，date2 + timedelta == date1之后。

  4. In other words, date1 < date2 if and only if date1.toordinal() < date2.toordinal(). 换句话说，date1 < date2当且仅当date1.toordinal() < date2.toordinal()。Date comparison raises TypeError if the other comparand isn’t also a date object. 如果另一个比较对象不是date对象，则日期比较会引发TypeError。However, NotImplemented is returned instead if the other comparand has a timetuple() attribute. 但是，如果另一个比较项具有timetuple()属性，则返回NotImplemented。This hook gives other kinds of date objects a chance at implementing mixed-type comparison. 这个钩子为其他类型的日期对象提供了实现混合类型比较的机会。If not, when a date object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. 如果不是，则当将date对象与不同类型的对象进行比较时，会引发TypeError，除非比较为==或!=。The latter cases return False or True, respectively.后一种情况分别返回False或True。

In Boolean contexts, all date objects are considered to be true.在布尔上下文中，所有date对象都被视为true。

Instance methods:实例方法：

date.replace(year=self.year, month=self.month, day=self.day)

Return a date with the same value, except for those parameters given new values by whichever keyword arguments are specified.返回具有相同值的日期，但通过指定的关键字参数赋予新值的参数除外。

Example:例子：

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
date.timetuple()

Return a time.struct_time such as returned by time.localtime().返回time.struct_time，例如由time.localtime()返回的时间。

The hours, minutes and seconds are 0, and the DST flag is -1.小时、分钟和秒为0，DST标志为-1。

d.timetuple() is equivalent to:相当于：

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

where yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 is the day number within the current year starting with 1 for January 1st.其中yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1是当前年份内的天数，从1开始表示1月1日。

date.toordinal()

Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 has ordinal 1. 返回日期的序数，其中第1年的1月1日具有序数1。For any date object d, date.fromordinal(d.toordinal()) == d.对于任何date对象d，date.fromordinal(d.toordinal()) == d。

date.weekday()

Return the day of the week as an integer, where Monday is 0 and Sunday is 6. 以整数形式返回一周中的某一天，其中周一为0，周日为6。For example, date(2002, 12, 4).weekday() == 2, a Wednesday. 例如，date(2002, 12, 4).weekday() == 2，周三。See also isoweekday().另请参见isoweekday()。

date.isoweekday()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7. 以整数形式返回一周中的某一天，其中周一为1，周日为7。For example, date(2002, 12, 4).isoweekday() == 3, a Wednesday. 例如，date(2002, 12, 4).isoweekday() == 3，周三。See also weekday(), isocalendar().

date.isocalendar()

Return a named tuple object with three components: year, week and weekday.返回包含三个组件的命名元组对象：year、week和weekday。

The ISO calendar is a widely used variant of the Gregorian calendar. ISO日历是广泛使用的公历变体。3

The ISO year consists of 52 or 53 full weeks, and where a week starts on a Monday and ends on a Sunday. ISO年由52或53个整周组成，其中一周从周一开始，到周日结束。The first week of an ISO year is the first (Gregorian) calendar week of a year containing a Thursday. ISO年的第一周是一年中包含星期四的第一个（公历）日历周。This is called week number 1, and the ISO year of that Thursday is the same as its Gregorian year.这被称为第1周，该星期四的ISO年与其公历年相同。

For example, 2004 begins on a Thursday, so the first week of ISO year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004:例如，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)

Changed in version 3.9:版本3.9中更改： Result changed from a tuple to a named tuple.结果从元组更改为命名元组。

date.isoformat()

Return a string representing the date in ISO 8601 format, YYYY-MM-DD:返回以ISO 8601格式YYYY-MM-DD表示日期的字符串：

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

This is the inverse of date.fromisoformat().这与date.fromisoformat()相反。

date.__str__()

For a date d, str(d) is equivalent to d.isoformat().对于日期d，str(d)等价于d.isoformat()。

date.ctime()

Return a string representing the date:返回表示日期的字符串：

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() is equivalent to:相当于：

time.ctime(time.mktime(d.timetuple()))

on platforms where the native C ctime() function (which time.ctime() invokes, but which date.ctime() does not invoke) conforms to the C standard.在本机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. 引用小时、分钟或秒的格式代码将显示0值。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

date.__format__(format)

Same as date.strftime(). 与date.strftime()相同。This makes it possible to specify a format string for a date object in formatted string literals and when using str.format(). 这使得在使用strformat()时，可以在格式化字符串文字中为date对象指定格式字符串。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

Examples of Usage: 用法示例：date

Example of counting days to an event:计算活动天数的示例：

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

More examples of working with date:使用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 Objects对象

A datetime object is a single object containing all the information from a date object and a time object.datetime对象是包含date对象和time对象的所有信息的单个对象。

Like a date object, datetime assumes the current Gregorian calendar extended in both directions; like a time object, datetime assumes there are exactly 3600*24 seconds in every day.像date对象一样，datetime假设当前公历在两个方向上扩展；与time对象一样，datetime假设每天正好有3600*24秒。

Constructor:构造函数：

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

The year, month and day arguments are required. year、month和day参数是必需的。tzinfo may be None, or an instance of a tzinfo subclass. tzinfo可以是None，也可以是tzinfo子类的实例。The remaining arguments must be integers in the following ranges:其余参数必须是以下范围内的整数：

  • MINYEAR <= year <= MAXYEAR,

  • 1 <= month <= 12,

  • 1 <= day <= number of days in the given month and year,

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

If an argument outside those ranges is given, ValueError is raised.如果给定的参数超出这些范围，则会引发ValueError。

New in version 3.6.版本3.6中新增。Added the fold argument.添加了fold参数。

Other constructors, all class methods:其他构造函数，所有类方法：

classmethoddatetime.today()

Return the current local datetime, with tzinfo None.返回当前本地日期时间，tzinfo None。

Equivalent to:相当于：

datetime.fromtimestamp(time.time())

See also now(), fromtimestamp().另请参见now()，fromtimestamp()。

This method is functionally equivalent to now(), but without a tz parameter.该方法在功能上等价于now()，但没有tz参数。

classmethoddatetime.now(tz=None)

Return the current local date and time.返回当前本地日期和时间。

If optional argument tz is None or not specified, this is like today(), but, if possible, supplies more precision than can be gotten from going through a time.time() timestamp (for example, this may be possible on platforms supplying the C gettimeofday() function).如果可选参数tz为None或未指定，则类似于today()，但如果可能，它提供的精度比通过time.time()时间戳获得的精度更高（例如，在提供C gettimeofday()函数的平台上可能实现）。

If tz is not None, it must be an instance of a tzinfo subclass, and the current date and time are converted to tz’s time zone.如果tz不是None，则它必须是tzinfo子类的实例，并且当前日期和时间转换为tz的时区。

This function is preferred over today() and utcnow().此函数优于today()和utcnow()。

classmethoddatetime.utcnow()

Return the current UTC date and time, with tzinfo None.返回当前UTC日期和时间，tzinfo None。

This is like now(), but returns the current UTC date and time, as a naive datetime object. 这类似于now()，但返回当前UTC日期和时间，作为原始datetime对象。An aware current UTC datetime can be obtained by calling datetime.now(timezone.utc). 可以通过调用datetime.now(timezone.utc)获得有意识的当前UTC日期时间。See also now().请参见now()。

Warning

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC. 由于许多datetime方法将原生datetime对象视为本地时间，因此首选使用感知datetime以UTC表示时间。As such, the recommended way to create an object representing the current time in UTC is by calling datetime.now(timezone.utc).因此，创建以UTC表示当前时间的对象的推荐方法是调用datetime.now(timezone.utc)。

classmethoddatetime.fromtimestamp(timestamp, tz=None)

Return the local date and time corresponding to the POSIX timestamp, such as is returned by time.time(). 返回与POSIX时间戳对应的本地日期和时间，例如由time.time()返回。If optional argument tz is None or not specified, the timestamp is converted to the platform’s local date and time, and the returned datetime object is naive.如果可选参数tz为None或未指定，则时间戳将转换为平台的本地日期和时间，并且返回的datetime对象是原生的。

If tz is not None, it must be an instance of a tzinfo subclass, and the timestamp is converted to tz’s time zone.如果tz不是None，则它必须是tzinfo子类的实例，并且时间戳转换为tz的时区。

fromtimestamp() may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. 如果时间戳超出平台C localtime()或gmtime()函数支持的值范围，并且localtime()或gmtime()失败时出现OSError，则fromtimestamp()可能会引发OverflowError。It’s common for this to be restricted to years in 1970 through 2038. 这通常被限制在1970年到2038年。Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by fromtimestamp(), and then it’s possible to have two timestamps differing by a second that yield identical datetime objects. 注意，在时间戳概念中包含闰秒的非POSIX系统上，fromtimestamp()忽略闰秒，然后可能有两个相差一秒的时间戳，从而生成相同的datetime对象。This method is preferred over utcfromtimestamp().此方法优于utcfromtimestamp()。

Changed in version 3.3:版本3.3中更改： Raise OverflowError instead of ValueError if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions. 如果时间戳超出平台C localtime()或gmtime()函数支持的值范围，则引发OverflowError而不是ValueError。Raise OSError instead of ValueError on localtime() or gmtime() failure.在localtime()或gmtime()失败时，引发OSError而不是ValueError。

Changed in version 3.6:版本3.6中更改： fromtimestamp() may return instances with fold set to 1.可以返回fold设置为1的实例。

classmethoddatetime.utcfromtimestamp(timestamp)

Return the UTC datetime corresponding to the POSIX timestamp, with tzinfo None. 返回与POSIX时间戳对应的UTCdatetime，tzinfo None。(The resulting object is naive.)（生成的对象是幼稚的。）

This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C gmtime() function, and OSError on gmtime() failure. 如果时间戳超出平台C gmtime()函数支持的值范围，并且在gmtime()失败时出现OSError，则这可能会引发OverflowError。It’s common for this to be restricted to years in 1970 through 2038.这通常被限制在1970年到2038年。

To get an aware datetime object, call fromtimestamp():要获取感知的datetime对象，请调用fromtimestamp()：

datetime.fromtimestamp(timestamp, timezone.utc)

On the POSIX compliant platforms, it is equivalent to the following expression:在兼容POSIX的平台上，它等效于以下表达式：

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

except the latter formula always supports the full years range: between MINYEAR and MAXYEAR inclusive.但后一个公式始终支持完整的年份范围：MINYEAR和MAXYEAR之间（含MINYEAR和MAXYEAR）。

Warning

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC. 由于许多datetime方法将原始datetime对象视为本地时间，因此首选使用感知datetime以UTC表示时间。As such, the recommended way to create an object representing a specific timestamp in UTC is by calling datetime.fromtimestamp(timestamp, tz=timezone.utc).因此，在UTC中创建表示特定时间戳的对象的推荐方法是调用datetime.fromtimestamp(timestamp, tz=timezone.utc)。

Changed in version 3.3:版本3.3中更改： Raise OverflowError instead of ValueError if the timestamp is out of the range of values supported by the platform C gmtime() function. 如果时间戳超出平台C gmtime()函数支持的值范围，则引发OverflowError而不是ValueError。Raise OSError instead of ValueError on gmtime() failure.在gmtime()失败时引发OSError而不是ValueError。

classmethoddatetime.fromordinal(ordinal)

Return the datetime corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. 返回与序数公历序号对应的datetime，其中第1年的1月1日具有序号1。ValueError is raised unless 1 <= ordinal <= datetime.max.toordinal(). 除非1 <= ordinal <= datetime.max.toordinal()，否则会引发ValueError。The hour, minute, second and microsecond of the result are all 0, and tzinfo is None.结果的小时、分钟、秒和微秒均为0，而tzinfo为None。

classmethoddatetime.combine(date, time, tzinfo=self.tzinfo)

Return a new datetime object whose date components are equal to the given date object’s, and whose time components are equal to the given time object’s. 返回一个新的datetime对象，其日期组件等于给定的date对象，其时间组件等于给定的时间对象。If the tzinfo argument is provided, its value is used to set the tzinfo attribute of the result, otherwise the tzinfo attribute of the time argument is used.如果提供了tzinfo参数，则其值用于设置结果的tzinfo属性，否则使用time参数的tzinfo属性。

For any datetime object d, d == datetime.combine(d.date(), d.time(), d.tzinfo). 对于任何datetime对象d，d == datetime.combine(d.date(), d.time(), d.tzinfo)。If date is a datetime object, its time components and tzinfo attributes are ignored.如果date是datetime对象，则忽略其时间组件和tzinfo属性。

Changed in version 3.6:版本3.6中更改： Added the tzinfo argument.添加了tzinfo参数。

classmethoddatetime.fromisoformat(date_string)

Return a datetime corresponding to a date_string in one of the formats emitted by date.isoformat() and datetime.isoformat().以date.isoformat()和datetime.isoformat()发出的格式之一返回与date_string相对应的datetime。

Specifically, this function supports strings in the format:具体来说，此函数支持以下格式的字符串：

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

where * can match any single character.其中*可以匹配任何单个字符。

Caution

This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse operation of datetime.isoformat(). 这不支持解析任意ISO 8601字符串-它仅用于datetime.isoformat()的反向操作。A more full-featured ISO 8601 parser, dateutil.parser.isoparse is available in the third-party package dateutil.第三方软件包dateutil中提供了功能更为全面的ISO 8601解析器dateutil.parser.isoparse。

Examples:示例：

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
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-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)))

New in version 3.7.版本3.7中新增。

classmethoddatetime.fromisocalendar(year, week, day)

Return a datetime corresponding to the ISO calendar date specified by year, week and day. 返回与按年、周和日指定的ISO日历日期相对应的datetime。The non-date components of the datetime are populated with their normal default values. datetime的非日期组件由其正常默认值填充。This is the inverse of the function datetime.isocalendar().这与函数datetime.isocalendar()相反。

New in version 3.8.版本3.8中新增。

classmethoddatetime.strptime(date_string, format)

Return a datetime corresponding to date_string, parsed according to format.返回date_string对应的datetime，根据format进行解析。

This is equivalent to:这相当于：

datetime(*(time.strptime(date_string, format)[0:6]))

ValueError is raised if the date_string and format can’t be parsed by time.strptime() or if it returns a value which isn’t a time tuple. 如果date_string和格式不能由time.strptime()解析，或者返回的值不是时间元组，则会引发ValueError。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

Class attributes:类属性：

datetime.min

The earliest representable datetime, datetime(MINYEAR, 1, 1, tzinfo=None).最早的可表示的datetime，即datetime(MINYEAR, 1, 1, tzinfo=None)。

datetime.max

The latest representable datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).最新可表示的datetime，即datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)。

datetime.resolution

The smallest possible difference between non-equal datetime objects, timedelta(microseconds=1).非相等datetime对象之间可能存在的最小差异，timedelta(microseconds=1)。

Instance attributes (read-only):实例属性（只读）：

datetime.year

Between MINYEAR and MAXYEAR inclusive.在MINYEAR和MAXYEAR之间（含MINYEAR和MAXYEAR）。

datetime.month

Between 1 and 12 inclusive.介于1和12之间（含1和12）。

datetime.day

Between 1 and the number of days in the given month of the given year.介于1和给定年份给定月份的天数之间。

datetime.hour

In range(24).在range(24)内。

datetime.minute

In range(60).在range(60)内。

datetime.second

In range(60).在range(60)内。

datetime.microsecond

In range(1000000).在range(1000000)内。

datetime.tzinfo

The object passed as the tzinfo argument to the datetime constructor, or None if none was passed.对象作为tzinfo参数传递给datetime构造函数，如果没有传递，则为None。

datetime.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. 在[0, 1]中。用于在重复间隔期间消除墙壁时间的歧义。(A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) （当时钟在夏令时结束时回滚，或当当前区域的UTC偏移因政治原因减少时，会出现重复间隔。）The value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.值0(1)表示具有相同壁时间表示的两个力矩中的较早（较晚）时刻。

New in version 3.6.版本3.6中新增。

Supported operations:支持的操作：

Operation操作

Result结果

datetime2 = datetime1 + timedelta

(1)

datetime2 = datetime1 - timedelta

(2)

timedelta = datetime1 - datetime2

(3)

datetime1 < datetime2

Compares datetime to datetime.比较datetime和datetime。 (4)

  1. datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if timedelta.days < 0. datetime2是从datetime1中删除的timedelta的持续时间，如果timedelta.days>0，则向前移动，如果timedelta.days<0，则向后移动。The result has the same tzinfo attribute as the input datetime, and datetime2 - datetime1 == timedelta after. 结果具有与输入datetime相同的tzinfo属性，并且之后datetime2-datetime1==timedelta。OverflowError is raised if datetime2.year would be smaller than MINYEAR or larger than MAXYEAR. 如果datetime2.year小于MINYEAR或大于MAXYEAR，则会引发溢出错误。Note that no time zone adjustments are done even if the input is an aware object.注意，即使输入是感知对象，也不会进行时区调整。

  2. Computes the datetime2 such that datetime2 + timedelta == datetime1. 计算datetime2，使datetime2 + timedelta == datetime1。As for addition, the result has the same tzinfo attribute as the input datetime, and no time zone adjustments are done even if the input is aware.此外，结果与输入datetime具有相同的tzinfo属性，即使输入是已知的，也不会进行时区调整。

  3. Subtraction of a datetime from a datetime is defined only if both operands are naive, or if both are aware. 只有当两个操作数都是纯操作数或两者都知道时，才定义从datetime减去datetime。If one is aware and the other is naive, TypeError is raised.如果一个是感知的，另一个是天真的，则会引发TypeError。

    If both are naive, or both are aware and have the same tzinfo attribute, the tzinfo attributes are ignored, and the result is a timedelta object t such that datetime2 + t == datetime1. 如果两者都是原生的，或者两者都知道并且具有相同的tzinfo属性，则忽略tzinfo属性，结果是一个timedelta对象t，使得datetime2+t==datetime1。No time zone adjustments are done in this case.在这种情况下，不会进行时区调整。

    If both are aware and have different tzinfo attributes, a-b acts as if a and b were first converted to naive UTC datetimes first. 如果两者都知道并且具有不同的tzinfo属性，则a-b的行为就像a和b首先转换为原生UTC日期时间一样。The result is (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) except that the implementation never overflows.结果是(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())，但实现从不溢出。

  4. datetime1 is considered less than datetime2 when datetime1 precedes datetime2 in time.当datetime1在时间上先于datetime2时，datetime1被认为小于datetime2。

    If one comparand is naive and the other is aware, TypeError is raised if an order comparison is attempted. 如果一个比较对象是原始的，而另一个是已知的，则如果尝试进行顺序比较，则会引发TypeError。For equality comparisons, naive instances are never equal to aware instances.对于相等比较，原始实例永远不会等于感知实例。

    If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base datetimes are compared. 如果两个比较对象都知道，并且具有相同的tzinfo属性，则忽略公共tzinfo属性，并比较基准日期时间。If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()).如果两个比较变量都知道并且具有不同的tzinfo属性，则首先通过减去其UTC偏移量（从self.utcoffset()获得）来调整比较变量。

    Changed in version 3.3:版本3.3中更改： Equality comparisons between aware and naive datetime instances don’t raise TypeError.感知和原生datetime实例之间的相等性比较不会引发TypeError。

    Note

    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 a datetime object. 为了防止比较退回到比较对象地址的默认方案，如果另一个比较对象不是datetime对象，则datetime比较通常会引发TypeError。However, NotImplemented is returned instead if the other comparand has a timetuple() attribute. 但是，如果另一个比较项具有timetuple()属性，则返回NotImplemented。This hook gives other kinds of date objects a chance at implementing mixed-type comparison. 这个钩子为其他类型的日期对象提供了实现混合类型比较的机会。If not, when a datetime object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. 如果不是，则当将datetime对象与不同类型的对象进行比较时，会引发TypeError，除非比较为==或!=。The latter cases return False or True, respectively.后一种情况分别返回False或True。

Instance methods:

datetime.date()

Return date object with same year, month and day.返回具有相同年、月和日的date对象。

datetime.time()

Return time object with same hour, minute, second, microsecond and fold. 返回具有相同小时、分钟、秒、微秒和倍数的time对象。tzinfo is None. 是None。See also method timetz().另请参见方法timetz()。

Changed in version 3.6:版本3.6中更改： The fold value is copied to the returned time object.将折叠值复制到返回的time对象。

datetime.timetz()

Return time object with same hour, minute, second, microsecond, fold, and tzinfo attributes. 返回具有相同小时、分钟、秒、微秒、折叠和tzinfo属性的time对象。See also method time().另请参见方法time()。

Changed in version 3.6:版本3.6中更改： The fold value is copied to the returned time object.将折叠值复制到返回的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)

Return a datetime with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. 返回具有相同属性的datetime，但通过指定的关键字参数赋予新值的属性除外。Note that tzinfo=None can be specified to create a naive datetime from an aware datetime with no conversion of date and time data.请注意，可以指定tzinfo=None以从已知日期时间创建原始日期时间，而不转换日期和时间数据。

New in version 3.6.版本3.6中新增。Added the fold argument.添加了fold参数。

datetime.astimezone(tz=None)

Return a datetime object with new tzinfo attribute tz, adjusting the date and time data so the result is the same UTC time as self, but in tz’s local time.返回一个带有新tzinfo属性tz的datetime对象，调整日期和时间数据，使结果为与self相同的UTC时间，但为tz的本地时间。

If provided, tz must be an instance of a tzinfo subclass, and its utcoffset() and dst() methods must not return None. 如果提供，tz必须是tzinfo子类的实例，其utcoffset()和dst()方法不得返回无。If self is naive, it is presumed to represent time in the system timezone.如果self是原生的，则假定它表示系统时区中的时间。

If called without arguments (or with tz=None) the system local timezone is assumed for the target timezone. 如果在没有参数的情况下调用（或在tz=None的情况下调用），则假设目标时区为系统本地时区。The .tzinfo attribute of the converted datetime instance will be set to an instance of timezone with the zone name and offset obtained from the OS.转换后的timezone实例的.tzinfo属性将设置为时区实例，其中包含从操作系统获得的区域名称和偏移量。

If self.tzinfo is tz, self.astimezone(tz) is equal to self: no adjustment of date or time data is performed. 如果self.tzinfo是tz，则self.astimezone(tz)等于self：不执行日期或时间数据的调整。Else the result is local time in the timezone tz, representing the same UTC time as self: after astz = dt.astimezone(tz), astz - astz.utcoffset() will have the same date and time data as dt - dt.utcoffset().否则，结果是时区tz中的本地时间，表示与self相同的UTC时间：在astz = dt.astimezone(tz)之后，astz - astz.utcoffset()将具有与dt - dt.utcoffset()相同的日期和时间数据。

If you merely want to attach a time zone object tz to a datetime dt without adjustment of date and time data, use dt.replace(tzinfo=tz). 如果只想将时区对象tz附加到日期时间dt，而不调整日期和时间数据，请使用dt.replace(tzinfo=tz)。If you merely want to remove the time zone object from an aware datetime dt without conversion of date and time data, use dt.replace(tzinfo=None).如果您只想在不转换日期和时间数据的情况下从感知日期时间dt中删除时区对象，请使用dt.replace(tzinfo=None)。

Note that the default tzinfo.fromutc() method can be overridden in a tzinfo subclass to affect the result returned by astimezone(). 请注意，可以在tzinfo子类中重写默认的tzinfo.fromutc()方法，以影响astimezone()返回的结果。Ignoring error cases, astimezone() acts like:忽略错误情况，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)

Changed in version 3.3:版本3.3中更改： tz now can be omitted.现在可以省略。

Changed in version 3.6:版本3.6中更改： The astimezone() method can now be called on naive instances that are presumed to represent system local time.现在可以在假定代表系统本地时间的原始实例上调用astimezone()方法。

datetime.utcoffset()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(self), and raises an exception if the latter doesn’t return None or a timedelta object with magnitude less than one day.如果tzinfo为None，则返回None，否则返回self.tzinfo.utcoffset(self)，如果后者不返回None或幅值小于一天的timedelta对象，则引发异常。

Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

datetime.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(self), and raises an exception if the latter doesn’t return None or a timedelta object with magnitude less than one day.如果tzinfo为None，则返回None，否则返回self.tzinfo.dst(self)，如果后者不返回None或幅值小于一天的timedelta对象，则引发异常。

Changed in version 3.7:版本3.7中更改： The DST offset is not restricted to a whole number of minutes.DST偏移量不限于整数分钟。

datetime.tzname()

If tzinfo is None, returns None, else returns self.tzinfo.tzname(self), raises an exception if the latter doesn’t return None or a string object,如果tzinfo为None，则返回None，否则返回self.tzinfo.tzname(self)，如果后者不返回None或string对象，则引发异常，

datetime.timetuple()

Return a time.struct_time such as returned by time.localtime().返回time.struct_time，例如由time.localtime()返回的时间。

d.timetuple() is equivalent to:相当于：

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 with 1 for January 1st. 其中yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1是当前年份内的天数，从1开始表示1月1日。The tm_isdst flag of the result is set according to the dst() method: tzinfo is None or dst() returns None, tm_isdst is set to -1; else if dst() returns a non-zero value, tm_isdst is set to 1; else tm_isdst is set to 0.根据dst()方法设置结果的tm_isdst标志：tzinfo为None或dst()返回None，tm_isdst设置为-1；否则，如果dst()返回非零值，则tm_isdst设置为1；否则tm_isdst设置为0。

datetime.utctimetuple()

If datetime instance d is naive, this is the same as d.timetuple() except that tm_isdst is forced to 0 regardless of what d.dst() returns. 如果datetime实例d是原生的，则这与d.timetuple()相同，只是无论d.dst()返回什么，tm_isdst都被强制为0。DST is never in effect for a UTC time.在UTC时间内，DST从未生效。

If d is aware, d is normalized to UTC time, by subtracting d.utcoffset(), and a time.struct_time for the normalized time is returned. 如果d是感知的，则通过减去d.utcofset()，将d归一化为UTC时间，并返回归一化时间的time.struct_time。tm_isdst is forced to 0. tm_isdst强制为0。Note that an OverflowError may be raised if d.year was MINYEAR or MAXYEAR and UTC adjustment spills over a year boundary.请注意，如果d.year为MINYEAR或MAXYEAR，并且UTC调整溢出超过一年边界，则可能会引起溢出。

Warning

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC; as a result, using utcfromtimetuple may give misleading results. 由于许多datetime方法将原始datetime对象视为本地时间，因此首选使用感知datetime以UTC表示时间；因此，使用utcfromtimetuple可能会产生误导性的结果。If you have a naive datetime representing UTC, use datetime.replace(tzinfo=timezone.utc) to make it aware, at which point you can use datetime.timetuple().如果您有一个表示UTC的原始datetime，请使用datetime.replace(tzinfo=timezone.utc)使其知道，此时您可以使用datetime.timetuple()。

datetime.toordinal()

Return the proleptic Gregorian ordinal of the date. 返回日期的序数。The same as self.date().toordinal().与self.date().toordinal()相同。

datetime.timestamp()

Return POSIX timestamp corresponding to the datetime instance. 返回datetime实例对应的POSIX时间戳。The return value is a float similar to that returned by time.time().返回值是一个类似于time.time()返回的float。

Naive datetime instances are assumed to represent local time and this method relies on the platform C mktime() function to perform the conversion. 假设原始datetime实例表示本地时间，该方法依赖于平台C mktime()函数来执行转换。Since datetime supports wider range of values than mktime() on many platforms, this method may raise OverflowError for times far in the past or far in the future.由于datetime在许多平台上支持比mktime()更广泛的值范围，因此该方法可能会在过去或未来的很长时间内引发OverflowError。

For aware datetime instances, the return value is computed as:对于感知datetime实例，返回值计算为：

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

New in version 3.3.版本3.3中新增。

Changed in version 3.6:版本3.6中更改： The timestamp() method uses the fold attribute to disambiguate the times during a repeated interval.timestamp()方法使用fold属性来消除重复间隔期间的时间歧义。

Note

There is no method to obtain the POSIX timestamp directly from a naive datetime instance representing UTC time. 没有直接从表示UTC时间的原始datetime实例获取POSIX时间戳的方法。If your application uses this convention and your system timezone is not set to UTC, you can obtain the POSIX timestamp by supplying tzinfo=timezone.utc:如果应用程序使用此约定，并且系统时区未设置为UTC，则可以通过提供tzinfo=timezone.utc来获取POSIX时间戳：

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

or by calculating the timestamp directly:或者直接计算时间戳：

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
datetime.weekday()

Return the day of the week as an integer, where Monday is 0 and Sunday is 6. 以整数形式返回一周中的某一天，其中周一为0，周日为6。The same as self.date().weekday(). 与self.date().weekday()相同。See also isoweekday().另请参见isoweekday()。

datetime.isoweekday()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7. 以整数形式返回一周中的某一天，其中周一为1，周日为7。The same as self.date().isoweekday(). 与self.date().isoweekday()相同。See also weekday(), isocalendar().另请参见weekday()、isocalendar()。

datetime.isocalendar()

Return a named tuple with three components: year, week and weekday. 返回包含三个组件的命名元组：year、week和weekday。The same as self.date().isocalendar().与self.date().isocalendar()相同。

datetime.isoformat(sep='T', timespec='auto')

Return a string representing the date and time in ISO 8601 format:返回表示ISO 8601格式的日期和时间的字符串：

If utcoffset() does not return None, a string is appended, giving the UTC offset:如果utcoffset()不返回None，则会追加一个字符串，给出utcoffset()：

Examples:示例：

>>> 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'

The optional argument sep (default 'T') is a one-character separator, placed between the date and time portions of the result. 可选参数sep（默认值'T'）是一个单字符分隔符，位于结果的日期和时间部分之间。For example:例如：

>>> 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'

The optional argument timespec specifies the number of additional components of the time to include (the default is 'auto'). 可选参数timespec指定要包括的时间的其他组件的数量（默认值为'auto'）。It can be one of the following:它可以是以下之一：

  • 'auto': Same as 'seconds' if microsecond is 0, same as 'microseconds' otherwise.：如果microsecond为0，则与'seconds'相同，否则与'microseconds'相同。

  • 'hours': Include the hour in the two-digit HH format.：包括两位数HH格式的hour。

  • 'minutes': Include hour and minute in HH:MM format.：以HH:MM格式包括hour和minute。

  • 'seconds': Include hour, minute, and second in HH:MM:SS format.：以HH:MM:SS格式包括hour、minute和second。

  • 'milliseconds': Include full time, but truncate fractional second part to milliseconds. ：包括完整时间，但将分数秒部分截断为毫秒。HH:MM:SS.sss format.HH:MM:SS.sss格式。

  • 'microseconds': Include full time in HH:MM:SS.ffffff format.：包括HH:MM:SS.ffffff格式的完整时间。

Note

Excluded time components are truncated, not rounded.排除的时间分量被截断，而不是四舍五入。

ValueError will be raised on an invalid timespec argument:将在无效的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'

New in version 3.6.版本3.6中新增。Added the timespec argument.添加了timespec参数。

datetime.__str__()

For a datetime instance d, str(d) is equivalent to d.isoformat(' ').对于datetime实例d，str(d)等价于d.isoformat(' ')。

datetime.ctime()

Return a string representing the date and time:返回表示日期和时间的字符串：

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

The output string will not include time zone information, regardless of whether the input is aware or naive.输出字符串将不包括时区信息，无论输入是感知的还是原生的。

d.ctime() is equivalent to:相当于：

time.ctime(time.mktime(d.timetuple()))

on platforms where the native C ctime() function (which time.ctime() invokes, but which datetime.ctime() does not invoke) conforms to the C standard.在本机C ctime()函数（time.ctime()调用，但datetime.ctime()不调用）符合C标准的平台上。

datetime.strftime(format)

Return a string representing the date and time, controlled by an explicit format string. 返回一个表示日期和时间的字符串，由显式格式字符串控制。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

datetime.__format__(format)

Same as datetime.strftime(). 与datetime.strftime()相同。This makes it possible to specify a format string for a datetime object in formatted string literals and when using str.format(). 这使得在使用str.format()时，可以在格式化字符串文字中为datetime对象指定格式字符串。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

Examples of Usage: 用法示例：datetime

Examples of working with datetime objects:使用datetime对象的示例：

>>> 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.'

The example below defines a tzinfo subclass capturing time zone information for Kabul, Afghanistan, which used +4 UTC until 1945 and then +4:30 UTC thereafter:下面的示例定义了一个tzinfo子类，用于捕获阿富汗喀布尔的时区信息，该子类在1945年之前使用+4 UTC，之后使用+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"

Usage of KabulTz from above:从上面使用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 Objects对象

A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a tzinfo object.time对象表示一天中的（本地）时间，独立于任何特定的一天，并可通过tzinfo对象进行调整。

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

All arguments are optional. 所有参数都是可选的。tzinfo may be None, or an instance of a tzinfo subclass. tzinfo可以是None，也可以是tzinfo子类的实例。The remaining arguments must be integers in the following ranges:其余参数必须是以下范围内的整数：

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

If an argument outside those ranges is given, ValueError is raised. 如果给定的参数超出这些范围，则会引发ValueError。All default to 0 except tzinfo, which defaults to None.除tzinfo（默认为None）外，所有默认值均为0。

Class attributes:类属性：

time.min

The earliest representable time, time(0, 0, 0, 0).最早的可表示time，即time(0, 0, 0, 0)。

time.max

The latest representable time, time(23, 59, 59, 999999).最新的可表示time，即time(23, 59, 59, 999999)。

time.resolution

The smallest possible difference between non-equal time objects, timedelta(microseconds=1), although note that arithmetic on time objects is not supported.非等time对象之间可能存在的最小差异，timedelta(microseconds=1)，但请注意，不支持对time对象进行算术运算。

Instance attributes (read-only):实例属性（只读）：

time.hour

In range(24).

time.minute

In range(60).在range(60)中。

time.second

In range(60).在range(60)中。

time.microsecond

In range(1000000).在range(1000000)中。

time.tzinfo

The object passed as the tzinfo argument to the time constructor, or None if none was passed.对象作为tzinfo参数传递给time构造函数，如果未传递，则为None。

time.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. 在[0, 1]中。用于在重复间隔期间消除墙壁时间的歧义。(A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.)（当时钟在夏令时结束时回滚，或当当前区域的UTC偏移因政治原因减少时，会出现重复间隔。）The value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.值0(1)表示具有相同壁时间表示的两个力矩中的较早（较晚）时刻。

New in version 3.6.版本3.6中新增。

time objects support comparison of time to time, where a is considered less than b when a precedes b in time. time对象支持time与time的比较，其中当a在时间上先于b时，a被认为小于b。If one comparand is naive and the other is aware, TypeError is raised if an order comparison is attempted. 如果一个比较对象是原始的，而另一个是已知的，则如果尝试进行顺序比较，则会引发TypeError。For equality comparisons, naive instances are never equal to aware instances.对于相等比较，原始实例永远不会等于感知实例。

If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base times are compared. 如果两个比较者都知道，并且具有相同的tzinfo属性，则忽略公共tzinfo属性，并比较基准时间。If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()). 如果两个比较变量都知道并且具有不同的tzinfo属性，则首先通过减去其UTC偏移量（从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 !=. 为了防止混合类型比较回落到按对象地址的默认比较，当time对象与不同类型的对象进行比较时，会引发TTypeError，除非比较为==或!=。The latter cases return False or True, respectively.后一种情况分别返回False或True。

Changed in version 3.3:版本3.3中更改： Equality comparisons between aware and naive time instances don’t raise TypeError.感知和原生time实例之间的相等性比较不会引起TypeError。

In Boolean contexts, a time object is always considered to be true.在布尔上下文中，time对象始终被认为是真的。

Changed in version 3.5:版本3.5中更改： Before Python 3.5, a time object was considered to be false if it represented midnight in UTC. 在Python 3.5之前，如果time对象以UTC表示午夜，则它被认为是错误的。This behavior was considered obscure and error-prone and has been removed in Python 3.5. 这种行为被认为是模糊且容易出错的，在Python 3.5中已被删除。See bpo-13936 for full details.有关详细信息，请参阅bpo-13936。

Other constructor:其它构造函数：

classmethodtime.fromisoformat(time_string)

Return a time corresponding to a time_string in one of the formats emitted by time.isoformat(). 以time.isoformat()发出的格式之一返回与time_string相对应的time。Specifically, this function supports strings in the format:具体来说，此函数支持以下格式的字符串：

HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

Caution小心

This does not support parsing arbitrary ISO 8601 strings. 这不支持解析任意ISO 8601字符串。It is only intended as the inverse operation of time.isoformat().它仅用于time.isoformat()的反向操作。

Examples:示例：

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> 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)))

New in version 3.7.版本3.7中新增。

Instance methods:实例方法：

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Return a time with the same value, except for those attributes given new values by whichever keyword arguments are specified. 返回具有相同值的time，但通过指定的关键字参数赋予新值的属性除外。Note that tzinfo=None can be specified to create a naive time from an aware time, without conversion of the time data.注意，可以指定tzinfo=None来从感知time创建原生time，而无需转换时间数据。

New in version 3.6.版本3.6中新增。Added the fold argument.添加了fold参数。

time.isoformat(timespec='auto')

Return a string representing the time in ISO 8601 format, one of:返回ISO 8601格式的表示时间的字符串，其中一个为：

The optional argument timespec specifies the number of additional components of the time to include (the default is 'auto'). 可选参数timespec指定要包括的时间的其他组件的数量（默认值为“auto”）。It can be one of the following:它可以是以下之一：

  • 'auto': Same as 'seconds' if microsecond is 0, same as 'microseconds' otherwise.：如果microsecond为0，则与'seconds'相同，否则与'microseconds'相同。

  • 'hours': Include the hour in the two-digit HH format.：包括两位数HH格式的hour。

  • 'minutes': Include hour and minute in HH:MM format.：以HH:MM格式包括hour和minute。

  • 'seconds': Include hour, minute, and second in HH:MM:SS format.：以HH:MM:SS格式包括hour、minute和second。

  • 'milliseconds': Include full time, but truncate fractional second part to milliseconds. ：包括完整时间，但将分数秒部分截断为毫秒。HH:MM:SS.sss format.HH:MM:SS.sss格式。

  • 'microseconds': Include full time in HH:MM:SS.ffffff format.：包括HH:MM:SS.ffffff格式的完整时间。

Note

Excluded time components are truncated, not rounded.排除的时间分量被截断，而不是四舍五入。

ValueError will be raised on an invalid timespec argument.无效的timespec参数将引发ValueError。

Example:例子：

>>> 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'

New in version 3.6.版本3.6中新增。Added the timespec argument.添加了timespec参数。

time.__str__()

For a time t, str(t) is equivalent to t.isoformat().对于时间t，str(t)等价于t.isoformat()。

time.strftime(format)

Return a string representing the time, controlled by an explicit format string. 返回表示时间的字符串，由显式格式字符串控制。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

time.__format__(format)

Same as time.strftime(). 与time.strftime()相同。This makes it possible to specify a format string for a time object in formatted string literals and when using str.format(). 这使得在使用str.format()时，可以在格式化字符串文字中为time对象指定格式字符串。For a complete list of formatting directives, see strftime() and strptime() Behavior.有关格式化指令的完整列表，请参阅strftime()和strptime()行为。

time.utcoffset()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(None), and raises an exception if the latter doesn’t return None or a timedelta object with magnitude less than one day.如果tzinfo为None，则返回None，否则返回self.tzinfo.utcoffset(None)，如果后者不返回None或幅值小于一天的timedelta对象，则引发异常。

Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

time.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(None), and raises an exception if the latter doesn’t return None, or a timedelta object with magnitude less than one day.如果tzinfo为None，则返回None，否则返回self.tzinfo.dst(None)，如果self.tzinfo.dst(None)不返回None或幅值小于一天的timedelta对象，则引发异常。

Changed in version 3.7:版本3.7中更改： The DST offset is not restricted to a whole number of minutes.DST偏移量不限于整数分钟。

time.tzname()

If tzinfo is None, returns None, else returns self.tzinfo.tzname(None), or raises an exception if the latter doesn’t return None or a string object.如果tzinfo为None，则返回None，否则返回self.tzinfo.tzname(None)，如果后者不返回None或string对象，则引发异常。

Examples of Usage: 用法示例：time

Examples of working with a time object:使用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 Objects对象

classdatetime.tzinfo

This is an abstract base class, meaning that this class should not be instantiated directly. 这是一个抽象基类，这意味着该类不应直接实例化。Define a subclass of tzinfo to capture information about a particular time zone.定义tzinfo的子类以捕获关于特定时区的信息。

An instance of (a concrete subclass of) tzinfo can be passed to the constructors for datetime and time objects. tzinfo（的一个具体子类）的实例可以传递给datetime对象和time对象的构造函数。The latter objects view their attributes as being in local time, and the tzinfo object supports methods revealing offset of local time from UTC, the name of the time zone, and DST offset, all relative to a date or time object passed to them.后一个对象将其属性视为本地时间，tzinfo对象支持显示本地时间相对于UTC的偏移量、时区名称和DST偏移量的方法，所有这些都与传递给它们的日期或时间对象有关。

You need to derive a concrete subclass, and (at least) supply implementations of the standard tzinfo methods needed by the datetime methods you use. 您需要派生一个具体的子类，并且（至少）提供您使用的datetime方法所需的标准tzinfo方法的实现。The datetime module provides timezone, a simple concrete subclass of tzinfo which can represent timezones with fixed offset from UTC such as UTC itself or North American EST and EDT.datetime模块提供了timezone，它是tzinfo的一个简单具体的子类，可以表示与UTC有固定偏移的时区，例如UTC本身或北美EST和EDT。

Special requirement for pickling: A tzinfo subclass must have an __init__() method that can be called with no arguments, otherwise it can be pickled but possibly not unpickled again. pickle的特殊要求：tzinfo子类必须有一个可以不带参数调用的__init__()方法，否则可以对其进行pickle，但可能不会再次取消pickle。This is a technical requirement that may be relaxed in the future.这是一项技术要求，将来可能会放宽。

A concrete subclass of tzinfo may need to implement the following methods. tzinfo的一个具体子类可能需要实现以下方法。Exactly which methods are needed depends on the uses made of aware datetime objects. 具体需要哪些方法取决于感知datetime对象的使用情况。If in doubt, simply implement all of them.如果有疑问，只需全部实施即可。

tzinfo.utcoffset(dt)

Return offset of local time from UTC, as a timedelta object that is positive east of UTC. 返回本地时间相对于UTC的偏移量，作为UTC正东的timedelta对象。If local time is west of UTC, this should be negative.如果当地时间在UTC以西，则应为负值。

This represents the total offset from UTC; for example, if a tzinfo object represents both time zone and DST adjustments, utcoffset() should return their sum. 这表示与UTC的总偏移量；例如，如果tzinfo对象同时表示时区和DST调整，则utcoffset()应返回其总和。If the UTC offset isn’t known, return None. 如果UTC偏移量未知，则返回None。Else the value returned must be a timedelta object strictly between -timedelta(hours=24) and timedelta(hours=24) (the magnitude of the offset must be less than one day). 否则，返回的值必须是严格介于-timedelta（小时=24）和timedelta（小时=24）之间的timedelta对象（偏移量必须小于一天）。Most implementations of utcoffset() will probably look like one of these two:utcoffset()的大多数实现可能类似于以下两种实现之一：

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

If utcoffset() does not return None, dst() should not return None either.如果utcoffset()不返回None，则dst()也不应返回None。

The default implementation of utcoffset() raises NotImplementedError.utcoffset()的默认实现会引发NotImplementedError。

Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

tzinfo.dst(dt)

Return the daylight saving time (DST) adjustment, as a timedelta object or None if DST information isn’t known.将夏令时（DST）调整作为timedelta对象返回，如果夏令时信息未知，则返回None。

Return timedelta(0) if DST is not in effect. 如果DST无效，则返回timedelta(0)。If DST is in effect, return the offset as a timedelta object (see utcoffset() for details). 如果DST有效，则将偏移量作为timedelta对象返回（有关详细信息，请参阅utcoffset()。Note that DST offset, if applicable, has already been added to the UTC offset returned by utcoffset(), so there’s no need to consult dst() unless you’re interested in obtaining DST info separately. 请注意，DST偏移量（如果适用）已添加到utcoffset()返回的UTC偏移量中，因此无需咨询dst()，除非您有兴趣单独获取DST信息。For example, datetime.timetuple() calls its tzinfo attribute’s dst() method to determine how the tm_isdst flag should be set, and tzinfo.fromutc() calls dst() to account for DST changes when crossing time zones.例如，datetime.timetuple()调用其tzinfo属性的dst()方法来确定如何设置tm_isdst标志，tzinfo.fromutc()调用dst()来说明跨时区时的DST更改。

An instance tz of a tzinfo subclass that models both standard and daylight times must be consistent in this sense:tzinfo子类的一个实例tz（同时模拟标准时间和昼时）必须在这个意义上保持一致：

tz.utcoffset(dt) - tz.dst(dt)

must return the same result for every datetime dt with dt.tzinfo == tz For sane tzinfo 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. 必须为每个datetimedt返回相同的结果，dt.tzinfo==tz对于sane tzinfo子类，此表达式生成时区的“标准偏移”，其不应取决于日期或时间，而仅取决于地理位置。The implementation of datetime.astimezone() relies on this, but cannot detect violations; it’s the programmer’s responsibility to ensure it. datetime.astimezone()的实现依赖于此，但无法检测到违规行为；确保这一点是程序员的责任。If a tzinfo subclass cannot guarantee this, it may be able to override the default implementation of tzinfo.fromutc() to work correctly with astimezone() regardless.如果tzinfo子类不能保证这一点，那么不管怎样，它都可以重写tzinfo.fromutc()的默认实现，以正确使用astimezone()。

Most implementations of dst() will probably look like one of these two:dst()的大多数实现可能类似于以下两种实现之一：

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

or:或：

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)

The default implementation of dst() raises NotImplementedError.dst()的默认实现会引发NotImplementedError。

Changed in version 3.7:版本3.7中更改： The DST offset is not restricted to a whole number of minutes.DST偏移量不限于整数分钟。

tzinfo.tzname(dt)

Return the time zone name corresponding to the datetime object dt, as a string. 以字符串形式返回datetime对象dt对应的时区名称。Nothing about string names is defined by the datetime module, and there’s no requirement that it mean anything in particular. datetime模块没有定义任何关于字符串名称的内容，也不要求它有任何特殊含义。For example, “GMT”, “UTC”, “-500”, “-5:00”, “EDT”, “US/Eastern”, “America/New York” are all valid replies. 例如，“GMT”、“UTC”、“-500”、“-5:00”、“EDT”、“US/Eastern”、“America/New York”均为有效回复。Return None if a string name isn’t known. 如果字符串名称未知，则返回None。Note that this is a method rather than a fixed string primarily because some tzinfo subclasses will wish to return different names depending on the specific value of dt passed, especially if the tzinfo class is accounting for daylight time.请注意，这是一个方法，而不是固定字符串，主要是因为一些tzinfo子类希望根据传递的dt的特定值返回不同的名称，特别是如果tzinfo类考虑夏令时。

The default implementation of tzname() raises NotImplementedError.tzname()的默认实现会引发NotImplementedError。

These methods are called by a datetime or time object, in response to their methods of the same names. 这些方法由datetime或time对象调用，以响应其同名方法。A datetime object passes itself as the argument, and a time object passes None as the argument. datetime对象将自身作为参数传递，而time对象将None作为参数传递。A tzinfo subclass’s methods should therefore be prepared to accept a dt argument of None, or of class datetime.因此，tzinfo子类的方法应该准备好接受None或datetime类的dt参数。

When None is passed, it’s up to the class designer to decide the best response. 如果传入None，则由类设计器决定最佳响应。For example, returning None is appropriate if the class wishes to say that time objects don’t participate in the tzinfo protocols. 例如，如果类希望说时间对象不参与tzinfo协议，则返回None是合适的。It may be more useful for utcoffset(None) to return the standard UTC offset, as there is no other convention for discovering the standard offset.utcoffset(None)返回标准UTC偏移可能更有用，因为没有其他用于发现标准偏移的约定。

When a datetime object is passed in response to a datetime method, dt.tzinfo is the same object as self. 当传递datetime对象以响应datetime方法时，dt.tzinfo是与self相同的对象。tzinfo methods can rely on this, unless user code calls tzinfo methods directly. tzinfo方法可以依赖于此，除非用户代码直接调用tzinfo方法。The intent is that the tzinfo methods interpret dt as being in local time, and not need worry about objects in other timezones.其目的是tzinfo方法将dt解释为在本地时间，而不需要担心其他时区中的对象。

There is one more tzinfo method that a subclass may wish to override:子类可能希望重写另一个tzinfo方法：

tzinfo.fromutc(dt)

This is called from the default datetime.astimezone() implementation. 这是从默认的datetime.astimezone()实现中调用的。When called from that, dt.tzinfo is self, and dt’s date and time data are to be viewed as expressing a UTC time. 从中调用时，dt.tzinfo是self，dt的日期和时间数据将被视为表示UTC时间。The purpose of fromutc() is to adjust the date and time data, returning an equivalent datetime in self’s local time.fromutc()的目的是调整日期和时间数据，在self的本地时间中返回等效的datetime。

Most tzinfo subclasses should be able to inherit the default fromutc() implementation without problems. 大多数tzinfo子类应该能够毫无问题地继承默认的fromutc()实现。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 default fromutc() 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. 例如，时区的默认fromutc()实现可能无法在所有情况下正确处理，其中标准偏移量（从UTC）取决于经过的特定日期和时间，这可能是出于政治原因。The default implementations of astimezone() and fromutc() may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes.如果结果是跨越标准偏移量更改时间的某个小时，则astimezone()和fromutc()的默认实现可能不会产生您想要的结果。

Skipping code for error cases, the default fromutc() implementation acts like:跳过错误情况的代码，默认的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

In the following tzinfo_examples.py file there are some examples of tzinfo classes:在以下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
# http://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")

Note that there are unavoidable subtleties twice per year in a tzinfo subclass accounting for both standard and daylight time, at the DST transition points. 请注意，tzinfo子类每年在夏令时转换点不可避免地存在两次标准时间和夏令时的微妙之处。For concreteness, consider US Eastern (UTC -0500), where EDT begins the minute after 1:59 (EST) on the second Sunday in March, and ends the minute after 1:59 (EDT) on the first Sunday in November:具体来说，请考虑美国东部时间（UTC-0500），其中EDT开始于3月第二个星期日1:59（东部时间）后的一分钟，结束于11月第一个星期日1:59（东部时间）后的一分钟：

  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

When DST starts (the “start” line), the local wall clock leaps from 1:59 to 3:00. 当夏令时开始（“开始”行）时，本地挂钟从1:59跳到3:00。A wall time of the form 2:MM doesn’t really make sense on that day, so astimezone(Eastern) won’t deliver a result with hour == 2 on the day DST begins. 表2:MM的墙时间在那天没有意义，因此astimezone(Eastern)不会在DST开始的当天提供hour == 2的结果。For example, at the Spring forward transition of 2016, we get:例如，在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. 在东部，这是夏时制结束当天UTC格式5:MM的时间。The local wall clock leaps from 1:59 (daylight time) back to 1:00 (standard time) again. 当地的挂钟再次从1:59（夏令时）跳回到1:00（标准时间）。Local times of the form 1:MM are ambiguous. 形式为1:MM的当地时间不明确。astimezone() mimics the local clock’s behavior by mapping two adjacent UTC hours into the same local hour then. astimezone()通过将两个相邻的UTC小时映射到同一个本地小时来模拟本地时钟的行为。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. 在东部示例中，格式为5:MM和6:MM的UTC时间在转换为东部时均映射为1:MM，但早期时间的折叠属性设置为0，后期时间的fold属性设置为1。For example, at the Fall back transition of 2016, we get:例如，在2016年的回退过渡期，我们得到：

>>> 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.请注意，在比较中，仅因fold属性的值不同而不同的datetime实例被视为相等。

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)).不能承受墙时间模糊性的应用程序应该显式检查fold属性的值，或者避免使用混合的tzinfo子类；使用timezone或任何其他固定偏移量tzinfo子类（例如仅表示EST（固定偏移量-5小时）或仅表示EDT（固定偏移量-4小时））时没有歧义。

See also另请参见

zoneinfo

The datetime module has a basic timezone class (for handling arbitrary fixed offsets from UTC) and its timezone.utc attribute (a UTC timezone instance).datetime模块有一个基本时区类（用于处理UTC的任意固定偏移量）及其timezone.utc属性（UTC时区实例）。

zoneinfo brings the IANA timezone database (also known as the Olson database) to Python, and its usage is recommended.zoneinfo将IANA时区数据库（也称为Olson数据库）引入Python，建议使用它。

IANA timezone database

The Time Zone Database (often called tz, tzdata or zoneinfo) contains code and data that represent the history of local time for many representative locations around the globe. 时区数据库（通常称为tz、tzdata或zoneinfo）包含代码和数据，这些代码和数据表示全球许多具有代表性的位置的本地时间历史。It is updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets, and daylight-saving rules.它会定期更新，以反映政治机构对时区边界、UTC偏移和夏令时规则所做的更改。

timezone Objects对象

The timezone class is a subclass of tzinfo, each instance of which represents a timezone defined by a fixed offset from UTC.timezone类是tzinfo的一个子类，其每个实例表示由UTC的固定偏移量定义的时区。

Objects of this class cannot be used to represent timezone information in the locations where different offsets are used in different days of the year or where historical changes have been made to civil time.此类对象不能用于表示在一年中不同日期使用不同偏移量或对民用时间进行历史更改的位置中的时区信息。

classdatetime.timezone(offset, name=None)

The offset argument must be specified as a timedelta object representing the difference between the local time and UTC. offset参数必须指定为表示本地时间和UTC之间差异的timedelta对象。It must be strictly between -timedelta(hours=24) and timedelta(hours=24), otherwise ValueError is raised.它必须严格介于-timedelta(hours=24)和timedelta(hours=24)之间，否则会引发ValueError。

The name argument is optional. name参数是可选的。If specified it must be a string that will be used as the value returned by the datetime.tzname() method.如果指定，则必须是一个字符串，该字符串将用作datetime.tzname()方法返回的值。

New in version 3.2.版本3.2中新增。

Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

timezone.utcoffset(dt)

Return the fixed value specified when the timezone instance is constructed.返回构造timezone实例时指定的固定值。

The dt argument is ignored. 忽略dt参数。The return value is a timedelta instance equal to the difference between the local time and UTC.返回值是一个timedelta实例，等于本地时间和UTC之间的差值。

Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

timezone.tzname(dt)

Return the fixed value specified when the timezone instance is constructed.返回构造timezone实例时指定的固定值。

If name is not provided in the constructor, the name returned by tzname(dt) is generated from the value of the offset as follows. 如果构造函数中未提供name，则tzname(dt)返回的名称由offset的值生成，如下所示。If offset is timedelta(0), the name is “UTC”, otherwise it is a string in the format UTC±HH:MM, where ± is the sign of offset, HH and MM are two digits of offset.hours and offset.minutes respectively.如果偏移量是timedelta(0)，则名称为“UTC”，否则它是格式为UTC±HH:MM的字符串，其中是偏移量的符号，HH和MM分别是offset.hours和offset.minutes的两位数字。

Changed in version 3.6:版本3.6中更改： Name generated from offset=timedelta(0) is now plain ‘UTC’, not 'UTC+00:00'.从offset=timedelta(0)生成的名称现在是纯‘UTC’，而不是'UTC+00:00'。

timezone.dst(dt)

Always returns None.始终返回None。

timezone.fromutc(dt)

Return dt + offset. 返回dt + offset。The dt argument must be an aware datetime instance, with tzinfo set to self.dt参数必须是感知datetime实例，tzinfo设置为self。

Class attributes:类属性：

timezone.utc

The UTC timezone, timezone(timedelta(0)).UTC时区，即timezone(timedelta(0))。

strftime() and strptime() Behaviorstrftime()和strptime()行为

date, datetime, and time objects all support a strftime(format) method, to create a string representing the time under the control of an explicit format string.date、datetime和time对象都支持strftime(format)方法，以在显式格式字符串的控制下创建表示时间的字符串。

Conversely, the datetime.strptime() class method creates a datetime object from a string representing a date and time and a corresponding format string.相反，datetime.strptime()类方法从表示日期和时间的字符串以及相应的格式字符串创建datetime对象。

The table below provides a high-level comparison of strftime() versus strptime():下表提供了strftime()与strptime()的高级比较：

strftime

strptime

Usage用法

Convert object to a string according to a given format根据给定格式将对象转换为字符串

Parse a string into a datetime object given a corresponding format将字符串解析为给定相应格式的datetime对象

Type of method方法类型

Instance method实例方法

Class method类方法

Method of**的方法

date; datetime; time

datetime

Signature签名

strftime(format)

strptime(date_string, format)

strftime() and strptime() Format Codesstrftime()和strptime()格式代码

The following is a list of all the format codes that the 1989 C standard requires, and these work on all platforms with a standard C implementation.下面列出了1989年C标准要求的所有格式代码，这些代码在所有采用标准C实现的平台上都可以使用。

Directive指令

Meaning含义

Example实例

Notes备注

%a

Weekday as locale’s abbreviated name.Weekday作为区域设置的缩写名称。
Sun, Mon, …, Sat (en_US);
So, Mo, …, Sa (de_DE)

(1)

%A

Weekday as locale’s full name.工作日作为区域设置的全名。
Sunday, Monday, …, Saturday (en_US);
Sonntag, Montag, …, Samstag (de_DE)

(1)

%w

Weekday as a decimal number, where 0 is Sunday and 6 is Saturday.以十进制数字表示的工作日，其中0表示星期日，6表示星期六。

0, 1, …, 6

%d

Day of the month as a zero-padded decimal number.月份的第几天，以零填充的十进制数表示。

01, 02, …, 31

(9)

%b

Month as locale’s abbreviated name.月份作为区域设置的缩写名称。
Jan, Feb, …, Dec (en_US);
Jan, Feb, …, Dez (de_DE)

(1)

%B

Month as locale’s full name.月份作为区域设置的全名。
January, February, …, December (en_US);
Januar, Februar, …, Dezember (de_DE)

(1)

%m

Month as a zero-padded decimal number.月份为零填充十进制数。

01, 02, …, 12

(9)

%y

Year without century as a zero-padded decimal number.以零填充十进制数表示的无世纪年份。

00, 01, …, 99

(9)

%Y

Year with century as a decimal number.以世纪为小数的年份。

0001, 0002, …, 2013, 2014, …, 9998, 9999

(2)

%H

Hour (24-hour clock) as a zero-padded decimal number.小时（24小时制）为零填充十进制数。

00, 01, …, 23

(9)

%I

Hour (12-hour clock) as a zero-padded decimal number.小时（12小时制）为零填充十进制数。

01, 02, …, 12

(9)

%p

Locale’s equivalent of either AM or PM.语言环境等效于AM或PM。
AM, PM (en_US);
am, pm (de_DE)

(1), (3)

%M

Minute as a zero-padded decimal number.分钟作为零填充十进制数。

00, 01, …, 59

(9)

%S

Second as a zero-padded decimal number.秒作为零填充的十进制数。

00, 01, …, 59

(4), (9)

%f

Microsecond as a decimal number, zero-padded to 6 digits.微秒作为十进制数，零填充到6位。

000000, 000001, …, 999999

(5)

%z

UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive).UTC偏移量，格式为±HHMM[SS[.ffffff]]（如果对象是原始对象，则为空字符串）。

(empty), +0000, -0400, +1030, +063415, -030712.345216

(6)

%Z

Time zone name (empty string if the object is naive).时区名称（如果对象是原始的，则为空字符串）。

(empty), UTC, GMT

(6)

%j

Day of the year as a zero-padded decimal number.以零填充十进制数表示的一年中的某一天。

001, 002, …, 366

(9)

%U

Week number of the year (Sunday as the first day of the week) as a zero-padded decimal number. 一年中的周数（星期日为一周的第一天）为零填充十进制数。All days in a new year preceding the first Sunday are considered to be in week 0.新年中第一个星期日之前的所有日子都被视为在第0周。

00, 01, …, 53

(7), (9)

%W

Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. 一年中的周数（星期一为一周的第一天）为零填充十进制数。All days in a new year preceding the first Monday are considered to be in week 0.新年第一个星期一之前的所有日子都被视为在第0周。

00, 01, …, 53

(7), (9)

%c

Locale’s appropriate date and time representation.区域设置的适当日期和时间表示。
Tue Aug 16 21:30:00 1988 (en_US);
Di 16 Aug 21:30:00 1988 (de_DE)

(1)

%x

Locale’s appropriate date representation.区域设置的适当日期表示。
08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)

(1)

%X

Locale’s appropriate time representation.区域设置的适当时间表示。
21:30:00 (en_US);
21:30:00 (de_DE)

(1)

%%

A literal '%' character.文字字符'%'。

%

Several additional directives not required by the C89 standard are included for convenience. 为了方便起见，还包括了C89标准不要求的几个附加指令。These parameters all correspond to ISO 8601 date values.这些参数都对应于ISO 8601日期值。

Directive指令

Meaning含义

Example实例

Notes备注

%G

ISO 8601 year with century representing the year that contains the greater part of the ISO week (%V).ISO 8601年，世纪表示包含ISO周大部分（%V）的年份。

0001, 0002, …, 2013, 2014, …, 9998, 9999

(8)

%u

ISO 8601 weekday as a decimal number where 1 is Monday.ISO 8601 weekday作为十进制数，其中1是星期一。

1, 2, …, 7

%V

ISO 8601 week as a decimal number with Monday as the first day of the week. ISO 8601星期为十进制数，星期一为一周的第一天。Week 01 is the week containing Jan 4.第01周是包含1月4日的一周。

01, 02, …, 53

(8), (9)

These may not be available on all platforms when used with the strftime() method. 当与strftime()方法一起使用时，这些可能无法在所有平台上使用。The ISO 8601 year and ISO 8601 week directives are not interchangeable with the year and week number directives above. ISO 8601年和ISO 8601周指令不能与上述年和周数指令互换。Calling strptime() with incomplete or ambiguous ISO 8601 directives will raise a ValueError.使用不完整或不明确的ISO 8601指令调用strTime()将引发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. 支持的全套格式代码因平台而异，因为Python调用平台C库的strftime()函数，平台变体很常见。To see the full set of format codes supported on your platform, consult the strftime(3) documentation. 要查看您的平台上支持的全套格式代码，请参阅strftime(3)文档。There are also differences between platforms in handling of unsupported format specifiers.平台之间在处理不支持的格式说明符方面也存在差异。

New in version 3.6.版本3.6中新增。%G, %u and %V were added.添加了%G、%u和%V。

Technical Detail技术细节

Broadly speaking, d.strftime(fmt) acts like the time module’s time.strftime(fmt, d.timetuple()) although not all objects support a timetuple() method.广义上讲，d.strftime(fmt)就像time模块的time.strftime(fmt, d.timetuple())，尽管并非所有对象都支持timetuple()方法。

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. 对于datetime.strptime()类方法，默认值为1900-01-01T00:00:00.000：格式字符串中未指定的任何组件都将从默认值中提取。4

Using datetime.strptime(date_string, format) is equivalent to:使用datetime.strptime(date_string, format)等效于：

datetime(*(time.strptime(date_string, format)[0:6]))

except when the format includes sub-second components or timezone offset information, which are supported in datetime.strptime but are discarded by time.strptime.除非该格式包含亚秒分量或时区偏移信息，这些信息在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. 对于time对象，不应使用年、月和日的格式代码，因为time对象没有此类值。If they’re used anyway, 1900 is substituted for the year, and 1 for the month and day.如果仍然使用，则用1900代替年份，1代替月份和日期。

For date objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as date objects have no such values. 对于date对象，不应使用小时、分钟、秒和微秒的格式代码，因为date对象没有此类值。If they’re used anyway, 0 is substituted for them.如果仍然使用它们，则用0代替它们。

For the same reason, handling of format strings containing Unicode code points that can’t be represented in the charset of the current locale is also platform-dependent. 出于同样的原因，处理包含无法在当前区域设置的字符集中表示的Unicode代码点的格式字符串也取决于平台。On some platforms such code points are preserved intact in the output, while on others strftime may raise UnicodeError or return an empty string instead.在某些平台上，这样的代码点在输出中保持不变，而在其他平台上，strftime可能会引发UnicodeError或返回空字符串。

Notes:备注：

  1. Because the format depends on the current locale, care should be taken when making assumptions about the output value. 由于格式取决于当前区域设置，因此在假设输出值时应小心。Field orderings will vary (for example, “month/day/year” versus “day/month/year”), and the output may contain Unicode characters encoded using the locale’s default encoding (for example, if the current locale is ja_JP, the default encoding could be any one of eucJP, SJIS, or utf-8; use locale.getlocale() to determine the current locale’s encoding).字段顺序会有所不同（例如，“月/日/年”与“日/月/年”），输出可能包含使用区域设置的默认编码编码的Unicode字符（例如，如果当前区域设置为ja_JP，则默认编码可以是eucJP、SJIS或utf-8中的任何一种；使用locale.getlocale()确定当前区域设置的编码）。

  2. The strptime() method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width.strTime()方法可以解析[1, 9999]范围内的年份，但是小于1000的年份必须用零填充到4位宽度。

    Changed in version 3.2:版本3.2中更改： In previous versions, strftime() method was restricted to years >= 1900.在以前的版本中，strftime()方法被限制为大于等于1900年。

    Changed in version 3.3:版本3.3中更改： In version 3.2, strftime() method was restricted to years >= 1000.在3.2版中，strftime()方法被限制为大于等于1000年。

  3. 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.当与strTime()方法一起使用时，%p指令仅在使用%I指令解析小时时影响输出小时字段。

  4. Unlike the time module, the datetime module does not support leap seconds.与time模块不同，datetime模块不支持闰秒。

  5. When used with the strptime() method, the %f directive accepts from one to six digits and zero pads on the right. 当与strTime()方法一起使用时，%f指令接受1到6位数字和右侧的零填充。%f is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).%f是C标准中格式字符集的扩展（但在datetime对象中单独实现，因此始终可用）。

  6. For a naive object, the %z and %Z format codes are replaced by empty strings.对于原始对象，%z和%Z格式代码被空字符串替换。

    For an aware object:对于感知对象：

    %z

    utcoffset() is transformed into a string of the form ±HHMM[SS[.ffffff]], where HH 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 and ffffff is a 6-digit string giving the number of UTC offset microseconds. utcoffset()被转换为形式为±HHMM[SS[.ffffff]]的字符串，其中HH是给出UTC偏移小时数的2位字符串，MM是给出UTC偏移分钟数的2位字符串，SS是给出UTC偏移秒数的2位字符串，ffffff是给出UTC偏移微秒数的6位字符串。The ffffff part is omitted when the offset is a whole number of seconds and both the ffffff and the SS part is omitted when the offset is a whole number of minutes. 当偏移量为整数秒时，忽略ffffff部分，当偏移量为整数分钟时，忽略ffffff和SS部分。For example, if utcoffset() returns timedelta(hours=-3, minutes=-30), %z is replaced with the string '-0330'.例如，如果utcoffset()返回timedelta(hours=-3, minutes=-30)，%z将替换为字符串'-0330'。

    Changed in version 3.7:版本3.7中更改： The UTC offset is not restricted to a whole number of minutes.UTC偏移量不限于整数分钟。

    Changed in version 3.7:版本3.7中更改： When the %z directive is provided to the strptime() method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. 当向strTime()方法提供%z指令时，UTC偏移量可以使用冒号作为小时、分钟和秒之间的分隔符。For example, '+01:00:00' will be parsed as an offset of one hour. 例如，'+01:00:00'将被解析为一小时的偏移量。In addition, providing 'Z' is identical to '+00:00'.此外，提供的'Z'与'+00:00'相同。

    %Z

    In strftime(), %Z is replaced by an empty string if tzname() returns None; otherwise %Z is replaced by the returned value, which must be a string.在strftime()中，如果tzname()返回None，则将%Z替换为空字符串；否则%Z将替换为返回值，返回值必须是字符串。

    strptime() only accepts certain values for %Z:仅接受%Z的某些值：

    1. any value in time.tzname for your machine’s localetime.tzname中与计算机区域设置对应的任何值

    2. the hard-coded values UTC and GMT硬编码值UTC和GMT

    So someone living in Japan may have JST, UTC, and GMT as valid values, but probably not EST. 因此，生活在日本的人可能将JST、UTC和GMT作为有效值，但可能不是EST。It will raise ValueError for invalid values.对于无效值，它将引发ValueError。

    Changed in version 3.2:版本3.2中更改： When the %z directive is provided to the strptime() method, an aware datetime object will be produced. 当向strTime()方法提供%z指令时，将生成一个感知datetime对象。The tzinfo of the result will be set to a timezone instance.结果的tzinfo将设置为timezone实例。

  7. 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.当与strTime()方法一起使用时，仅当指定了星期几和日历年（%Y）时，才会在计算中使用%U和%W。

  8. 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 a strptime() format string. 与%U和%W类似，只有在strtime()格式字符串中指定了星期几和ISO年（%G）时，才在计算中使用%V。Also note that %G and %Y are not interchangeable.还要注意的是%G和%Y是不可互换的。

  9. When used with the strptime() method, the leading zero is optional for formats %d, %m, %H, %I, %M, %S, %J, %U, %W, and %V. 当与strTime()方法一起使用时，前导零对于格式%d、%m、%H、%I、%m、%S、%J、%U、%W和%V是可选的。Format %y does require a leading zero.格式%y需要前导零。

Footnotes

1

If, that is, we ignore the effects of Relativity如果我们忽略了相对论的影响

2

This matches the definition of the “proleptic Gregorian” calendar in Dershowitz and Reingold’s book Calendrical Calculations, where it’s the base calendar for all computations. 这与德肖维茨（Dershowitz）和莱因戈尔德（Reingold）的《历法计算》（Calendarial Calculations）一书中“前公历”（proleptic Gregorian）的定义相匹配，其中它是所有计算的基准日历。See the book for algorithms for converting between proleptic Gregorian ordinals and many other calendar systems.有关proleptic Gregorian序数和许多其他日历系统之间转换的算法，请参阅本书。

3

See R. H. van Gent’s guide to the mathematics of the ISO 8601 calendar for a good explanation.有关详细解释，请参阅R.H.VanGent的ISO 8601日历数学指南。

4

Passing datetime.strptime('Feb 29', '%b %d') will fail since 1900 is not a leap year.由于1900年不是闰年，传递datetime.strptime('Feb 29', '%b %d')将失败。