timetuple() converts a date or datetime into a time.struct_time, the 9-field tuple used by the time module: year, month, day, hour, minute, second, weekday (Monday 0), day of the year (1 to 366), and a DST flag.
The tm_isdst flag is -1 when dst() returns None (naive values and fixed offsets), 1 when it returns a non-zero timedelta, and 0 otherwise. No time zone conversion happens; for UTC fields use utctimetuple().
datetime.timetuple() is an instance method of datetime.datetime: call it on an existing object with dot notation, such as moment.timetuple(...). Import the class first, for example from datetime import datetime. The date class has a method with the same name.
Syntax
Call it with no arguments and read the fields by name or index.
Naive gives -1. Without a tzinfo there is no DST information at all.
Fixed offsets give -1 too.timezone.utc.dst() returns None, so the flag stays unknown.
Winter in the toy zone. In January dst() returns timedelta(0), so the flag is 0.
Summer in the toy zone. In July dst() returns one hour, so the flag is 1.
Example 3 — Pass timetuple() to time.strftime()
Functions in the time module accept a struct_time. Print the day of the year next to a formatted date for three holidays (C/English locale).
python
import time
from datetime import date
holidays = [date(2024, 1, 1), date(2024, 7, 4), date(2024, 12, 25)]
for day in holidays:
tt = day.timetuple()
print(tt.tm_yday, time.strftime("%d %b", tt), tt.tm_hour)
Output
1 01 Jan 0
186 04 Jul 0
360 25 Dec 0
How It Works
Dates work too.date.timetuple() fills the time fields with zeros.
Day of the year. 4 July is day 186 in leap year 2024, and 25 December is day 360.
time module bridge.time.strftime() takes the struct_time directly, which helps with older APIs.
Frequently Asked Questions
A named tuple from the time module with 9 fields: year, month, day, hour, minute, second, weekday, day of year, and DST flag.
Use d.timetuple().tm_yday, or d.strftime("%j") for zero-padded text.
The value is naive, or its tzinfo is a fixed offset whose dst() returns None.
No, it keeps the wall-clock fields. Use utctimetuple() for UTC fields.