`!time` --- Time access and conversions

asctime([time_tuple])

Convert a tuple or struct_time representing a time as returned by gmtime or localtime to a string of the following form: 'Sun Jun 20 23:21:05 1993'. The day field is two characters long and is space padded if the day is a single digit, for example: 'Wed Jun 9 04:26:40 1993'.

If time_tuple is not provided, the current time as returned by localtime is used. Locale information is not used by asctime.

[!NOTE] Unlike the C function of the same name, asctime does not add a trailing newline.

pthread_getcpuclockid(thread_id, /)

Return the clk_id of the thread-specific CPU-time clock for the specified thread_id.

Use threading.get_ident or the ~threading.Thread.ident attribute of threading.Thread objects to get a suitable value for thread_id.

[!WARNING] Passing an invalid or expired thread_id may result in undefined behavior, such as segmentation fault.

clock_getres(clk_id, /)

Return the resolution (precision) of the specified clock clk_id. Refer to time-clock-id-constants for a list of accepted values for clk_id.

clock_gettime(clk_id, /) -> float

Return the time of the specified clock clk_id. Refer to time-clock-id-constants for a list of accepted values for clk_id.

Use clock_gettime_ns to avoid the precision loss caused by the float type.

clock_gettime_ns(clk_id, /) -> int

Similar to clock_gettime but return time as nanoseconds.

clock_settime(clk_id, time, /)

Set the time of the specified clock clk_id. Currently, CLOCK_REALTIME is the only accepted value for clk_id.

Use clock_settime_ns to avoid the precision loss caused by the float type.

clock_settime_ns(clk_id, time: int, /)

Similar to clock_settime but set time with nanoseconds.

ctime(seconds=None, /)

Convert a time expressed in seconds since the epoch to a string of a form: 'Sun Jun 20 23:21:05 1993' representing local time. The day field is two characters long and is space padded if the day is a single digit, for example: 'Wed Jun 9 04:26:40 1993'.

If seconds is not provided or None, the current time as returned by .time is used. ctime(seconds) is equivalent to asctime(localtime(seconds)). Locale information is not used by ctime.

get_clock_info(name, /)

Get information on the specified clock as a namespace object. Supported clock names and the corresponding functions to read their value are:

• 'monotonic': time.monotonic
• 'perf_counter': time.perf_counter
• 'process_time': time.process_time
• 'thread_time': time.thread_time
• 'time': time.time

The result has the following attributes:

• adjustable: True if the clock can be set to jump forward or backward in time, False otherwise. Does not refer to gradual NTP rate adjustments.
• implementation: The name of the underlying C function used to get the clock value. Refer to time-clock-id-constants for possible values.
• monotonic: True if the clock cannot go backward, False otherwise
• resolution: The resolution of the clock in seconds (float)

gmtime(seconds=None, /)

Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If seconds is not provided or None, the current time as returned by .time is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm for the inverse of this function.

localtime(seconds=None, /)

Like gmtime but converts to local time. If seconds is not provided or None, the current time as returned by .time is used. The dst flag is set to 1 when DST applies to the given time.

localtime may raise OverflowError, if the timestamp is outside the range of values supported by the platform C localtime or gmtime functions, and OSError on localtime or gmtime failure. It's common for this to be restricted to years between 1970 and 2038.

mktime(time_tuple, /)

This is the inverse function of localtime. Its argument is the struct_time or full 9-tuple (since the dst flag is needed; use -1 as the dst flag if it is unknown) which expresses the time in local time, not UTC. It returns a floating-point number, for compatibility with .time. If the input value cannot be represented as a valid time, either OverflowError or ValueError will be raised (which depends on whether the invalid value is caught by Python or the underlying C libraries). The earliest date for which it can generate a time is platform-dependent.

monotonic() -> float

Return the value (in fractional seconds) of a monotonic clock, i.e. a clock that cannot go backwards. The clock is not affected by system clock updates. The reference point of the returned value is undefined, so that only the difference between the results of two calls is valid.

Clock:

• On Windows, call QueryPerformanceCounter() and QueryPerformanceFrequency().
• On macOS, call mach_absolute_time() and mach_timebase_info().
• On HP-UX, call gethrtime().
• Call clock_gettime(CLOCK_HIGHRES) if available.
• Otherwise, call clock_gettime(CLOCK_MONOTONIC).

Use monotonic_ns to avoid the precision loss caused by the float type.

monotonic_ns() -> int

Similar to monotonic, but return time as nanoseconds.

perf_counter() -> float

Return the value (in fractional seconds) of a performance counter, i.e. a clock with the highest available resolution to measure a short duration. It does include time elapsed during sleep. The clock is the same for all processes. The reference point of the returned value is undefined, so that only the difference between the results of two calls is valid.

Use perf_counter_ns to avoid the precision loss caused by the float type.

perf_counter_ns() -> int

Similar to perf_counter, but return time as nanoseconds.

process_time() -> float

Return the value (in fractional seconds) of the sum of the system and user CPU time of the current process. It does not include time elapsed during sleep. It is process-wide by definition. The reference point of the returned value is undefined, so that only the difference between the results of two calls is valid.

Use process_time_ns to avoid the precision loss caused by the float type.

process_time_ns() -> int

Similar to process_time but return time as nanoseconds.

sleep(seconds, /)

Suspend execution of the calling thread for the given number of seconds. The argument may be a non-integer to indicate a more precise sleep time.

If the sleep is interrupted by a signal and no exception is raised by the signal handler, the sleep is restarted with a recomputed timeout.

The suspension time may be longer than requested by an arbitrary amount, because of the scheduling of other activity in the system.

Windows implementation

