Wall-clock timestamps
Record event timestamps or generate epoch-based identifiers.
Python · Module
time
Python’s time module provides clocks, sleeping, epoch-based conversions, and formatting utilities. Use wall-clock functions for timestamps and monotonic or performance counters for measuring elapsed durations.
How it works
The time module exposes clocks, sleeping, epoch conversions, formatting, and platform-related timing information. Use wall-clock functions for timestamps and monotonic performance counters for measuring durations.
Syntax
import time
time.time()
time.time_ns()
time.sleep(secs)
time.gmtime([secs])
time.localtime([secs])
time.strftime(format[, t])
time.strptime(string[, format])Parameters
| Name | Type | Description |
|---|---|---|
format | str | Format string containing directives that control the resulting textual representation. |
secs | float | None | Optional epoch timestamp; when omitted, the current time is used. |
Returns
The module provides clock values, epoch conversions, formatted strings, parsed struct_time values, and sleep operations; exact return types depend on the selected function.
Key points
- The module groups clocks, delays, conversions, formatting helpers, and platform timing information.
- Epoch timestamps measure elapsed time from a platform-defined starting point; inspect gmtime(0) to identify it.
- time.time() supplies the current wall-clock timestamp as floating-point epoch seconds.
- time.time_ns() provides the current epoch timestamp as an integer count of nanoseconds.
- gmtime() turns epoch seconds into a UTC struct_time suitable for reading calendar components.
- struct_time is the documented result type for several parsing and calendar-conversion functions, with named fields.
- Pass epoch seconds to gmtime() or localtime() when calendar fields are needed.
Common mistakes
- Some functions depend on platform support, so portable code should account for availability differences.
- Epoch-based values generally do not count leap seconds.
- A timestamp from time() is a numeric epoch value, not a calendar object; convert it before displaying calendar fields.
Example: Measure elapsed time
import time
started = time.perf_counter()
time.sleep(0.01)
elapsed = time.perf_counter() - started
print(f"Elapsed: {elapsed:.3f}s")Measures elapsed duration with a monotonic performance counter and pauses briefly.
When to use it
Elapsed-time measurement
Measure request, job, or function duration without being affected by wall-clock corrections.
Delays and backoff
Pause between polling attempts or implement simple retry delays.
Time conversion and formatting
Convert epoch values into UTC or local calendar fields and format them for output.
Interview questions
QWhat does time.time() return, and when should it be used?
time.time() returns the current wall-clock time as seconds since the epoch, represented as a floating-point number. It is appropriate for timestamps, but wall-clock adjustments can affect elapsed-time calculations.
Follow-up: Which clock should measure a duration? Use time.monotonic() or time.perf_counter(), because these clocks are intended for elapsed-time measurement rather than civil timestamps.
QWhat is a limitation of time.sleep()?
time.sleep() suspends execution for at least the requested interval, although scheduling and system activity can make the actual delay longer. It is useful for pauses and retry backoff.
Follow-up: How should a precise short duration be measured? Record time.perf_counter() before and after the operation and subtract the readings.
QHow do gmtime() and localtime() differ?
gmtime() converts epoch seconds to a UTC struct_time, while localtime() converts them to local time. struct_time exposes calendar fields through both indexes and named attributes.
Follow-up: How can a struct_time become epoch seconds? Use calendar.timegm() for UTC or mktime() for local time.
Related
datetimecalendartime.timetime.time_nstime.monotonictime.perf_countertime.sleeptime.gmtime