diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..aedae76 --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) Quectel Wireless Solution, Co., Ltd.All Rights Reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d8f85d --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# QuecPython Enhanced Time & TimeZone + +[中文](README_ZH.md) | English + +## Overview + +QuecPython utime method can only support the east and west 12 time zone, but in practice, some countries with borders across the international date line in order to maintain national date unity, the original territorial date of UTC-11 is pushed forward by one day, that is, from UTC-11 plus 24H, is UTC+13. This method can extend the time zone to UTC-12 to UTC+14. + +At the same time, the utime method does not have a convenient way to set the time, so it needs to call the API of setting the time in RTC separately, and it needs to convert the date format. This method provides a method of obtaining/setting the local time in a consistent format. + +Finally, this method provides a more flexible mktime method, which can add the time zone parameter and directly obtain the time stamp of the specified time zone. + +## Usage + +- [API Reference Manual](./docs/en/API_Reference.md) + +## Contribution + +We welcome contributions to improve this project! Please follow these steps to contribute: + +1. Fork the repository. +2. Create a new branch (`git checkout -b feature/your-feature`). +3. Commit your changes (`git commit -m 'Add your feature'`). +4. Push to the branch (`git push origin feature/your-feature`). +5. Open a Pull Request. + +## License + +This project is licensed under the Apache License. See the [LICENSE](LICENSE) file for details. + +## Support + +If you have any questions or need support, please refer to the [QuecPython documentation](https://python.quectel.com/doc/en) or open an issue in this repository. diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..75814ed --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,33 @@ +# QuecPython 增强型时间及时区 + +中文 | [English](README.md) + +## 概述 + +QuecPython utime方法只能支持东西十二时区,但在实际应用中,某些国境横跨国际日期变更线的国家为保持全国日期统一,将原属UTC-11的领土日期前推一天,即从UTC-11加24H,是为UTC+13。该方法可以拓展时区至为UTC-12至UTC+14。 + +同时,utime方法没有便捷的设定时间的方法,需要另外调用RTC中设置时间的API,并且需要对日期格式做转换,本方法提供格式一致的获取/设置本地时间的方法。 + +最后,本方法提供了更为灵活的mktime方法,可以增加加时区参数,直接获取指定时区的时间戳。 + +## 用法 + +- [API 参考手册](./docs/zh/API参考手册.md) + +## 贡献 + +我们欢迎对本项目的改进做出贡献!请按照以下步骤进行贡献: + +1. Fork 此仓库。 +2. 创建一个新分支(`git checkout -b feature/your-feature`)。 +3. 提交您的更改(`git commit -m 'Add your feature'`)。 +4. 推送到分支(`git push origin feature/your-feature`)。 +5. 打开一个 Pull Request。 + +## 许可证 + +本项目使用 Apache 许可证。详细信息请参阅 [LICENSE](LICENSE) 文件。 + +## 支持 + +如果您有任何问题或需要支持,请参阅 [QuecPython 文档](https://python.quectel.com/doc) 或在本仓库中打开一个 issue。 diff --git a/utime_ex.py b/code/utime_ex.py similarity index 97% rename from utime_ex.py rename to code/utime_ex.py index 90b5ed3..49d538d 100644 --- a/utime_ex.py +++ b/code/utime_ex.py @@ -1,164 +1,164 @@ -''' -背景:标准的UTC时区应为-12到+12,但某些国境横跨国际日期变更线的国家为保持全国日期统一,将 -原属UTC-11的领土日期前推一天,即从UTC-11加24H,是为UTC+13 -''' -import utime -from machine import RTC - -class utimeextend(object): - #如果设置的时区大于UTC+12,此flag被置为True - isExtendTz = False - - """_extend_tz_handle - 内部函数,在使用扩展时区(isExtendTz = False = True)时处理时间,将时间前推24h,例如从UTC-11把时间映射到UTC+13 - - Returns: - tuple: (year, month, day, hour, minute, second, weekday, yearday) - """ - @classmethod - def _extend_tz_handle(cls): - tm_temp_in = utime.mktime(utime.localtime()) - tm_tuple_out = utime.localtime(tm_temp_in + (24*60*60)) - - return tm_tuple_out - - """localtime - 扩展原生utime的方法,不带参数时,如果isExtendTz = True,此时输出的时间应为模组的RTC时间加偏24H. - 带参数时由传入的时间戳解算出时间 - args: - args[0]:int,时间戳,单位s - args[1]:int,时区,范围-12~14,可使时间戳解算的时间加时区偏移,不填此参数则默认输出GMT时间 - - Returns: - tuple(year, month, day, hour, minute, second, weekday, yearday):返回时间 - """ - @classmethod - def localtime(cls, *args): - tm_tuple = () - if not args: - tm_tuple = cls._extend_tz_handle() if cls.isExtendTz else utime.localtime() - - elif len(args) == 1: - tm_tuple = utime.localtime(args[0] - (8*60*60)) - - elif len(args) == 2: - tm_tuple = utime.localtime(args[0] - (8*60*60) + (args[1]*60*60)) - - else: - raise(ValueError, "Arguments Error") - - return tm_tuple - - '''setTimeZoneEx - 设置时区(增强型,支持浮点) - 如果设置的时区大于UTC+12且小于等于UTC+14,此时向模组中设入此时区对应的标准UTC时区(如UTC+13 -> UTC-11),并将isExtendTz置为True - 如果在标准时区之内,则直接使用模组底层时区 - args: - tz:float,时区,范围-12.0~14.0 - - Returns: - int:0设置成功,否则失败 - ''' - @classmethod - def setTimeZoneEx(cls, tz): - if 12.0 < tz <= 14.0 : - cls.isExtendTz = True - return utime.setTimeZoneEx(tz - 24.0) - else : - cls.isExtendTz = False - return utime.setTimeZoneEx(tz) - - '''getTimeZoneEx - 获取时区(增强型,支持浮点) - 如果isExtendTz = True,从模组对应的时区应加24小时 - Returns: - float:时区 - ''' - @classmethod - def getTimeZoneEx(cls): - if cls.isExtendTz : - return utime.getTimeZoneEx() + 24.0 - else : - return utime.getTimeZoneEx() - - '''setTimeZone - 设置时区 - 如果设置的时区大于UTC+12且小于等于UTC+14,此时向模组中设入此时区对应的标准UTC时区(如UTC+13 -> UTC-11),并将isExtendTz置为True - 如果在标准时区之内,则直接使用模组底层时区 - args: - tz:int,时区 - - Returns: - int:0设置成功,否则失败 - ''' - @classmethod - def setTimeZone(cls, tz): - if 12 < tz <= 14 : - cls.isExtendTz = True - return utime.setTimeZone(int(tz - 24)) - else : - cls.isExtendTz = False - return utime.setTimeZone(int(tz)) - - '''getTimeZone - 获取时区 - 如果isExtendTz = True,从模组对应的时区应加24小时 - Returns: - int:时区 - ''' - @classmethod - def getTimeZone(cls): - if cls.isExtendTz : - return int(utime.getTimeZoneEx() + 24) - else : - return int(utime.getTimeZoneEx()) - - '''setlocaltime - 设定时间(带时区偏移)&元组转换,解决RTC和localtime存在时区偏移,以及数据格式不同的问题 - 所设即所得,自动计算localtime对RTC时间的偏移量,无论在任何条件下,utimeextend.localtime()获取的时间均应符合此接口设置 - args: - tm_tuple:tuple(year, month, day, hour, minute, second, weekday, yearday):设置时间 - - Returns: - int:0设置成功,否则失败 - ''' - @classmethod - def setlocaltime(cls, tm_tuple): - temp_rtc = RTC() - #RTC_datatime_list:[year, month, day, week, hour, minute, second, microsecond] - try: - temp_rtc.datetime([tm_tuple[0], tm_tuple[1], tm_tuple[2], tm_tuple[6], tm_tuple[3], tm_tuple[4], tm_tuple[5], 0]) - except: - raise(TypeError,"Error time argument") - - tm_rtc_in = utime.mktime(tm_tuple) - offset = tm_rtc_in - utime.mktime(utime.localtime())#此处通过一次尝试设置,计算当前时区配置下RTC时间和localtime的差值 - - print(str(offset) + "s for offset\r\n") - - tm_set_tuple = () - if not cls.isExtendTz: - tm_set_tuple = utime.localtime(tm_rtc_in + offset) - else: - tm_set_tuple = utime.localtime(tm_rtc_in + offset - (24*60*60))#东十二区以上还要添加到对应标准时区的一天偏差 - - return temp_rtc.datetime([tm_set_tuple[0], tm_set_tuple[1], tm_set_tuple[2], tm_set_tuple[6], tm_set_tuple[3], tm_set_tuple[4], tm_set_tuple[5], 0]) - - '''mktime - 由时间转换时间戳 - args: - tm_tuple_in:tuple(year, month, day, hour, minute, second, weekday, yearday):输入时间 - time_zone:int,时区,不填默认输出GMT时间戳 - - Returns: - int:0设置成功,否则失败 - ''' - @classmethod - def mktime(cls, tm_tuple_in, time_zone = 0): - - return utime.mktime(tm_tuple_in) + (8*60*60) - (time_zone*60*60)#UTC timestamp with timezone - - - - - +''' +背景:标准的UTC时区应为-12到+12,但某些国境横跨国际日期变更线的国家为保持全国日期统一,将 +原属UTC-11的领土日期前推一天,即从UTC-11加24H,是为UTC+13 +''' +import utime +from machine import RTC + +class utimeextend(object): + #如果设置的时区大于UTC+12,此flag被置为True + isExtendTz = False + + """_extend_tz_handle + 内部函数,在使用扩展时区(isExtendTz = False = True)时处理时间,将时间前推24h,例如从UTC-11把时间映射到UTC+13 + + Returns: + tuple: (year, month, day, hour, minute, second, weekday, yearday) + """ + @classmethod + def _extend_tz_handle(cls): + tm_temp_in = utime.mktime(utime.localtime()) + tm_tuple_out = utime.localtime(tm_temp_in + (24*60*60)) + + return tm_tuple_out + + """localtime + 扩展原生utime的方法,不带参数时,如果isExtendTz = True,此时输出的时间应为模组的RTC时间加偏24H. + 带参数时由传入的时间戳解算出时间 + args: + args[0]:int,时间戳,单位s + args[1]:int,时区,范围-12~14,可使时间戳解算的时间加时区偏移,不填此参数则默认输出GMT时间 + + Returns: + tuple(year, month, day, hour, minute, second, weekday, yearday):返回时间 + """ + @classmethod + def localtime(cls, *args): + tm_tuple = () + if not args: + tm_tuple = cls._extend_tz_handle() if cls.isExtendTz else utime.localtime() + + elif len(args) == 1: + tm_tuple = utime.localtime(args[0] - (8*60*60)) + + elif len(args) == 2: + tm_tuple = utime.localtime(args[0] - (8*60*60) + (args[1]*60*60)) + + else: + raise(ValueError, "Arguments Error") + + return tm_tuple + + '''setTimeZoneEx + 设置时区(增强型,支持浮点) + 如果设置的时区大于UTC+12且小于等于UTC+14,此时向模组中设入此时区对应的标准UTC时区(如UTC+13 -> UTC-11),并将isExtendTz置为True + 如果在标准时区之内,则直接使用模组底层时区 + args: + tz:float,时区,范围-12.0~14.0 + + Returns: + int:0设置成功,否则失败 + ''' + @classmethod + def setTimeZoneEx(cls, tz): + if 12.0 < tz <= 14.0 : + cls.isExtendTz = True + return utime.setTimeZoneEx(tz - 24.0) + else : + cls.isExtendTz = False + return utime.setTimeZoneEx(tz) + + '''getTimeZoneEx + 获取时区(增强型,支持浮点) + 如果isExtendTz = True,从模组对应的时区应加24小时 + Returns: + float:时区 + ''' + @classmethod + def getTimeZoneEx(cls): + if cls.isExtendTz : + return utime.getTimeZoneEx() + 24.0 + else : + return utime.getTimeZoneEx() + + '''setTimeZone + 设置时区 + 如果设置的时区大于UTC+12且小于等于UTC+14,此时向模组中设入此时区对应的标准UTC时区(如UTC+13 -> UTC-11),并将isExtendTz置为True + 如果在标准时区之内,则直接使用模组底层时区 + args: + tz:int,时区 + + Returns: + int:0设置成功,否则失败 + ''' + @classmethod + def setTimeZone(cls, tz): + if 12 < tz <= 14 : + cls.isExtendTz = True + return utime.setTimeZone(int(tz - 24)) + else : + cls.isExtendTz = False + return utime.setTimeZone(int(tz)) + + '''getTimeZone + 获取时区 + 如果isExtendTz = True,从模组对应的时区应加24小时 + Returns: + int:时区 + ''' + @classmethod + def getTimeZone(cls): + if cls.isExtendTz : + return int(utime.getTimeZoneEx() + 24) + else : + return int(utime.getTimeZoneEx()) + + '''setlocaltime + 设定时间(带时区偏移)&元组转换,解决RTC和localtime存在时区偏移,以及数据格式不同的问题 + 所设即所得,自动计算localtime对RTC时间的偏移量,无论在任何条件下,utimeextend.localtime()获取的时间均应符合此接口设置 + args: + tm_tuple:tuple(year, month, day, hour, minute, second, weekday, yearday):设置时间 + + Returns: + int:0设置成功,否则失败 + ''' + @classmethod + def setlocaltime(cls, tm_tuple): + temp_rtc = RTC() + #RTC_datatime_list:[year, month, day, week, hour, minute, second, microsecond] + try: + temp_rtc.datetime([tm_tuple[0], tm_tuple[1], tm_tuple[2], tm_tuple[6], tm_tuple[3], tm_tuple[4], tm_tuple[5], 0]) + except: + raise(TypeError,"Error time argument") + + tm_rtc_in = utime.mktime(tm_tuple) + offset = tm_rtc_in - utime.mktime(utime.localtime())#此处通过一次尝试设置,计算当前时区配置下RTC时间和localtime的差值 + + print(str(offset) + "s for offset\r\n") + + tm_set_tuple = () + if not cls.isExtendTz: + tm_set_tuple = utime.localtime(tm_rtc_in + offset) + else: + tm_set_tuple = utime.localtime(tm_rtc_in + offset - (24*60*60))#东十二区以上还要添加到对应标准时区的一天偏差 + + return temp_rtc.datetime([tm_set_tuple[0], tm_set_tuple[1], tm_set_tuple[2], tm_set_tuple[6], tm_set_tuple[3], tm_set_tuple[4], tm_set_tuple[5], 0]) + + '''mktime + 由时间转换时间戳 + args: + tm_tuple_in:tuple(year, month, day, hour, minute, second, weekday, yearday):输入时间 + time_zone:int,时区,不填默认输出GMT时间戳 + + Returns: + int:0设置成功,否则失败 + ''' + @classmethod + def mktime(cls, tm_tuple_in, time_zone = 0): + + return utime.mktime(tm_tuple_in) + (8*60*60) - (time_zone*60*60)#UTC timestamp with timezone + + + + + diff --git a/docs/en/API_Reference.md b/docs/en/API_Reference.md new file mode 100644 index 0000000..b246a32 --- /dev/null +++ b/docs/en/API_Reference.md @@ -0,0 +1,95 @@ +# QuecPython Enhanced Time & TimeZone API Reference Manual + +QuecPython Enhanced time and time zone is based on utime and RTC, the functionality is more comprehensive, users can call the utimeextend class, directly use the class method for time and time zone operations. + +## Get local time + +### `utimeextend.localtime` + +```python +utimeextend.localtime(timestamp=None, tz=None) +``` + +**Parameters** + +- `timestamp` - int,Optional: Enter the timestamp. Otherwise, the current RTC time is directly displayed +- `tz` - int/float,Optional: Time zone, the value ranges from -12 to 14. The time calculated by the timestamp is plus the time zone offset. If this parameter is not specified, the GMT time is displayed by default + +**Return Value** + +Returns a tuple of the format (year, month, day, hour, minute, second, weekday, yearday). + +## Set loacl time + +### `utimeextend.setlocaltime` + +```python +utimeextend.setlocaltime(tm_tuple) +``` + +**Parameters** + +- `tm_tuple` - tuple(year, month, day, hour, minute, second, weekday, yearday):设置时间 + +**Return Value** + +int:0 for success, else for failure + +## Set Time Zone + +### `utimeextend.setTimeZone` + +```python +utimeextend.setTimeZone(tz) +``` +**Parameters** + +- `tz` - int,time zone,range -12~14。 + +**Return Value** + +int:0 for success, else for failure + +## Get Time Zone + +### `utimeextend.getTimeZone` + +```python +utimeextend.getTimeZone() +``` + +**Return Value** + +int: Time Zone + +## Set Time Zone(Enhanced, support float) + +### `utimeextend.setTimeZoneEx` + +```python +utimeextend.setTimeZoneEx(tz) +``` + +**Parameters** + +- `tz` - float,time zone,range -12.0~14.0。 + +**Return Value** + +int:0 for success, else for failure + +> - To use the enhanced time zone interface Settings, you must use the enhanced time zone interface to obtain, otherwise it will cause precision loss + +## Get Time Zone(Enhanced, support float) + +### `utimeextend.getTimeZoneEx` + +```python +utimeextend.getTimeZoneEx() +``` + +**Return Value** + +float: Time Zone + +> - To use the enhanced time zone interface Settings, you must use the enhanced time zone interface to obtain, otherwise it will cause precision loss \ No newline at end of file diff --git "a/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" "b/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" new file mode 100644 index 0000000..aa06784 --- /dev/null +++ "b/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" @@ -0,0 +1,100 @@ +# QuecPython 增强型时间和时区 API 参考手册 + +QuecPython 增强型时间和时区是基于utime和RTC,实现的功能更为全面,用户可以在调用utimeextend类,直接使用类方法进行时间和时区操作。 + + +## 获取本地时间 + +### `utimeextend.localtime` + +```python +utimeextend.localtime(timestamp=None, tz=None) +``` + +**参数** + +- `timestamp` - int,可选,输入时间戳,否则直接输出当前RTC时间 +- `tz` - int/float,可选,时区,范围-12~14,可使时间戳解算的时间加时区偏移,不填此参数则默认输出GMT时间 + +**返回值** + +返回元组,格式为(year, month, day, hour, minute, second, weekday, yearday) + + +## 设置本地时间 + +### `utimeextend.setlocaltime` + +```python +utimeextend.setlocaltime(tm_tuple) +``` + +**参数** + +- `tm_tuple` - tuple(year, month, day, hour, minute, second, weekday, yearday):设置时间 + +**返回值** + +int:0设置成功,否则失败 + + +## 设置时区 + +### `utimeextend.setTimeZone` + +```python +utimeextend.setTimeZone(tz) +``` + +**参数** + +- `tz` - int,时区,范围-12~14。 + +**返回值** + +int:0设置成功,否则失败 + + +## 获取时区 + +### `utimeextend.getTimeZone` + +```python +utimeextend.getTimeZone() +``` + +**返回值** + +int:时区 + + +## 设置时区(增强型,支持浮点) + +### `utimeextend.setTimeZoneEx` + +```python +utimeextend.setTimeZoneEx(tz) +``` +**参数** + +- `tz` - float,时区,范围-12.0~14.0 + +**返回值** + +int:0设置成功,否则失败 + +> - 使用增强型时区接口设置,就要用增强型时区接口获取,否则会造成精度丢失 + +## 获取时区(增强型,支持浮点) + +### `utimeextend.getTimeZoneEx` + +```python +utimeextend.getTimeZoneEx() +``` +**返回值** + +float:时区 + +> - 使用增强型时区接口设置,就要用增强型时区接口获取,否则会造成精度丢失 +