utime
– Time functions¶
Differences to CPython
This module implements a subset of the corresponding CPython 3.5 module, as described below. For more information, refer to the original CPython documentation: time (version 3.5).
This module is used when executing on SR OS only. On a remote machine, the native Python time module is used.
The utime
module provides functions for getting the current time and date,
measuring time intervals, and for delays.
Functions¶
- utime.gmtime(secs)¶
Convert a time, expressed in seconds, since the epoch to a
struct_time
. If secs is not provided orNone
, the current time is returned bytime()
. Fractions of a second are ignored.- Parameters
secs (int, optional) – Seconds since epoch. Default
None
- Returns
Structured time object in UTC where the dst flag is 0.
- Return type
.struct_time
- utime.localtime(secs)¶
Operates like
gmtime()
but converts to the local time. The local time is defined by the timezone configured on SR OS in the/configure system time zone
context.- Parameters
secs (int, optional) – Seconds since epoch. Default
None
- Returns
Structured time object in local time. The dst flag is set to 1 when DST applies to the given time.
- Return type
.struct_time
- utime.mktime(t)¶
This is the inverse function of
localtime()
. The earliest date for which it can generate a time on SR OS is the epoch.- Parameters
t (.struct_time, tuple(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)) – Time in local time, not UTC. The dst flag is required; use
-1
as the dst flag value if it is unknown.- Returns
Floating point number compatible with
time()
. If the input value cannot be represented as a valid time, eitherOverflowError
orValueError
is raised (depending on whether the invalid value is caught by Python or the underlying C libraries).- Return type
float
- Raises
OverflowError – Result of an arithmetic operation is too large to be represented.
ValueError – Argument has the right type but an inappropriate value, and the situation is not described by a more precise exception.
- utime.sleep(secs)¶
- utime.sleep_ms(millisecs)¶
- utime.sleep_us(microsecs)¶
Suspend execution for the given period of time. The suspension time may be longer than requested by an arbitrary amount because of the scheduling of other activities in the system.
- Parameters
secs (int, float) – Time, in seconds.
millisecs (int, float) – Time, in milliseconds.
microsecs (int, float) – Time, in microseconds.
- utime.strftime(format, t)¶
Convert a tuple or
struct_time
representing a time as returned bygmtime()
orlocaltime()
to a string as specified by the format argument. If t is not provided, the current time as returned bylocaltime()
is used.- Parameters
format (str) – Output format template. Accepted directives for the template can be found in the table below Format directives.
t (
struct_time
, tuple, optional) – Time
- Returns
Formatted string
- Return type
str
- Raises
ValueError – Any field in t is outside of the allowed range.
Note
0 is a valid input for any position in the time tuple. If the value is invalid, the value is changed 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.¶ Directive
Meaning
Notes
%a
Abbreviated weekday name in English.
%A
Weekday name in English.
%b
Abbreviated month name in English.
%B
Full month name in English.
%c
Date and time representation.
%d
Day of the month as a decimal number [Range: 01-31].
%H
Hour (24-hour clock) as a decimal number [Range: 00-23].
%I
Hour (12-hour clock) as a decimal number [Range: 01-12].
%j
Day of the year as a decimal number [Range: 001-366].
%m
Month as a decimal number [Range: 01-12].
%M
Minute as a decimal number [Range: 00-59].
%p
AM or PM.
%S
Second as a decimal number [Range: 00-59].
%U
Week number of the year (Sunday as the first day of the week) as a decimal number [Range: 00-53]. All days in a new year preceding the first Sunday are considered to be in week 0.
%w
Weekday as a decimal number [Range: 0-6]. 0 is considered to mean Sunday.
%W
Week number of the year (Monday as the first day of the week) as a decimal number [Range: 00-53]. All days in a new year preceding the first Monday are considered to be in week 0.
%x
Locale’s appropriate date representation.
%X
Locale’s appropriate time representation.
%y
Year without century as a decimal number [Range: 00-99].
%Y
Year with century as a decimal number.
%%
A literal
'%'
character.
Notes:
- 1
Output uses English words and is all uppercase characters.
Example to format a date and time into RFC 2822 Internet email standard:
>>> from time import gmtime, strftime >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) 'THU, 28 JUN 2001 14:17:15 +0000'
- class utime.struct_time¶
The type of the time value sequence returned by
gmtime()
andlocaltime()
. It is an object with a named tuple interface. Values can be accessed by index or by attribute name.When a tuple with an incorrect length is passed to a function expecting a
struct_time
, or has elements of the wrong type, aTypeError
is raised. The following values are present:¶ Index
Attribute
Values
0
tm_year
Example: 1993
1
tm_mon
[Range: 1-12] 2
2
tm_mday
[Range: 1-31]
3
tm_hour
[Range: 0-23]
4
tm_min
[Range: 0-59]
5
tm_sec
[Range: 0-59]
6
tm_wday
[Range: 0-6]. Monday is 0
7
tm_yday
[Range: 1-366]
8
tm_isdst
0, 1 or -1 3
N/A
tm_zone
Abbreviation of timezone name
N/A
tm_gmtoff
Offset east of UTC in seconds
Notes:
- 2
Note that unlike the C structure, the month value is a range of 1-12, not 0-11.
- 3
In calls to
mktime()
,tm_isdst
may be set to 1 when daylight savings time is in effect, and 0 when it is not. A value of -1 indicates that this is not known, and results in the correct state being filled in.
- utime.ticks_ms()¶
Return an increasing millisecond counter with an arbitrary reference point, that wraps around after some value.
The wraparound value is not explicitly exposed, but for discussion, is referred to as TICKS_MAX. Period of the values is TICKS_PERIOD = TICKS_MAX + 1. TICKS_PERIOD is guaranteed to be a power of two, but otherwise may differ.
The same period value is used for all of
ticks_ms()
,ticks_us()
,ticks_cpu()
functions (for simplicity). Therefore, these functions return a value in the range [0 .. TICKS_MAX], inclusive, total TICKS_PERIOD values.Values returned by these functions should be treated as opaque. The only operations available are
ticks_diff()
andticks_add()
.- Returns
Increasing millisecond counter with an arbitrary reference point.
- Return type
int
Note
Note that only non-negative values are used.
Note
Standard mathematical operations (e.g. +, -), or relational operators (e.g. <, <=, >, >=) cannot be performed directly on these values. Invalid results also occur if results from mathematical operations are passed as arguments to
ticks_diff()
orticks_add()
.
- utime.ticks_us()¶
Similar to
ticks_ms()
, but in microseconds.- Returns
Increasing microseconds counter with an arbitrary reference point.
- Return type
int
- utime.ticks_cpu()¶
Similar to
ticks_ms()
and ticks_us, but with the highest possible resolution in the system.- Returns
Increasing counter with an arbitrary reference point.
- Return type
int
- utime.ticks_add(ticks, delta)¶
Offset the value of ticks by a given (positive or negative) delta.
Given a ticks value, this function calculates the ticks value delta ticks before or after it, using the modular-arithmetic definition of tick values (see
ticks_ms()
).ticks_add()
is useful for calculating deadlines for events/tasks.- Parameters
ticks (int) – ticks value as a direct result of a call to
ticks_ms()
,ticks_us()
orticks_cpu()
or from a previous call toticks_add()
.delta (int, expr) – Positive or negative integer number or numeric expression.
- Returns
Calculated value of ticks.
- Return type
int
Note
Use
ticks_diff()
function to work with deadlines.Example:
# Find out what ticks value 100ms ago print(ticks_add(time.ticks_ms(), -100)) # Calculate deadline for operation and test for it deadline = ticks_add(time.ticks_ms(), 200) while ticks_diff(deadline, time.ticks_ms()) > 0: do_a_little_of_something() # Find out TICKS_MAX used by this port print(ticks_add(0, -1))
- utime.ticks_diff(ticks1, ticks2)¶
Measure ticks difference between values returned from
ticks_ms()
,ticks_us()
, orticks_cpu()
functions, as a signed value which may wrap around. The function has the same meaning asticks1 - ticks2
.Values returned by
ticks_ms()
,ticks_us()
orticks_cpu()
may wrap around. Directly using a subtraction operation produces an incorrect result. Use theticks_diff()
function provided.The function implements modular (or more specifically, ring) arithmetic to produce the correct result, even for wraparound values (as long as there is not too much of a difference between them).
If the result is negative, it means that ticks1 occurred earlier in time than ticks2. Otherwise, it means that ticks1 occurred after ticks2. This holds only if ticks1 and ticks2 are apart from each other for no more than TICKS_PERIOD/2-1 ticks. If that does not hold, an incorrect result is returned. That is, if two tick values are apart for TICKS_PERIOD/2-1 ticks, that value is returned by the function. However, if TICKS_PERIOD/2 of real-time ticks has passed between them, the function returns -TICKS_PERIOD/2 instead. That is, the result value wraps to the negative range of possible values.
- Returns
Signed value in the range [-TICKS_PERIOD/2 .. TICKS_PERIOD/2-1], which is a typical range definition for a two’s-completment signed binary integer.
- Return type
int (signed)
Note
Do not pass
time()
values toticks_diff()
. Use standard mathematical operations instead.
- utime.time()¶
Return the time in seconds since the epoch.
The number returned by
time()
may be converted to a more common time format (i.e. year, month, day, hour, etc…) in UTC by passing it togmtime()
function, or in local time by passing it to thelocaltime()
function. In both cases, astruct_time
object is returned, from which the components of the calendar date may be accessed as attributes.- Returns
Time in seconds since the epoch.
- Return type
float
- utime.tzset()¶
Reset the time conversion rules used by the library routines. When invoked, the current time configuration is inspected and the variables
tzname
,timezone
(non-DST seconds West of UTC),altzone
(DST seconds west of UTC) anddaylight
are set.daylight
is set to 0 if the timezone does not have daylight saving time rules, or to nonzero if there is a time (past, present or future) when daylight saving time applies.
Timezone constants¶
- utime.altzone¶
The offset of the local DST timezone, in seconds, west of UTC (if one is defined). The offset is negative if the local DST timezone is east of UTC (such as Western Europe, including the UK). Only use this if
daylight
is nonzero. See the note on timezone constants.
- utime.daylight¶
Nonzero if a DST timezone is defined. See the note on timezone constants.
- utime.timezone¶
The offset of the local (non-DST) timezone, in seconds, west of UTC (negative in most of Western Europe, positive in the USA, zero in the UK). See the note on timezone constants.
- utime.tzname¶
A tuple of two strings:
Name of the local non-DST timezone
Name of the local DST timezone
If no DST timezone is defined, the second string should not be used. See the note on timezone constants.
Note
For the above timezone constants (altzone
, daylight
, timezone
,
and tzname
), the value is determined by the timezone configuration in effect
at module load time or the last time tzset()
is called, and may be incorrect for
times in the past. Nokia recommends using the tm_gmtoff
and tm_zone
results from localtime()
to obtain timezone information.