8.1. datetime — Basic date and time types

Source code: Lib/datetime.py

The datetime module supplies classes for manipulating dates and times in both simple and complex ways. While date and time arithmetic is supported, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation. For related functionality, see also the time and calendar modules.

There are two kinds of date and time objects: 「naive」 and 「aware」.

An aware object has sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, to locate itself relative to other aware objects. An aware object is used to represent 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. 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. These tzinfo objects capture information about the offset from UTC time, the time zone name, and whether Daylight Saving Time is in effect. Note that only one concrete tzinfo class, the timezone class, is supplied by the datetime module. The timezone class can represent simple timezones with fixed offset from UTC, such as UTC itself or North American EST and EDT timezones. Supporting timezones at deeper levels of detail is up to the application. The rules for time adjustment across the world are more political than rational, change frequently, and there is no standard suitable for every application aside from UTC.

The datetime module exports the following constants:

datetime.MINYEAR

The smallest year number allowed in a date or datetime object. MINYEAR is 1.

datetime.MAXYEAR

The largest year number allowed in a date or datetime object. MAXYEAR is 9999.

也參考

Module calendar
General calendar related functions.
Module time
Time access and conversions.

8.1.1. Available Types

class datetime.date

An idealized naive date, assuming the current Gregorian calendar always was, and always will be, in effect. Attributes: year, month, and day.

class datetime.time

An idealized time, independent of any particular day, assuming that every day has exactly 24*60*60 seconds (there is no notion of 「leap seconds」 here). Attributes: hour, minute, second, microsecond, and tzinfo.

class datetime.datetime

A combination of a date and a time. Attributes: year, month, day, hour, minute, second, microsecond, and tzinfo.

class datetime.timedelta

A duration expressing the difference between two date, time, or datetime instances to microsecond resolution.

class datetime.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).

class datetime.timezone

A class that implements the tzinfo abstract base class as a fixed offset from the UTC.

3.2 版新加入.

Objects of these types are immutable.

Objects of the date type are always naive.

An object of type time or datetime may be naive or aware. A datetime object d is aware if d.tzinfo is not None and d.tzinfo.utcoffset(d) does not return None. If d.tzinfo is None, or if d.tzinfo is not None but d.tzinfo.utcoffset(d) returns None, d is naive. A time object t is aware if t.tzinfo is not None and t.tzinfo.utcoffset(None) does not return None. Otherwise, t is naive.

The distinction between naive and aware doesn’t apply to timedelta objects.

Subclass relationships:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

8.1.2. timedelta Objects

A timedelta object represents a duration, the difference between two dates or times.

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

All arguments are optional and default to 0. Arguments may be integers or floats, and may be positive or negative.

Only days, seconds and microseconds are stored internally. Arguments are converted to those units:

  • A millisecond is converted to 1000 microseconds.
  • A minute is converted to 60 seconds.
  • An hour is converted to 3600 seconds.
  • A week is converted to 7 days.

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

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.

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

timedelta.min

The most negative timedelta object, timedelta(-999999999).

timedelta.max

The most positive timedelta object, 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).

Note that, because of normalization, timedelta.max > -timedelta.min. -timedelta.max is not representable as a timedelta object.

Instance attributes (read-only):

Attribute Value
days Between -999999999 and 999999999 inclusive
seconds Between 0 and 86399 inclusive
microseconds Between 0 and 999999 inclusive

Supported operations:

Operation Result
t1 = t2 + t3 Sum of t2 and t3. Afterwards t1-t2 == t3 and t1-t3 == t2 are true. (1)
t1 = t2 - t3 Difference of t2 and t3. Afterwards t1 == t2 - t3 and t2 == t1 + t3 are true. (1)(6)
t1 = t2 * i or t1 = i * t2 Delta multiplied by an integer. Afterwards t1 // i == t2 is true, provided i != 0.
  In general, t1 * i == t1 * (i-1) + t1 is 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.
f = t2 / t3 Division (3) of t2 by t3. Returns a float object.
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.
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. (3)
q, r = divmod(t1, t2) Computes the quotient and the remainder: q = t1 // t2 (3) and r = t1 % t2. q is an integer and r is a timedelta object.
+t1 Returns a timedelta object with the same value. (2)
-t1 equivalent to timedelta(-t1.days, -t1.seconds, -t1.microseconds), and to t1* -1. (1)(4)
abs(t) equivalent to +t when t.days >= 0, and to -t when t.days < 0. (2)
str(t) Returns a string in the form [D day[s], ][H]H:MM:SS[.UUUUUU], where D is negative for negative t. (5)
repr(t) Returns a string representation of the