Mycroft 时间工具指南:掌握 mycroft.util.time 时区获取与 datetime 转换

原创2026-10-14 18:44:541,354 阅读
文章标签:人工智能语音交互助手智能硬件

Mycroft 时间工具指南:掌握 mycroft.util.time 时区获取与 datetime 转换

mycroft.util.time 是 Mycroft Core 中专门负责"获取当前时间、在用户时区与 UTC 之间转换 datetime"的官方工具模块,其时间基准取自 Mycroft 配置中的 location.timezone,而非操作系统 locale,从而保证同一台设备上语音助手与技能看到的时间始终一致。阅读本文后,你将掌握 default_timezone、now_utc、now_local、to_utc、to_local、to_system 六个函数的完整语义与调用方式,理解它们背后的配置层级与 dateutil 实现原理,并能据此写出时区安全、可本地化的技能时间处理代码。

模块定位:Mycroft 时间体系的总入口

在 Mycroft Core 中,时间处理被刻意设计为"以用户配置为中心"。模块 docstring 明确说明:

Time utils for getting and converting datetime objects for the Mycroft system. This time is based on the setting in the Mycroft config and may or may not match the system locale.

也就是说,mycroft.util.time 返回的"本地时间"指的是用户配置的时区所对应的时间,可能与操作系统时区不一致(例如设备在服务器机房、用户在美国中部时区)。这一设计与系统级工具(如 date 命令)形成对比,是技能开发中避免"时区错乱"的关键。

模块源码位于 mycroft/util/time.py,对外暴露 6 个函数;官方文档入口 doc/source/mycroft.util.time.rst 通过 automodule 指令自动生成这些函数的 API 文档,是技能开发者查阅该模块的正式入口。

六个核心函数:API 语义与完整参数说明

default_timezone() —— 获取默认时区

获取 Mycroft 默认时区。优先读取用户配置 location.timezone.code(例如 "America/Chicago"),配置缺失或读取异常时回退到系统本地时区。

  • 返回:datetime.tzinfo,即默认时区定义
  • 依赖:mycroft.configuration.Configuration.get() 与 dateutil.tz.gettz
from mycroft.util.time import default_timezone

tz = default_timezone()
print(tz)  # tzfile('/usr/share/zoneinfo/America/Chicago') 或系统本地时区

实现要点(time.py):

def default_timezone():
    try:
        from mycroft.configuration import Configuration
        config = Configuration.get()
        code = config["location"]["timezone"]["code"]
        return gettz(code)
    except Exception:
        # Just go with system default timezone
        return tzlocal()

配置中 location.timezone 实际包含四个字段(见 mycroft.conf),其中只有 code 被本函数使用:

字段 类型 示例 含义
code str "America/Chicago" IANA 时区标识,由 gettz 解析
name str "Central Standard Time" 人类可读时区名
offset int(ms) -21600000 相对 UTC 的偏移量(毫秒)
dstOffset int(ms) 3600000 夏令时偏移量(毫秒)

值得注意的是,default_timezone 的整个配置读取被包在 try/except 中,任何异常(配置缺失、code 不存在、gettz 失败)都会静默回退到 tzlocal(),因此该函数理论上不会抛异常,适合无条件调用。

now_utc() —— 获取当前 UTC 时间

返回当前时刻的 UTC datetime,等价于 "Universal Time / GMT"。

from mycroft.util.time import now_utc

print(now_utc())  # 例如 2026-10-14 01:20:14+00:00

实现上它先取 datetime.utcnow()(naive datetime),再通过 to_utc() 补上 UTC 时区信息(time.py),因此返回对象始终带 +00:00 时区信息,可以直接参与跨时区运算。

now_local(tz=None) —— 获取当前本地时间

返回当前时间。tz 为可选的 datetime.tzinfo,省略时默认使用用户配置时区(即 default_timezone() 的返回值)。

from mycroft.util.time import now_local

print(now_local())                         # 用户配置时区的当前时间
print(now_local(tz=None))                  # 等价写法

参数说明:

  • tz (datetime.tzinfo, optional):指定时区;默认 None 表示使用用户配置时区
  • 返回:datetime,当前时间(带时区信息)

实现为 datetime.now(tz),传入的 tz 会被 datetime.now 用于获取"该时区视角"的当前时刻(time.py)。

to_utc(dt) —— 任意 datetime 转 UTC

