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 0
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 2003-08-05T21:36:11.590000 20030805T213611
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-07-29 2003 7 29 2003-08-07
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 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