ports: Add utime.gmtime() function.

To portably get the Epoch.  This is simply aliased to localtime() on ports
that are not timezone aware.

Signed-off-by: Damien George <damien@micropython.org>

docs/library/utime.rst

@@ -36,11 +36,17 @@ behave not as expected.
 Functions
 ---------
 
-.. function:: localtime([secs])
+.. function:: gmtime([secs])
+              localtime([secs])
 
-   Convert a time expressed in seconds since the Epoch (see above) into an 8-tuple which
-   contains: (year, month, mday, hour, minute, second, weekday, yearday)
-   If secs is not provided or None, then the current time from the RTC is used.
+   Convert the time *secs* expressed in seconds since the Epoch (see above) into an
+   8-tuple which contains: ``(year, month, mday, hour, minute, second, weekday, yearday)``
+   If *secs* is not provided or None, then the current time from the RTC is used.
+
+   The `gmtime()` function returns a date-time tuple in UTC, and `localtime()` returns a
+   date-time tuple in local time.
+
+   The format of the entries in the 8-tuple are:
 
    * year includes the century (for example 2014).
    * month   is 1-12

ports/cc3200/mods/modutime.c

@@ -133,6 +133,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(time_sleep_obj, time_sleep);
 STATIC const mp_rom_map_elem_t time_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__),        MP_ROM_QSTR(MP_QSTR_utime) },
 
+    { MP_ROM_QSTR(MP_QSTR_gmtime),          MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_localtime),       MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_mktime),          MP_ROM_PTR(&time_mktime_obj) },
     { MP_ROM_QSTR(MP_QSTR_time),            MP_ROM_PTR(&time_time_obj) },

ports/esp32/modutime.c

@@ -85,6 +85,7 @@ MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time);
 STATIC const mp_rom_map_elem_t time_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_utime) },
 
+    { MP_ROM_QSTR(MP_QSTR_gmtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_localtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_mktime), MP_ROM_PTR(&time_mktime_obj) },
     { MP_ROM_QSTR(MP_QSTR_time), MP_ROM_PTR(&time_time_obj) },

ports/esp8266/modules/ntptime.py

@@ -29,12 +29,11 @@ def time():
     return val - NTP_DELTA
 
 
-# There's currently no timezone support in MicroPython, so
-# utime.localtime() will return UTC time (as if it was .gmtime())
+# There's currently no timezone support in MicroPython, and the RTC is set in UTC time.
 def settime():
     t = time()
     import machine
     import utime
 
-    tm = utime.localtime(t)
+    tm = utime.gmtime(t)
     machine.RTC().datetime((tm[0], tm[1], tm[2], tm[6] + 1, tm[3], tm[4], tm[5], 0))

ports/esp8266/modutime.c

@@ -108,6 +108,7 @@ MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time);
 STATIC const mp_rom_map_elem_t time_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_utime) },
 
+    { MP_ROM_QSTR(MP_QSTR_gmtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_localtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_mktime), MP_ROM_PTR(&time_mktime_obj) },
     { MP_ROM_QSTR(MP_QSTR_sleep), MP_ROM_PTR(&mp_utime_sleep_obj) },

ports/stm32/modutime.c

@@ -132,6 +132,7 @@ MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time);
 STATIC const mp_rom_map_elem_t time_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_utime) },
 
+    { MP_ROM_QSTR(MP_QSTR_gmtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_localtime), MP_ROM_PTR(&time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_mktime), MP_ROM_PTR(&time_mktime_obj) },
     { MP_ROM_QSTR(MP_QSTR_time), MP_ROM_PTR(&time_time_obj) },

ports/unix/modtime.c

@@ -132,7 +132,7 @@ STATIC mp_obj_t mod_time_sleep(mp_obj_t arg) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mod_time_sleep_obj, mod_time_sleep);
 
-STATIC mp_obj_t mod_time_localtime(size_t n_args, const mp_obj_t *args) {
+STATIC mp_obj_t mod_time_gm_local_time(size_t n_args, const mp_obj_t *args, struct tm *(*time_func)(const time_t *timep)) {
     time_t t;
     if (n_args == 0) {
         t = time(NULL);
@@ -144,7 +144,7 @@ STATIC mp_obj_t mod_time_localtime(size_t n_args, const mp_obj_t *args) {
         t = mp_obj_get_int(args[0]);
         #endif
     }
-    struct tm *tm = localtime(&t);
+    struct tm *tm = time_func(&t);
 
     mp_obj_t ret = mp_obj_new_tuple(9, NULL);
 
@@ -165,6 +165,15 @@ STATIC mp_obj_t mod_time_localtime(size_t n_args, const mp_obj_t *args) {
 
     return ret;
 }
+
+STATIC mp_obj_t mod_time_gmtime(size_t n_args, const mp_obj_t *args) {
+    return mod_time_gm_local_time(n_args, args, gmtime);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mod_time_gmtime_obj, 0, 1, mod_time_gmtime);
+
+STATIC mp_obj_t mod_time_localtime(size_t n_args, const mp_obj_t *args) {
+    return mod_time_gm_local_time(n_args, args, localtime);
+}
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mod_time_localtime_obj, 0, 1, mod_time_localtime);
 
 STATIC mp_obj_t mod_time_mktime(mp_obj_t tuple) {
@@ -210,6 +219,7 @@ STATIC const mp_rom_map_elem_t mp_module_time_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_ticks_cpu), MP_ROM_PTR(&mp_utime_ticks_cpu_obj) },
     { MP_ROM_QSTR(MP_QSTR_ticks_add), MP_ROM_PTR(&mp_utime_ticks_add_obj) },
     { MP_ROM_QSTR(MP_QSTR_ticks_diff), MP_ROM_PTR(&mp_utime_ticks_diff_obj) },
+    { MP_ROM_QSTR(MP_QSTR_gmtime), MP_ROM_PTR(&mod_time_gmtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_localtime), MP_ROM_PTR(&mod_time_localtime_obj) },
     { MP_ROM_QSTR(MP_QSTR_mktime), MP_ROM_PTR(&mod_time_mktime_obj) },
 };