Python Datetime Methods: Date, Timedelta

Datetime. Space and time are connected.

But in Python, we are concerned most with simpler aspects of time. We can format and manipulate dates.

With datetime, a module, we parse strings containing dates. And we can manipulate time spans. We use built-in datetime libraries. They make many programs easier to write.

Parse. We can parse dates from strings. We have the strptime method in datetime. The name is confusing. It is best just to memorize it. This method requires two arguments.

Arguments: The first argument is a string containing date information. The second argument is the format string.

Based on:

Python 3

Format codes

B: The full month name.
d: The digit of the day of the month.
Y: The four-digit year.

Python program that uses strptime

from datetime import datetime

# Input string.
s = "August 16, 2012"

# Use strptime.
d = datetime.strptime(s, "%B %d, %Y")
print(d)

Output

2012-08-16 00:00:00

Yesterday. This is always the current date minus one day. In Python we compute this with timedelta. This type resides in the datetime module.

Here: We introduce a method called yesterday(). It calls today() and then subtracts a timedelta of 1 day.

Tip: A timedelta can be subtracted or added to a date object. In this way, we compute yesterday, today and any other relative day.

Python program that returns yesterday

from datetime import date
from datetime import timedelta

def yesterday():
    # Get today.
    today = date.today()

    # Subtract timedelta of 1 day.
    yesterday = today - timedelta(days=1)
    return yesterday

print(date.today())
print(yesterday())

Output

2013-02-21
2013-02-20

Tomorrow. This is the best day to do an annoying task. It is computed in the same way as yesterday. We add a timedelta of one day to the current day. Here we use a shorter method body.

Info: Helper methods, such as tomorrow and yesterday, are a useful abstraction in certain programs. They are reusable.

Python program that gets tomorrow

from datetime import date
from datetime import timedelta

def tomorrow():
    # Add one day delta.
    return date.today() + timedelta(days=1)

print(date.today())
print(tomorrow())

Output

2013-02-21
2013-02-22

Sort dates. A list of dates can be sorted. Suppose a program has an unordered list of dates. Often we will need to order them chronologically, from first to last (or in reverse).

List

Here: We create a list and append four new dates to it. These are all dates in the future. They are not chronologically ordered.

Then: We invoke the sort method on the list. In a for-loop, we display the dates, now ordered from first to last in time.

Python program that sorts date list

from datetime import date, timedelta

# Create a list of dates.
values = []
values.append(date.today() + timedelta(days=300))
values.append(date.today() + timedelta(days=2))
values.append(date.today() + timedelta(days=1))
values.append(date.today() + timedelta(days=20))

# Sort the list.
values.sort()

# Display.
for d in values:
    print(d)

Output

2013-10-13
2013-10-14
2013-11-01
2014-08-08

Timedelta. No two points in time are the same. In Python we express the difference between two dates with timedelta. To use timedelta, provide the arguments using names.

Here: In this program, we subtract one hour from one day. And, as you might expect, the result is 23 hours.

Python program that uses timedelta

from datetime import timedelta

# This represents 1 day.
a = timedelta(days=1)

# Represents 1 hour.
b = timedelta(hours=1)

# Subtract 1 hour from 1 day.
c = a - b
print(c)

Output

23:00:00

Timedelta arguments. Next, we consider the possible arguments to timedelta in more detail. You can specify more than argument to timedelta—simply use a comma to separate them.

Note: Large units like years, and small units, like nanoseconds, are not included in the Timedelta calls.

Timedelta arguments, smallest to largest

microseconds,
milliseconds,
seconds,
minutes,
hours,
days,
weeks

File, timestamps. This program uses the os.path and date modules. It gets the access, modification and creation of time of a file. You will need to change the file name to one that exists.

os.path

Float: In many programs we prefer a date type, not a float type. Dates are easier to understand and print.

So: We use the fromtimestamp method from the date module. This converts, correctly, the floats to dates.

Tip: I verified that the three dates are correct in this program according to Windows 8.1.

Python program that gets timestamps, converts to dates

from os import path
from datetime import date

# Get access, modification, and creation time.
a = path.getatime("/enable1.txt")
m = path.getmtime("/enable1.txt")
c = path.getctime("/enable1.txt")

# Display the times.
print(a, m, c)

# Convert timestamps to dates.
a2 = date.fromtimestamp(a)
m2 = date.fromtimestamp(m)
c2 = date.fromtimestamp(c)
print(a2, m2, c2)

Output, format edited

1360539846.3326 1326137807.9652 1360539846.3326
2013-02-10      2012-01-09      2013-02-10

Range. It is easy to get a range of dates. Suppose we have a start date and want the next 10 days. Loop over 1 through 10, and use timedelta to add that number of days to the original date.

Here: We get today. We then add one to ten days to today. This yields the next 10 days.

Python that gets future dates, range

from datetime import date, timedelta

# Start with today.
start = date.today()
print(start)

# Add 1 to 10 days and get future days.
for add in range(1, 10):
    future = start + timedelta(days=add)
    print(future)

Output

2014-04-21
2014-04-22
2014-04-23
2014-04-24
2014-04-25
2014-04-26
2014-04-27
2014-04-28
2014-04-29
2014-04-30

Cache. Getting the date, as with date.today(), is slow. This call must access the operating system. An easy way to optimize this is to cache dates.

Loop 1: This loop access date.today() once on each iteration through the loop. It runs much slower.

Loop 2: The date.today() call is cached in a variable before the loop runs. This makes each iteration much faster. We hoist the call.

Also: The logic checks the year of the date. This can be changed for the current year.

Python that caches date

import time
from datetime import date

# Time 1.
print(time.time())

# Accesses today repeatedly.
i = 0
while i < 100000:
    t = date.today()
    if t.year != 2013:
        raise Exception()
    i += 1

# Time 2.
print(time.time())

# Accesses today once.
i = 0
t = date.today()
while i < 100000:
    if t.year != 2013:
        raise Exception()
    i += 1

# Time 3.
print(time.time())

Results

1361485333.238
1361485333.411    Loop 1 = 0.173
1361485333.435    Loop 2 = 0.024

Some research. Human beings like to make things as complicated as possible. This is true with dates and times. We apply political concepts like daylight saving time.

An aware object has sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information.... A naive object does not....

Datetime: Python.org

In conclusion, the Python environment has strong support for time handling. These libraries are built into the environment. They do not need to be recreated in each program.

This yields faster, more reliable software. Certain aspects of time handling, such as computing calendar dates by offsets, is best left to sophisticated libraries.

Related Links