linkcad.env

Options and logging utilities for scripts and plugins.

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,
)

Options

LinkCAD stores persistent format and tool options under string keys (e.g. "GdsiiInFlattenAll"). The functions below let scripts read and override these values without opening the Options dialog.

Options declared by a Python plugin through Option.* use a generated key scoped to the plugin: PyPlugin.<Class>.<attribute>, so the flatten attribute of AsciiWriter persists as PyPlugin.AsciiWriter.flatten. The reserved PyPlugin root keeps plugin options out of the application’s own namespace, and the class segment keeps two plugins that both call an option flatten apart. Read and write those with the same functions.

Reading and writing

Function	Description
`get_option_boolean(name, default=False, *, record=False)`	Read a boolean option
`set_option_boolean(name, value)`	Write a boolean option
`get_option_int(name, default=0, *, record=False)`	Read an integer option
`set_option_int(name, value)`	Write an integer option
`get_option_real(name, default=0.0, *, record=False)`	Read a float option
`set_option_real(name, value)`	Write a float option
`get_option_string(name, default="", *, record=False)`	Read a string option
`set_option_string(name, value)`	Write a string option
`get_option_path(name, default="", *, record=False)`	Read a filesystem-path option, as a string
`set_option_path(name, value)`	Write a filesystem-path option from a string
`test_option(name)`	Whether the option is registered and readable
`record_option(name)`	Record that the option was accessed

Every getter returns default when the option is not registered, so an unknown key gives back what you passed rather than the type’s zero value:

from linkcad.v1.env import get_option_int

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

record is keyword-only on all five getters. The second positional argument therefore means “default” for every type, including bool — get_option_boolean(name, True) means what it reads as.

Plugin options declared with Option.* are registered for you before run(), read(), or write() is called, so reading them through self.<attribute> gives the current value.

Registering and persisting

Plugin base classes register their own options, so most scripts never need these. They are here for code that defines option keys of its own.

Function	Description
`register_option_int(name, default_value, short_name="", persistent=True)`	Declare an integer option
`register_option_boolean(name, default_value, short_name="", persistent=True)`	Declare a boolean option
`register_option_real(name, default_value, short_name="", persistent=True)`	Declare a real option
`register_option_string(name, default_value, short_name="", persistent=True)`	Declare a string option
`init_options(enable_persistence=True)`	Initialise the options system
`save_options()`	Flush options to persistent storage

Version

Function	Description
`program_version(short_form=False)`	LinkCAD version as a string
`program_version_number()`	LinkCAD version as a number

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)

Logging

EventLog

The application event log. Messages written here appear in the LinkCAD log panel.

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)

Three interfaces, in one hierarchy: IEventLog is the write side, IEventLogReader adds read access, and EventLog is the concrete log you can construct. Conversion.export_log and ConversionController.export_log hand back an IEventLog; import_log hands back an IEventLogReader.

Property / Method	Defined by	Description
`EventLog()`	`EventLog`	Create an event log
`log.log(severity, message)`	`IEventLog`	Write a message with the given severity
`log.log_with_title(severity, title, description)`	`IEventLog`	Write a titled message
`log.log_success(message)`	`IEventLog`	Convenience success message
`log.log_info(message)`	`IEventLog`	Convenience informational message
`log.log_warning(message)`	`IEventLog`	Convenience warning message
`log.log_error(message)`	`IEventLog`	Convenience error message
`log.fatal`	`IEventLog`	`True` once the log has been marked fatal
`log.mark_fatal()`	`IEventLog`	Mark the log fatal. This cannot be undone
`log.entry_count`	`IEventLogReader`	Number of entries in the log
`log.highest_severity`	`IEventLogReader`	Highest severity present in the log
`log.log_at_line(severity, message, line)`	`EventLog`	Write a message with a line number
`log.log_at_name(severity, message, name)`	`EventLog`	Write a message with a named location
`log.clear_log()`	`EventLog`	Remove all entries

mark_fatal() stays a verb rather than becoming fatal = True, because it is a one-way transition: there is no way back.

Severity

Log message severity levels.

Value	Description
`Severity.Success`	Success message
`Severity.Info`	Informational message
`Severity.Informational`	Informational message; equal to `Severity.Info`
`Severity.Warning`	Non-fatal warning
`Severity.Error`	Recoverable error