On Windows, if seconds is zero, the thread relinquishes the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 10 and newer the implementation uses a high-resolution timer which provides resolution of 100 nanoseconds. If seconds is zero, Sleep(0) is used.

Unix implementation

• Use clock_nanosleep() if available (resolution: 1 nanosecond);
• Or use nanosleep() if available (resolution: 1 nanosecond);
• Or use select() (resolution: 1 microsecond).

[!NOTE] To emulate a "no-op", use pass instead of time.sleep(0).

To voluntarily relinquish the CPU, specify a real-time scheduling policy <os-scheduling-policy> and use os.sched_yield instead.

strftime(format[, time_tuple])

Convert a tuple or struct_time representing a time as returned by gmtime or localtime to a string as specified by the format argument. If time_tuple is not provided, the current time as returned by localtime is used. format must be a string. ValueError is raised if any field in time_tuple is outside of the allowed range.

0 is a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one.

The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime result:

Notes:

(1)
The %f format directive only applies to strptime, not to strftime. However, see also datetime.datetime.strptime and datetime.datetime.strftime where the %f format directive applies to microseconds <format-codes>.

(2)
When used with the strptime function, the %p directive only affects the output hour field if the %I directive is used to parse the hour.

Here is an example, a format for dates compatible with that specified in the 5322 Internet email standard.[^3] :

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C. To see the full set of format codes supported on your platform, consult the strftime(3) documentation.

On some platforms, an optional field width and precision specification can immediately follow the initial '%' of a directive in the following order; this is also not portable. The field width is normally 2 except for %j where it is 3.

strptime(string[, format])

Parse a string representing a time according to a format. The return value is a struct_time as returned by gmtime or localtime.

The format parameter uses the same directives as those used by strftime; it defaults to "%a %b %d %H:%M:%S %Y" which matches the formatting returned by ctime. If string cannot be parsed according to format, or if it has excess data after parsing, ValueError is raised. The default values used to fill in any missing data when more accurate values cannot be inferred are (1900, 1, 1, 0, 0, 0, 0, 1, -1). Both string and format must be strings.

For example:

>>> import time >>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

Support for the %Z directive is based on the values contained in tzname and whether daylight is true. Because of this, it is platform-specific except for recognizing UTC and GMT which are always known (and are considered to be non-daylight savings timezones).

Only the directives specified in the documentation are supported. Because strftime() is implemented per platform it can sometimes offer more directives than those listed. But strptime() is independent of any platform and thus does not necessarily support all directives available that are not documented as supported.

time() -> float

Return the time in seconds since the epoch as a floating-point number. The handling of leap seconds is platform dependent. On Windows and most Unix systems, the leap seconds are not counted towards the time in seconds since the epoch. This is commonly referred to as Unix time.

Note that even though the time is always returned as a floating-point number, not all systems provide time with a better precision than 1 second. While this function normally returns non-decreasing values, it can return a lower value than a previous call if the system clock has been set back between the two calls.

The number returned by .time may be converted into a more common time format (i.e. year, month, day, hour, etc...) in UTC by passing it to gmtime function or in local time by passing it to the localtime function. In both cases a struct_time object is returned, from which the components of the calendar date may be accessed as attributes.

Clock:

• On Windows, call GetSystemTimePreciseAsFileTime().
• Call clock_gettime(CLOCK_REALTIME) if available.
• Otherwise, call gettimeofday().

Use time_ns to avoid the precision loss caused by the float type.

time_ns() -> int

Similar to ~time.time but returns time as an integer number of nanoseconds since the epoch.

thread_time() -> float

Return the value (in fractional seconds) of the sum of the system and user CPU time of the current thread. It does not include time elapsed during sleep. It is thread-specific by definition. The reference point of the returned value is undefined, so that only the difference between the results of two calls in the same thread is valid.

Use thread_time_ns to avoid the precision loss caused by the float type.

thread_time_ns() -> int

Similar to thread_time but return time as nanoseconds.

tzset()

Reset the time conversion rules used by the library routines. The environment variable TZ specifies how this is done. It will also set the variables tzname (from the TZ environment variable), timezone (non-DST seconds West of UTC), altzone (DST seconds west of UTC) and daylight (to 0 if this timezone does not have any daylight saving time rules, or to nonzero if there is a time, past, present or future when daylight saving time applies).

[!NOTE] Although in many cases, changing the TZ environment variable may affect the output of functions like localtime without calling tzset, this behavior should not be relied on.

The TZ environment variable should contain no whitespace.

The standard format of the TZ environment variable is (whitespace added for clarity):

std offset [dst [offset [,start[/time], end[/time]]]]

Where the components are:

std and dst
Three or more alphanumerics giving the timezone abbreviations. These will be propagated into time.tzname

offset
The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the local time to arrive at UTC. If preceded by a '-', the timezone is east of the Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is assumed to be one hour ahead of standard time.

start[/time], end[/time]
Indicates when to change to and back from DST. The format of the start and end dates are one of the following:

J{n}
The Julian day n (1 <= n <= 365). Leap days are not counted, so in all years February 28 is day 59 and March 1 is day 60.

{n}
The zero-based Julian day (0 <= n <= 365). Leap days are counted, and it is possible to refer to February 29.

M{m}.{n}.{d}
The d'th day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means "the last d day in month m" which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d'th day occurs. Day zero is a Sunday.

time has the same format as offset except that no leading sign ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it is more convenient to use the system's zoneinfo (tzfile(5)) database to specify the timezone rules. To do this, set the TZ environment variable to the path of the required timezone datafile, relative to the root of the systems 'zoneinfo' timezone database, usually located at /usr/share/zoneinfo. For example, 'US/Eastern', 'Australia/Melbourne', 'Egypt' or 'Europe/Amsterdam'. :

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')