linkcad.env

供脚本和插件使用的选项与日志工具。

from linkcad.v1.env import (
    get_option_boolean, set_option_boolean,
    get_option_int,     set_option_int,
    get_option_real,    set_option_real,
    get_option_string,  set_option_string,
    get_option_path,    set_option_path,
    test_option, record_option,
    register_option_int, register_option_boolean,
    register_option_real, register_option_string,
    init_options, save_options,
    program_version, program_version_number,
    EventLog, IEventLog, IEventLogReader, Severity,
)

选项

LinkCAD 以字符串键（例如 "GdsiiInFlattenAll"）保存持久的格式选项和工具选项。以下函数让脚本无需打开选项对话框即可读取和覆盖这些值。

Python 插件通过 Option.* 声明的选项使用按插件限定的生成键：PyPlugin.<类>.<属性>，因此 AsciiWriter 的 flatten 属性会保存为 PyPlugin.AsciiWriter.flatten。保留根 PyPlugin 把插件选项挡在应用程序自身的命名空间之外，类名段则把两个都叫 flatten 的插件选项区分开。这些键同样用下列函数读写。

读取与写入

函数	说明
`get_option_boolean(name, default=False, *, record=False)`	读取布尔选项
`set_option_boolean(name, value)`	写入布尔选项
`get_option_int(name, default=0, *, record=False)`	读取整数选项
`set_option_int(name, value)`	写入整数选项
`get_option_real(name, default=0.0, *, record=False)`	读取浮点选项
`set_option_real(name, value)`	写入浮点选项
`get_option_string(name, default="", *, record=False)`	读取字符串选项
`set_option_string(name, value)`	写入字符串选项
`get_option_path(name, default="", *, record=False)`	以字符串形式读取路径选项
`set_option_path(name, value)`	从字符串写入路径选项
`test_option(name)`	该选项是否已注册且可读
`record_option(name)`	记录该选项被访问过

选项未注册时，每个读取函数都会返回 default，因此未知的键返回的是你传入的值，而不是该类型的零值：

from linkcad.v1.env import get_option_int

iterations = get_option_int("MyToolIterations", 10)   # 10 if never registered

五个读取函数的 record 都是仅限关键字参数。因此第二个位置参数对任何类型都表示“默认值”，bool 也不例外——get_option_boolean(name, True) 的含义就是它字面上的意思。

用 Option.* 声明的插件选项会在调用 run()、read() 或 write() 之前自动注册，因此通过 self.<属性> 读取即可得到当前值。

注册与持久化

插件基类会注册自己的选项，因此大多数脚本用不到这些函数。它们面向自行定义选项键的代码。

函数	说明
`register_option_int(name, default_value, short_name="", persistent=True)`	声明整数选项
`register_option_boolean(name, default_value, short_name="", persistent=True)`	声明布尔选项
`register_option_real(name, default_value, short_name="", persistent=True)`	声明实数选项
`register_option_string(name, default_value, short_name="", persistent=True)`	声明字符串选项
`init_options(enable_persistence=True)`	初始化选项系统
`save_options()`	将选项写入持久存储

版本

函数	说明
`program_version(short_form=False)`	以字符串表示的 LinkCAD 版本
`program_version_number()`	以数字表示的 LinkCAD 版本

from linkcad.v1.env import get_option_boolean, set_option_boolean

# Check whether GDSII import flattens hierarchy
flatten = get_option_boolean("GdsiiInFlattenAll", False)
print(f"GDSII flatten: {flatten}")

# Temporarily override
set_option_boolean("GdsiiInFlattenAll", True)

日志

EventLog

应用程序事件日志。写入此处的消息会出现在 LinkCAD 的日志面板中。

from linkcad.v1.env import EventLog, Severity

log = EventLog()
log.log(Severity.Info, "Processing complete")
log.log(Severity.Warning, "Layer 'TEMP' will be deleted")
log.log(Severity.Error, "Could not open file")

if log.highest_severity == Severity.Error:
    log.mark_fatal()
print(log.entry_count, log.fatal)

同一个层次结构中的三个接口：IEventLog 是写入端，IEventLogReader 在其上增加读取能力，EventLog 则是你可以自行构造的具体日志。Conversion.export_log 和 ConversionController.export_log 返回 IEventLog；import_log 返回 IEventLogReader。

属性 / 方法	定义于	说明
`EventLog()`	`EventLog`	创建事件日志
`log.log(severity, message)`	`IEventLog`	以给定严重级别写入消息
`log.log_with_title(severity, title, description)`	`IEventLog`	写入带标题的消息
`log.log_success(message)`	`IEventLog`	成功消息的便捷方法
`log.log_info(message)`	`IEventLog`	信息消息的便捷方法
`log.log_warning(message)`	`IEventLog`	警告消息的便捷方法
`log.log_error(message)`	`IEventLog`	错误消息的便捷方法
`log.fatal`	`IEventLog`	日志一旦被标记为致命即为 `True`
`log.mark_fatal()`	`IEventLog`	把日志标记为致命。此操作无法撤销
`log.entry_count`	`IEventLogReader`	日志中的条目数
`log.highest_severity`	`IEventLogReader`	日志中出现的最高严重级别
`log.log_at_line(severity, message, line)`	`EventLog`	写入带行号的消息
`log.log_at_name(severity, message, name)`	`EventLog`	写入带命名位置的消息
`log.clear_log()`	`EventLog`	移除所有条目

mark_fatal() 保持为动词而不是 fatal = True，因为它是单向的转变：没有回头路。

Severity

日志消息的严重级别。

值	说明
`Severity.Success`	成功消息
`Severity.Info`	信息消息
`Severity.Informational`	信息消息；等同于 `Severity.Info`
`Severity.Warning`	非致命警告
`Severity.Error`	可恢复的错误