ZWO Minilang

ZWO minilang 的 Python 工具包。

安装

使用您喜欢的 pip 调用从 PyPi 安装

$ pip install zwolang

您可以通过 zwom CLI 确认正确安装

$ zwom --help
                                                                               
 Usage: zwom [OPTIONS] COMMAND [ARGS]...                                       
                                                                               
+- Options -------------------------------------------------------------------+
| --help          Show this message and exit.                                 |
+-----------------------------------------------------------------------------+
+- Commands ------------------------------------------------------------------+
| batch    Discover and convert all `*.zwom` files in the given directory.    |
| single   Convert the specified `*.zwom` file to Zwift's `*.zwo`.            |
+-----------------------------------------------------------------------------+

ZWOM 文件规范

此包的主要目的是提供一个简单、可读的格式来构建 Zwift 训练计划，该格式可用于生成实际的训练计划 XML。让我们称之为 *.zwom 文件，或 ZWOM。

ZWOM 文件使用以下指定的 Parsimonious 语法进行解析

workout   = ((comment / block) elws*)+ / elws
block     = tag ws "{" ((comment / params) / elws)+ "}"
params    = (message / value) ","?
value     = tag ws (string / range / rangeval)

message   = "@" ws duration ws string
range     = rangeval ws "->" ws rangeval
rangeval  = duration / numeric / zone
duration  = number ":" number
percent   = number "%"
zone      = ("Z" number) / "SS"
numeric   = percent / number
elws      = ws / emptyline

comment   = ~r"\;[^\r\n]*"
tag       = ~"[A-Z_]+"
string    = ~'"[^\"]+"'
number    = ~"\d+"
ws        = ~"\s*"
emptyline = ws+

语法 & 关键字

类似于 Zwift 内置的训练计划构建器，ZWO minilang 是一种基于块的系统。块使用 <tag> {<block contents>} 格式指定，支持任意空白。

也支持内联注释，由一个开头的 ; 表示。

训练计划元数据

每个 ZWO 文件必须以一个包含逗号分隔参数的 META 块开始

1. 支持多行字符串
2. Zwift 的训练计划使用 FTP 百分比而不是绝对瓦数，因此如果您想在 ZWOM 中使用绝对瓦数，则需要您的 FTP。
3. 标签的总字符数限制为31个，包括空格和井号。 Zwift 还提供了4个内置标签（#RECOVERY、#INTERVALS、#FTP 和 #TT），也可以添加，但不会计入总数。

锻炼块

在 META 块之后是您的锻炼块

注意：虽然在工作界面中没有特定的爬坡块，但已经进行了一些实验观察

• 如果爬坡在锻炼的非常开始处，Zwift 会将其序列化为热身块
• 如果锻炼中有多个块，并且爬坡在最后，Zwift 会将其序列化为冷却块
• 如果锻炼中有多个块，并且爬坡既不在开始也不在结尾，Zwift 会将其序列化为爬坡块

在编写您的 *.zwom 文件时，这3个块可以互换使用，并且 ZWOM 将在输出其 *.zwo 文件时尝试匹配此行为。如果对锻炼UI进行了编辑，Zwift 可能会进行自己的规范化。

锻炼块元数据

锻炼块可以包含以下（可选）逗号分隔的参数

1. 对于间歇和爬坡段，可以使用范围语法为 <left> -> <right> 段设置值（例如 65% -> 120% 或 Z2 -> Z6）
2. 踏频范围仅适用于间歇段
3. 区域可以是 Z1-7 或 SS
4. 对于自由段，功率被忽略
5. 消息时间戳相对于其包含的块是相对的

重复块块块

提供 START_REPEAT 和 END_REPEAT 元块来指定要重复的任意块块。 START_REPEAT 块必须指定一个 REPEAT 参数； END_REPEAT 不接受任何参数。目前不支持嵌套重复。

例如

SEGMENT {DURATION 2:00, POWER 65%}
RAMP {
    DURATION 2:00,
    POWER 120% -> 140%,
    @ 0:00 "Here goes the ramp!",
    @ 1:50 "10 seconds left!",
}
SEGMENT {DURATION 2:00, POWER 65%}
RAMP {
    DURATION 2:00,
    POWER 120% -> 140%,
    @ 0:00 "Here goes the ramp!",
    @ 1:50 "10 seconds left!",
}

变成

START_REPEAT {REPEAT 2}
SEGMENT {DURATION 2:00, POWER 65%}
RAMP {
    DURATION 2:00,
    POWER 120% -> 140%,
    @ 0:00 "Here goes the ramp!",
    @ 1:50 "10 seconds left!",
}
END_REPEAT {}

示例锻炼

; Here is a workout-level comment!
META {
    NAME "Sample Workout",
    AUTHOR "sco1",
    DESCRIPTION "Here's a description!

    Descriptions may be on more than one line too!",
    TAGS "#RECOVERY #super #sweet #workout",
    FTP 270,
}
FREE {DURATION 10:00}
INTERVALS {
    ; Here is a block-level comment!
    REPEAT 3,
    DURATION 1:00 -> 0:30,
    POWER 55% -> 78%,
    CADENCE 85 -> 110,
}
SEGMENT {DURATION 2:00, POWER 65%}
RAMP {
    DURATION 2:00,
    POWER 120% -> 140%,
    @ 0:00 "Here goes the ramp!",
    @ 1:50 "10 seconds left!",
}
FREE {DURATION 10:00}