datetime --- 日期與時間的基本型別

原始碼：Lib/datetime.py

---

datetime 模組提供操作日期與時間的類別。

While date and time arithmetic is supported, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation.

小訣竅

跳轉至格式碼 (format codes)。

也參考

calendar 模組

與日曆相關的一般函式。

time 模組

Time access and conversions.

zoneinfo 模組

Concrete time zones representing the IANA time zone database.

dateutil 套件

帶有時區與剖析擴充支援的第三方函式庫。

DateType 套件

Third-party library that introduces distinct static types to for example, allow static type checkers to differentiate between naive and aware datetimes.

Aware and naive objects

Date and time objects may be categorized as "aware" or "naive" depending on whether or not they include time zone 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 time zone 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.

Only one concrete tzinfo class, the timezone class, is supplied by the datetime module. The timezone class can represent simple time zones with fixed offsets from UTC, such as UTC itself or North American EST and EDT time zones. Supporting time zones 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.

常數

datetime 模組匯出以下常數：

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.

datetime.UTC

Alias for the UTC time zone singleton datetime.timezone.utc.

在 3.11 版被加入.

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

表示兩個 datetime 或 date 實例之間時間的差異，以微秒為解析度。

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.

Subclass relationships:

常見屬性

The date, datetime, time, and timezone types share these common features:

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

Determining if an object is aware or naive

Objects of the date type are always naive.

An object of type time or datetime may be aware or naive.

A datetime object d is aware if both of the following hold:

1. d.tzinfo 不是 None

2. d.tzinfo.utcoffset(d) 不會回傳 None

否則 d 會是 naive 的。

A time object t is aware if both of the following hold:

1. t.tzinfo 不是 None

2. t.tzinfo.utcoffset(None) 沒有回傳 None。

否則 t 會是 naive 的。

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

timedelta 物件

一個 timedelta 物件代表著一段持續時間，即兩個 datetime 或 date 之間的差異。

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:

• 一毫秒會被轉換為 1000 微秒。

• 一分鐘會被轉換為 60 秒。

• 一小時會被轉換為 3600 秒。

• 一週會被轉換為 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:

>>> import datetime as dt
>>> delta = dt.timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,