将一个(通常带时区信息的)datetime 转换为 UTC datetime。

  • 入参:dt (datetime),假定处于某个本地时区
  • 返回:转换为 UTC 的 datetime
from datetime import datetime
from dateutil.tz import gettz
from mycroft.util.time import to_utc

dt = datetime(2000, 1, 1, tzinfo=gettz('Europe/Stockholm'))
print(to_utc(dt))   # 1999-12-31 23:00:00+00:00

实现细节(time.py)值得注意——它同时兼容 naive 与 aware 两种 datetime:

def to_utc(dt):
    tzUTC = gettz("UTC")
    if dt.tzinfo:
        return dt.astimezone(tzUTC)
    else:
        return dt.replace(tzinfo=gettz("UTC")).astimezone(tzUTC)
  • 若 dt 已带时区(dt.tzinfo 非空):直接 astimezone(UTC) 转换;
  • 若 dt 是 naive datetime:先假定其为 UTC(replace(tzinfo=UTC))再转换,即"无时区信息即视为 UTC",这与 Python 官方 utcfromtimestamp 的语义保持一致。

to_local(dt) —— 转换到用户本地时区

将 datetime 转换到用户配置的本地时区。若入参未带时区,默认按 UTC 解释。

  • 入参:dt (datetime),无时区信息时假定为 UTC
  • 返回:转换到用户时区的 datetime
from mycroft.util.time import to_local

print(to_local(now_utc()))   # 转回用户时区

实现上,tz = default_timezone(),带时区则 astimezone(tz),否则先 replace(tzinfo=UTC) 再转换(time.py)。注意:"本地"的定义取决于配置,而非操作系统,这与 to_system 形成鲜明对比。

to_system(dt) —— 转换到操作系统时区

将 datetime 转换到操作系统(而非用户配置)的时区。无时区信息时假定为 UTC。

  • 入参:dt (datetime),无时区信息时假定为 UTC
  • 返回:转换到操作系统时区的 datetime
from mycroft.util.time import to_system

print(to_system(now_utc()))   # 系统 /etc/localtime 视角的时间

实现使用 tzlocal() 获取操作系统时区(time.py)。当用户配置时区与系统时区不同(如远程设备、云服务器)时,to_system 与 to_local 的结果会明显不同——这是两个函数并存的原因。

配置驱动:location.timezone 从何而来

