Datetime Module

Indices and tables

• Index
• Module Index
• Search Page

Introduction

Applications commonly have to interpret, manipulate and print date and time values. The datetime module provides a rich set of standardized functionality to make it easy for you to integrate platform independent code into your application.

The datetime module provides several objects and they generally fall into one of 2 categories:

• Aware - Has knowledge of time adjustments like time zones and daylight savings time. Due to awareness, these object types can properly represent a specific moment in time relative to other objects that are also aware.
• Naive - Lacks “awareness” properties (mind…blown). Therefore, it is not always possible to identify exactly what the moment of time is compared to other naive or aware objects. For example, stating it’s 8pm without giving the timezone, does not actually tell you the time with-respect-to a known datum (UTC), and therefore without a known reference point, this ‘time’ can’t be compared to other ‘times’.

Naive objects are generally easier to work with since, in a lot of situations, you can ignore obtaining the information necessary to make an object “aware”. For example, saying a data sample was acquired 28 seconds after starting the program, does not require an aware object to make the time value meaningful.

There are many classes defined in the datetime that you should familiarize yourself with. However, only 2 will be discussed in detail here.

timedelta Class

MUTABILITY: Immutable

A type that represents the difference between two dates or times.

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

All arguments are optional, may be of class int or float, can be positive or negative, and default to 0.

Internally, the timedelta class converts the time-delta into units of days, seconds and microseconds only (fractional microseconds, if they exist, are rounded off). As a result, only these characteristic attributes of the time delta can be obtained from the timedelta object.

Instances of timedelta are considered True if they don’t equal timedelta(0).

We can explore some (but not all) of the attributes available to the timedelta objects. First, lets create some timedelta objects to work with:

>>> from datetime import timedelta
>>> t0 = timedelta(1, 2, 3, 4, 5, 6, 7)
>>> t0
datetime.timedelta(50, 21902, 4003)
>>> t1 = timedelta(21, 22, 23, 24, 25, 26, 27)
>>> t1
datetime.timedelta(211, 8722, 24023)

• Printing time-delta information

  >>> str(t0)
  '50 days, 6:05:02.004003'
  >>> print(t0)
  50 days, 6:05:02.004003
  >>> repr(t0)
  'datetime.timedelta(50, 21902, 4003)'
  

• Obtaining time-delta information

  >>> t0.days
  50
  >>> t0.seconds
  21902
  >>> t0.microseconds
  4003
  >>> t0.total_seconds()
  4341902.004003
  

Instances of timedelta objects support many of the typical math operators that work on int and float objects. For example:

• Adding and subtracting

  >>> t0 + t1
  datetime.timedelta(261, 30624, 28026)
  >>> t0 - t1
  datetime.timedelta(-161, 13179, 979980)
  

• Multiplication and division

  >>> t0 * 5
  datetime.timedelta(251, 23110, 20015)
  >>> t0 / t1
  0.23805433168790804
  >>> t0 / 5
  datetime.timedelta(10, 4380, 400801)
  >>> t0 // t1
  0
  >>> t0 // 5
  datetime.timedelta(10, 4380, 400800)
  >>> t0 % 5
  datetime.timedelta(50, 21902, 4003)
  >>> quotient, remainder = divmod(t0, t1)
  >>> quotient
  0
   >>> remainder
  datetime.timedelta(50, 21902, 4003)
  

• Unary operations

  >>> id(t0)
  140628001935808
  >>> id(+t0)      # '+' returns a copy of t0 timedelta object
  140628001938568
  >>> -t0
  datetime.timedelta(-51, 64497, 995997)
  >>> abs(t0)
  datetime.timedelta(50, 21902, 4003)
  

datetime Class

MUTABILITY: Immutable

This is a class within the datetime module, not the module itself.

A datetime object combines a date and a time object together to represent a specific moment in time.

datetime(year, month, day, hour=0, minute=0, second=0, tzinfo=None)

If the tzinfo argument is provided, the object is aware. Otherwise, it is naive. Except for tzinfo, all arguments are int.

We can explore some (but not all) of the attributes available to the datetime objects. First, lets create some datetime objects to work with:

>>> from datetime import datetime
>>> from datetime import timedelta
>>> from datetime import timezone
>>> import time
>>> #
>>> # Create a timezone object to represent UTC-5
>>> #
>>> my_timezone = timezone(timedelta(hours=-5))
>>> #
>>> # Create some aware datetime objects
>>> #
>>> dt0 = datetime(2018, 3, 12, 9, 37, 34, 100, my_timezone)
>>> dt1 = datetime.now(my_timezone)

Tip

Consider the pytz package for a slicker method for specifying timezones.

• Printing datetime objects returns iso8601 formatted strings:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> print(dt1)
  2018-03-12 20:59:37.447286-05:00
  

Tip

There is an international standard for representing date and time values called iso8601.

Due to it being more natural to interpret datetime values when printed (and not viewing their repr output), the output from the examples will be wrapped in print() statements.

• Obtaining the current time

  >>> print(datetime.now(my_timezone))
  2018-03-12 21:08:18.077444-05:00
  

• Obtaining a datetime object from a POSIX timestamp (such as from time())

  >>> print(datetime.fromtimestamp(time.time(), my_timezone))
  2018-03-12 21:07:02.917972-05:00
  

• Convert a datetime object into a POSIX timestamp:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> dt0.timestamp()
  1520865454.0001
  

• Obtain a datetime object by parsing a string according to a given format:

  >>> print(datetime.strptime('Tue Jun 17, 2008', '%a %b %d, %Y'))
  2008-06-17 00:00:00
  

• Output a datetime object using a specific format string:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> dt0.strftime('%a %b %d, %Y')
  'Mon Mar 12, 2018'
  

• Obtaining attributes about a datetime value:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> dt0.year
  2018
  >>> dt0.month
  3
  >>> dt0.day
  12
  >>> dt0.hour
  9
  >>> dt0.minute
  37
  >>> dt0.second
  34
  >>> print(dt0.tzinfo)
  UTC-05:00
  >>> print(dt0.date())
  2018-03-12
  >>> print(dt0.time())
  09:37:34.000100
  >>> dt0.weekday()    # Monday=0, Sunday=6
  0
  >>> dt0.isoweekday() # Monday=1, Sunday=7
  1
  >>> dt0.isocalendar() # ISO Year, ISO week num, ISO weekday
  (2018, 11, 1)
  >>> dt0.isoformat()   # ISO 8601 format output
  '2018-03-12T09:37:34.000100-05:00'
  

• Alter attributes of the datetime value:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> dt2 = dt0.replace(year=2099)
  >>> print(dt2)
  2099-03-12 09:37:34.000100-05:00
  

Any of the attributes (year, month, day, hour, minute, second, microsecond and tzinfo, given as keyword argument) can be replaced in the datetime object using this method.

• datetime objects can be added and subtracted with timedelta

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> print(dt0 + timedelta(hours=5))
  2018-03-12 14:37:34.000100-05:00
  >>> print(dt0 - timedelta(hours=5))
  2018-03-12 04:37:34.000100-05:00
  

• Subtracting two datetime objects yields the timedelta between them:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> print(dt1)
  2018-03-12 20:59:37.447286-05:00
  >>> print(dt1 - dt0)
  11:22:03.447186
  

• You can compare datetime objects just like other numerical objects:

  >>> print(dt0)
  2018-03-12 09:37:34.000100-05:00
  >>> print(dt1)
  2018-03-12 20:59:37.447286-05:00
  >>> dt0 < dt1
  True
  >>> dt0 == dt1
  False
  >>> dt0 > dt1
  False