Python time.localtime Function

Last modified April 11, 2025

This comprehensive guide explores Python’s time.localtime function, which converts seconds since epoch to a local time struct. We’ll cover time structs, formatting, timezone handling, and practical examples.

Basic Definitions

The time.localtime function converts seconds since the epoch to a time struct in local time. It returns a named tuple with time components.

Key characteristics: accounts for timezone and daylight saving time, returns a struct_time object, and is the inverse of time.mktime. The function accepts an optional seconds parameter.

Basic Time Struct Conversion

The simplest use of time.localtime converts current time to a local time struct. This example shows basic usage and struct attributes.

basic_localtime.py

import time

Get current local time

local_time = time.localtime() print(“Local time struct:”, local_time)

Access struct components

print(f"Year: {local_time.tm_year}") print(f"Month: {local_time.tm_mon}") print(f"Day: {local_time.tm_mday}") print(f"Hour: {local_time.tm_hour}") print(f"Minute: {local_time.tm_min}") print(f"Second: {local_time.tm_sec}")

This example demonstrates getting the current local time as a struct and accessing its components. The struct contains year, month, day, and more.

The tm_isdst flag indicates daylight saving time (1 for DST, 0 for not, -1 for unknown).

Converting Timestamp to Local Time

time.localtime can convert specific timestamps to local time. This example shows conversion of a fixed timestamp.

timestamp_conversion.py

import time

Unix epoch timestamp (January 1, 1970)

epoch_time = 0 epoch_local = time.localtime(epoch_time) print(“Epoch in local time:”, epoch_local)

Specific timestamp (July 20, 1969 moon landing)

moon_landing = -14159025 moon_local = time.localtime(moon_landing) print(“Moon landing in local time:”, moon_local)

Format the output

formatted = time.strftime("%B %d, %Y at %I:%M %p", moon_local) print(“Formatted moon landing:”, formatted)

This shows how to convert specific moments in history to local time. Negative timestamps represent dates before the Unix epoch.

The strftime function formats the struct into a readable string. Format codes like %B (month name) make output more presentable.

Comparing localtime and gmtime

While localtime converts to local time, gmtime converts to UTC. This example compares both functions.

localtime_vs_gmtime.py

import time

Get current timestamp

now = time.time()

Convert to local and UTC time

local = time.localtime(now) utc = time.gmtime(now)

print(“Local time struct:”, local) print(“UTC time struct:”, utc)

Calculate timezone offset

hour_diff = local.tm_hour - utc.tm_hour print(f"Timezone offset: {hour_diff} hours")

The difference between local and UTC time shows your timezone offset. This varies by location and daylight saving time status.

Note the structs are identical except for the hour component when your timezone isn’t UTC±0.

Working with Time Struct Components

Time structs allow easy access to date components. This example shows practical uses of struct components.

struct_components.py

import time

def is_weekend(): local = time.localtime() # tm_wday ranges from 0 (Monday) to 6 (Sunday) return local.tm_wday >= 5

def season(): local = time.localtime() month = local.tm_mon if month in (12, 1, 2): return “Winter” elif month in (3, 4, 5): return “Spring” elif month in (6, 7, 8): return “Summer” else: return “Autumn”

print(“Is it weekend?”, is_weekend()) print(“Current season:”, season())

The tm_wday attribute gives weekday (0-6) and tm_mon gives month (1-12). These enable date-based logic without parsing strings.

This approach is more efficient than string parsing when you need specific date components.

Daylight Saving Time Handling

time.localtime automatically handles daylight saving time. This example demonstrates DST detection and adjustment.

daylight_saving.py

import time

def check_dst(): local = time.localtime() if local.tm_isdst == 1: return “Daylight Saving Time is in effect” elif local.tm_isdst == 0: return “Standard Time is in effect” else: return “DST status unknown”

Test around DST transition (example for US/Eastern)

dst_start = time.mktime((2025, 3, 9, 2, 0, 0, 0, 0, -1)) dst_end = time.mktime((2025, 11, 2, 2, 0, 0, 0, 0, -1))

print(“Current DST status:”, check_dst()) print(“March 9, 2025 2:00 AM:”, time.localtime(dst_start)) print(“November 2, 2025 2:00 AM:”, time.localtime(dst_end))

The tm_isdst flag indicates DST status. When set to -1, the function determines DST status automatically.

Note DST transition rules vary by timezone. The example shows US/Eastern transition points for 2025.

Creating Custom Date Strings

Time structs enable flexible date formatting. This example shows custom string creation from local time.

custom_formatting.py

import time

def friendly_date(): local = time.localtime() weekday = [“Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday”, “Sunday”][local.tm_wday] month = [“January”, “February”, “March”, “April”, “May”, “June”, “July”, “August”, “September”, “October”, “November”, “December”][local.tm_mon - 1]

suffix = "th"
if 4 <= local.tm_mday <= 20 or 24 <= local.tm_mday <= 30:
    suffix = "th"
else:
    suffix = ["st", "nd", "rd"][local.tm_mday % 10 - 1]

return f"{weekday}, {month} {local.tm_mday}{suffix}, {local.tm_year}"

print(“Today is:”, friendly_date())

This creates a human-friendly date string like “Tuesday, April 11th, 2025”. It handles proper ordinal suffixes (st, nd, rd, th) for dates.

The example demonstrates manual formatting when strftime doesn’t provide needed flexibility.

Best Practices

• Timezone awareness: Remember localtime depends on system timezone settings

• DST handling: Use tm_isdst=-1 to auto-detect daylight saving time

• Struct immutability: time structs are read-only named tuples

• Efficiency: Prefer struct attributes over string parsing

• Portability: Test timezone behavior across deployment environments

Source References

• Python time.localtime Documentation

• Python struct_time Documentation

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.