Python - Time Module

Time Module in Python

In Python, the time module is part of the standard library and is used for working with time-related tasks. It provides access to time-related functions that are crucial for applications involving delays, timestamps, performance measurement, and formatted time output. This document offers a comprehensive overview of the time module, its functions, and real-world usage examples.

Introduction to the time Module

Importing the time Module

Before using any functionality from the time module, it must be imported:

import time

What is Epoch?

Epoch is the point where the time starts. On most systems, the epoch is January 1, 1970, 00:00:00 (UTC). The time module works with time values as the number of seconds since the epoch.

time.time()

This function returns the current time in seconds since the epoch as a floating-point number.

current_time = time.time()
print("Seconds since epoch:", current_time)

time.sleep()

Used to delay the execution of the program for a given number of seconds.

print("Start sleeping...")
time.sleep(3)
print("Woke up after 3 seconds")

Working with time.struct_time

What is struct_time?

Many functions in the time module either accept or return time in struct_time format. It is a named tuple with nine components: year, month, day, hour, minute, second, weekday, yearday, and DST flag.

time.localtime()

Returns the current local time as a struct_time object.

local = time.localtime()
print("Local time:", local)

Accessing struct_time Attributes

print("Year:", local.tm_year)
print("Month:", local.tm_mon)
print("Day:", local.tm_mday)

time.gmtime()

Returns the current time in UTC as a struct_time object.

utc_time = time.gmtime()
print("UTC time:", utc_time)

time.mktime()

Converts a struct_time to seconds since the epoch.

timestamp = time.mktime(local)
print("Epoch time:", timestamp)

Formatted Time Strings

time.strftime()

Converts a struct_time object to a string representation, based on the format string provided.

formatted = time.strftime("%Y-%m-%d %H:%M:%S", local)
print("Formatted:", formatted)

Common Format Codes

• %Y - Year with century
• %m - Month (01 to 12)
• %d - Day of the month (01 to 31)
• %H - Hour (00 to 23)
• %M - Minute (00 to 59)
• %S - Second (00 to 59)

time.strptime()

Parses a string into a struct_time object based on the specified format.

date_string = "2025-06-27 15:30:00"
parsed = time.strptime(date_string, "%Y-%m-%d %H:%M:%S")
print("Parsed struct_time:", parsed)

time.asctime()

Converts a struct_time to a readable 24-character string.

readable = time.asctime(local)
print("Asctime:", readable)

time.ctime()

Returns a human-readable string representation of the time.

print("Current time:", time.ctime())

Performance Measurement with time

time.perf_counter()

Returns the value of a high-resolution performance counter, useful for benchmarking.

start = time.perf_counter()
time.sleep(1.5)
end = time.perf_counter()
print("Elapsed time:", end - start)

time.process_time()

Returns the CPU time used by the current process.

start = time.process_time()
for i in range(1000000):
    pass
end = time.process_time()
print("CPU time:", end - start)

Using time.monotonic()

Returns a monotonic clock, which means the value cannot go backward.

start = time.monotonic()
time.sleep(2)
end = time.monotonic()
print("Monotonic time:", end - start)

Working with Time Zones and Daylight Saving Time

time.timezone

Returns the offset in seconds of the local non-DST timezone from UTC.

print("Timezone offset (seconds):", time.timezone)

time.altzone

Returns the offset during DST.

print("DST offset (seconds):", time.altzone)

time.daylight

Returns whether DST is in effect (1) or not (0).

print("Is daylight saving time used?", time.daylight)

time.tzname

Returns a tuple of two strings: standard time and DST time zone names.

print("Time zone names:", time.tzname)

Practical Examples

Countdown Timer

import time

def countdown(seconds):
    while seconds:
        print("Time left:", seconds)
        time.sleep(1)
        seconds -= 1
    print("Time's up!")

countdown(5)

Event Logger

def log_event(event):
    timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
    print(f"[{timestamp}] {event}")

log_event("Application Started")
time.sleep(2)
log_event("Application Ended")

Measuring Function Execution Time

def sample_function():
    total = 0
    for i in range(1000000):
        total += i
    return total

start = time.perf_counter()
sample_function()
end = time.perf_counter()
print("Function execution time:", end - start)

time Module vs datetime Module

time Module Strengths

• Low-level control
• Precise timing
• Benchmarking tools

datetime Module Strengths

• High-level date arithmetic
• Time zone support (with external libraries)
• Easier parsing and formatting

Handling Timestamps in Files

Using time.ctime() for file logs

with open("log.txt", "a") as f:
    f.write(f"{time.ctime()} - Task completed\n")

Loop Scheduling with time.sleep()

for i in range(3):
    print("Running task", i + 1)
    time.sleep(1)

Simulating Clock

import time

while True:
    print(time.strftime("%H:%M:%S", time.localtime()))
    time.sleep(1)

Converting Between Formats

String to Epoch

date_string = "2025-06-27 14:00:00"
struct = time.strptime(date_string, "%Y-%m-%d %H:%M:%S")
epoch = time.mktime(struct)
print("Epoch time:", epoch)

Epoch to Formatted String

formatted = time.strftime("%A, %d %B %Y", time.localtime(epoch))
print("Formatted:", formatted)

Edge Cases and Tips

Floating Point Accuracy

Always be cautious when comparing two floating-point time values due to potential rounding errors.

Performance Benchmarking

Use time.perf_counter() for benchmarking over time.time().

Cross-Platform Compatibility

Not all time module features behave the same on every platform. For example, time.clock() was deprecated and removed in Python 3.8.

The Python time module is a versatile and essential part of time-based programming. Whether you are building countdown timers, logging systems, performance benchmarks, or simply need to delay execution, understanding the capabilities of this module is critical. Its combination with other modules such as datetime or threading makes it even more powerful. Mastering its use prepares you to tackle a broad range of programming challenges effectively and efficiently.