We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

The datetime Module

(New in 2.3) The datetime module provides a number of types to deal with dates, times, and time intervals. This module replaces the integer/tuple-based time mechanisms in the time module with a more object-oriented interface.

All types provided by this module are new-style classes, and can be subclassed and extended from Python.

The module contains the following types:

  • The datetime type represents a date and a time during that day.
  • The date type represents just a date, between year 1 and 9999 (see below for more about the calendar used by the datetime module)
  • The time type represents a time, independent of the date.
  • The timedelta type represents the difference between two time or date objects.
  • The tzinfo type is used to implement timezone support for time and datetime objects; more about that below.

the datetime type

Objects of the datetime type represent a date and a time in some timezone. Unless otherwise specified, datetime objects use “naive time”, which means that it’s up to the application to keep track of what time zone they’re in. The datetime module provides some support for time zones; more on that later.

To create a datetime object for a given date, call the datetime constructor:

# File: datetime-example-1.py

import datetime

now = datetime.datetime(2003, 8, 4, 12, 30, 45)

print now
print repr(now)
print type(now)
print now.year, now.month, now.day
print now.hour, now.minute, now.second
print now.microsecond
$ python datetime-example-1.py
2003-08-04 12:30:45
datetime.datetime(2003, 8, 4, 12, 30, 45)
<type 'datetime.datetime'>
2003 8 4
12 30 45

Note that the default string representation is an ISO 8601-style timestamp.

You can also create datetime objects by using one of the many built-in factory functions (but note that all such functions are provided as class methods, not module functions):

# File: datetime-example-2.py

import datetime
import time

print datetime.datetime(2003, 8, 4, 21, 41, 43)

print datetime.datetime.today()
print datetime.datetime.now()
print datetime.datetime.fromtimestamp(time.time())

print datetime.datetime.utcnow()
print datetime.datetime.utcfromtimestamp(time.time())
$ python datetime-example-2.py
2003-08-04 21:41:43
2003-08-04 21:41:43.522000
2003-08-04 21:41:43.522000
2003-08-04 21:41:43.522000
2003-08-04 19:41:43.532000
2003-08-04 19:41:43.532000

As can be seen from these examples, the default formatting for a datetime object is an ISO 8601-style string: “yyyy-mm-dd hh:mm:ss”, optionally followed by a number of microseconds.

The datetime type provides other formatting methods as well, including the highly general strftime method (for details on this method, see the description for the corresponding function in the time module):

# File: python datetime-example-3.py

import datetime
import time

now = datetime.datetime.now()

print now
print now.ctime()
print now.isoformat()
print now.strftime("%Y%m%dT%H%M%S")
$ python datetime-example-3.py
2003-08-05 21:36:11.590000
Tue Aug  5 21:36:11 2003

the date and time types

The date type represents the date portions of a datetime object.

# File: datetime-example-4.py

import datetime

d = datetime.date(2003, 7, 29)

print d
print d.year, d.month, d.day

print datetime.date.today()
$ python datetime-example-4.py
2003 7 29

The time type is similar; it represents the time portion, with microsecond resolution.

# File: datetime-example-5.py

import datetime

t = datetime.time(18, 54, 32)

print t
print t.hour, t.minute, t.second, t.microsecond
$ python datetime-example-5.py
18 54 32 0

The datetime type provides method to extract date and time objects, as well as a class method that combines two objects into a single datetime object:

# File: datetime-example-6.py

import datetime

now = datetime.datetime.now()

d = now.date()
t = now.time()

print now
print d, t
print datetime.datetime.combine(d, t)
$ python datetime-example-6.py
2003-08-07 23:19:57.926000
2003-08-07 23:19:57.926000
2003-08-07 23:19:57.926000