Home
Search
Datetime Methods: Date, TimedeltaUse the datetime module. Parses date strings and perform other useful tasks.
Python
This page was last reviewed on Dec 22, 2022.
Datetime. Often Python programs must handle or test dates in some way. We use the datetime module to handle dates. This module parses strings containing dates.
Datetime defs. The current date can be accessed with today(). And methods like strptime can be used with format codes to convert strings to dates.
Parse. To parse we have the strptime method in datetime. The name is confusing—it comes from the C standard library. This method requires two arguments.
Arguments The first argument is a string containing date information. The second argument is the format string.
Format codes:
B: The full month name. d: The digit of the day of the month. Y: The four-digit year.
from datetime import datetime # Input string. s = "August 16, 2012" # Use strptime. d = datetime.strptime(s, "%B %d, %Y") print(d)
2012-08-16 00:00:00
Exact date. Suppose you know the exact date you want to represent in a Python datetime. We can use a special constructor to get this date—no parsing is required.
from datetime import datetime # This is 20017, march 3, at 5:30 in the morning. # ... Hope you like getting up early. result = datetime(2017, 3, 1, 5, 30) print("DATETIME", result) # Verify the month. print("MONTH", result.month)
DATETIME 2017-03-01 05:30:00 MONTH 3
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.
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())
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.
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())
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, strings
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.
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)
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.
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)
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.
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.
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)
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.
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)
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
Time. With this method we get a number that indicates the total number of seconds in the time. An epoch is a period of time. For UNIX time the epoch begins at year 1970.
So The seconds returned by this program equal 46 years—the example is being tested in 2016.
import time # Get current seconds. current = time.time() print("Current seconds:", current)
Current seconds: 1471905804.3763597
Struct_time. To get detailed times, we use a method like gmtime() and then access parts of the returned struct_time. Here we access the year, month, hour and other properties.
Days Month days is the index of the day in the current month. So the 22nd of a month has "mday" of 22—this begins at index 1 not 0.
Also Weekdays and year days are indexes within those larger time ranges. Monday is "wday" 0.
import time # Get a struct indicating the current time. current = time.gmtime() # Get year. print("Year:", current.tm_year) # Get month. print("Month:", current.tm_mon) # Get day of month. print("Month day:", current.tm_mday) # Get hour. print("Hour:", current.tm_hour) # Get minute. print("Minute:", current.tm_min) # Get seconds. print("Second:", current.tm_sec) # Get day of week. print("Week day:", current.tm_wday) # Get day of year. print("Year day:", current.tm_yday) # Get whether daylight saving time. print("Is DST:", current.tm_isdst)
Year: 2016 Month: 8 Month day: 22 Hour: 22 Minute: 48 Second: 8 Week day: 0 Year day: 235 Is DST: 0
Benchmark, 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.
Version 1 This loop access date.today() once on each iteration through the loop. It runs much slower.
Version 2 The date.today() call is cached in a variable before the loop runs. This makes each iteration much faster. We hoist the call.
Result This optimization clearly improves the performance of accessing a date. But it comes with serious limitations.
import time from datetime import date # Time 1. print(time.time()) # Version 1: accesses today in a loop. i = 0 while i < 100000: t = date.today() if t.year != 2013: raise Exception() i += 1 # Time 2. print(time.time()) # Version 2: accesses today once. i = 0 t = date.today() while i < 100000: if t.year != 2013: raise Exception() i += 1 # Time 3. print(time.time())
1361485333.238 1361485333.411 Loop 1 = 0.173 1361485333.435 Loop 2 = 0.024
Filename, date.today. We can generate files with the current date in the filename. This is an effective approach for logging programs (or any program that is run once per day).
A review. 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.
Dot Net Perls is a collection of tested code examples. Pages are continually updated to stay current, with code correctness a top priority.
Sam Allen is passionate about computer languages. In the past, his work has been recommended by Apple and Microsoft and he has studied computers at a selective university in the United States.
No updates found for this page.
Home
Changes
© 2007-2023 Sam Allen.