mycroft.util.time 的时区来源是 Configuration.get()<a href="https://link.gitcode.com/i/c6c1f8aed3fe187a2f07e8d1d4eb34bb" target="_blank">"location"]["timezone"]["code"]。在默认配置 [mycroft/configuration/mycroft.conf 中,时区随 location 一起定义:

"location": {
  "city": {
    "code": "Lawrence",
    "name": "Lawrence",
    "state": {
      "code": "KS",
      "name": "Kansas",
      "country": {
        "code": "US",
        "name": "United States"
      }
    }
  },
  "coordinate": {
    "latitude": 38.971669,
    "longitude": -95.23525
  },
  "timezone": {
    "code": "America/Chicago",
    "name": "Central Standard Time",
    "dstOffset": 3600000,
    "offset": -21600000
  }
}

配置文件头部注释说明了设置加载顺序(mycroft.conf):

  1. DEFAULT:mycroft.conf 中的默认值;
  2. REMOTE:用户在 home.mycroft.ai 网页端设置,经 API 下发;
  3. SYSTEM:通常位于 /etc/mycroft/mycroft.conf;
  4. USER:通常位于 ~/.config/mycroft/mycroft.conf,优先级最高。

远程配置下发时,Configuration 还会通过 api.get_location() 拉取服务器端位置信息并写入 location(见 config.py),这也解释了为何 location 注释中标有 Override: REMOTE。对用户而言,最直接的时区修改方式是在 USER 级配置中写入:

{
  "location": {
    "timezone": {
      "code": "Asia/Shanghai"
    }
  }
}

只要 code 是合法的 IANA 时区标识(dateutil.tz.gettz 支持的值),default_timezone() 就会立即生效。

源码纵深:naive 与 aware datetime 的统一处理

mycroft.util.time 在工程上最值得借鉴的一点,是对 naive datetime 的默认语义约定:所有转换函数在遇到不带时区信息的 datetime 时,一律先 replace(tzinfo=gettz("UTC")),再执行 astimezone。这使得调用方无需自己记忆"这个对象到底属于哪个时区"——模块约定"无时区 = UTC",彻底避免了 datetime.utcnow() 与 datetime.now() 混用导致的时区漂移问题。

此外,三个转换函数(to_utc / to_local / to_system)共享同一套模式:

tzinfo 非空  ->  astimezone(目标时区)
tzinfo 为空  ->  replace(tzinfo=UTC) 后 astimezone(目标时区)

区别仅在于"目标时区"的取值:UTC、用户配置时区、系统本地时区。掌握了这一模式,你就能推导出任意组合的转换结果。

测试佐证:test_time.py 覆盖的行为约定

单元测试 test/unittests/util/test_time.py 完整验证了上述六个函数,可作为行为契约参考:

  • test_default_timezone:配置 code: "America/Chicago" 时返回 tzfile('/usr/share/zoneinfo/America/Chicago');配置缺失({})时回退到 tzlocal();
  • test_now_local:无参时以用户时区调用 datetime.now(tz);显式传 tz 时使用指定时区;
  • test_now_utc:调用 datetime.utcnow() 并补上 UTC 时区;
  • test_to_utc:将 Europe/Stockholm 的 datetime 转为 UTC(tzinfo == UTC);
  • test_to_local:将 Europe/Stockholm 的 datetime 转为 America/Chicago;
  • test_to_system:将任意时区 datetime 转为 tzlocal()。

测试中使用的配置样例(test_time.py)同样展示了 location.timezone 的完整字段结构,可作为你编写技能测试时的 mock 参考。

实战应用:技能与解析器如何使用时间工具

extract_datetime 的锚点时间

mycroft.util.time 在核心代码中最典型的消费方是自然语言时间解析器。在 mycroft/util/parse.py 中,extract_datetime 解析用户话语(如 "what is weather like"、"Set up an appointment 2 weeks from Sunday at 5 pm")时,以 now_local() 作为锚点日期:

if anchorDate is None or anchorDate == "DEFAULT":
    anchorDate = now_local()
return _extract_datetime(text, anchorDate, lang or get_default_loc(), default_time)

也就是说,技能中调用 extract_datetime 得到的"相对时间"(如"两周后的周日")天然基于用户配置时区计算,而非服务器/系统时区——这正是语音助手正确处理跨时区日程的基础。

配合 mycroft.util.format 输出人性化时间

获取到正确的 datetime 后,显示与语音输出通常交给 mycroft/util/format.py 完成,它基于 lingua-franca 提供 nice_time、nice_date、nice_date_time、nice_duration 等本地化格式化函数。典型组合:

from mycroft.util.time import now_local
from mycroft.util.format import nice_time, nice_date_time

dt = now_local()                     # 用户时区的当前时间
print(nice_time(dt))                 # 例如 "8:18 AM"(取决于 time_format 配置)
print(nice_date_time(dt))            # 例如 "Friday, October 14, 2026, 8:18 AM"

配套的 time_format("half" 如 "11:37 pm" / "full" 如 "23:37")与 date_format("MDY" / "DMY")配置定义于 mycroft.conf,与时间工具的时区逻辑共同构成 Mycroft 完整的时间本地化链路:mycroft.util.time 负责"时刻正确",mycroft.util.format 负责"表达友好"。

使用建议与注意事项

  1. 优先使用 now_local() 而非 datetime.now():前者尊重用户配置,后者受系统 locale 影响,在云设备/远程部署场景下两者可能相差数小时;
  2. 持久化与日志场景使用 UTC:需要跨设备比较或落库的时间建议用 now_utc(),展示时再 to_local() 转换,避免夏令时切换造成歧义;
  3. 明白 naive 输入的约定:向 to_utc / to_local / to_system 传入 naive datetime 时,一律按 UTC 解释,不要依赖系统本地时间;
  4. 时区值必须是 IANA 标识:location.timezone.code 应填写 gettz() 可解析的时区名(如 "America/Chicago"、"Asia/Shanghai"),offset/dstOffset 字段仅作参考,不影响实际换算;
  5. 本模块不负责格式化:时间字符串的本地化输出请交由 mycroft/util/format.py 处理,二者职责分离、配合使用。

综上,mycroft.util.time 以"用户配置时区"为唯一时间基准,通过 6 个精心设计的函数统一了 Mycroft 全系统(解析器、技能、后台服务)的时间语义;配合单元测试与配置文件的佐证,它是任何 Mycroft 技能开发者处理时间问题时最应优先选用的工具模块。

登录后查看全文
mycroft-core