datetime — Basic date and time types

Source code: Lib/datetime.py

The datetime module supplies classes for manipulating dates and times.

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

Tip

The dateutil package provides powerful extensions to the standard datetime module.

Aware and Naive Objects

Date and time objects may be categorized as aware or naive depending on whether or not they include timezone information.

An aware object represents a specific moment in time that is not open to interpretation. An aware object t knows its UTC offset via t.utcoffset(), and its t.dst() and t.tzname() methods.

A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.

Constants

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.

Available Types

timedelta Objects

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

Constructor:

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 ints 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 < 86400 (the number of seconds in one day)
• -999999999 <= days <= 999999999

Example usage:

>>> from datetime import timedelta
>>> delta = timedelta(days=50, seconds=27, microseconds=10, milliseconds=29000,
...                   minutes=5, hours=8, weeks=2)
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)
>>> delta.total_seconds()
5558756.00001

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.

Constructor:

class datetime.date(year, month, day)

All arguments are required. Arguments must satisfy the following constraints:

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

strftime() and strptime() Behavior

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.

Warning

The exact range of years for which strftime() works also varies across platforms. Regardless of platform, years before 1900 should not be used.

The following table shows all the directive codes:

Directive	Meaning	Example
%a	Weekday abbreviated name	Sun, Mon, …, Sat
%A	Weekday full name	Sunday, Monday, …, Saturday
%d	Day of month as zero-padded decimal	01, 02, …, 31
%m	Month as zero-padded decimal	01, 02, …, 12
%Y	Year with century	0001, 0002, …, 9999
%H	Hour (24-hour clock) zero-padded	00, 01, …, 23
%M	Minute zero-padded	00, 01, …, 59
%S	Second zero-padded	00, 01, …, 59
%f	Microsecond zero-padded	000000, 000001, …, 999999
%z	UTC offset in the form ±HHMM[SS[.ffffff]]	(empty), +0000, -0400, +1030