linkcad.env

Optionen und Protokollierung für Skripte und 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,
)

Optionen

LinkCAD speichert dauerhafte Format- und Tool-Optionen unter Zeichenkettenschlüsseln (z. B. "GdsiiInFlattenAll"). Mit den folgenden Funktionen können Skripte diese Werte lesen und überschreiben, ohne den Optionsdialog zu öffnen.

Optionen, die ein Python-Plugin über Option.* deklariert, verwenden einen generierten Schlüssel, der auf das Plugin eingegrenzt ist: PyPlugin.<Klasse>.<Attribut>, das Attribut flatten von AsciiWriter wird also als PyPlugin.AsciiWriter.flatten gespeichert. Die reservierte Wurzel PyPlugin hält Plugin-Optionen aus dem Namensraum der Anwendung heraus, und das Klassensegment hält zwei Plugins auseinander, die beide eine Option flatten nennen. Diese lesen und schreiben Sie mit denselben Funktionen.

Lesen und Schreiben

Funktion	Beschreibung
`get_option_boolean(name, default=False, *, record=False)`	Boolesche Option lesen
`set_option_boolean(name, value)`	Boolesche Option schreiben
`get_option_int(name, default=0, *, record=False)`	Ganzzahlige Option lesen
`set_option_int(name, value)`	Ganzzahlige Option schreiben
`get_option_real(name, default=0.0, *, record=False)`	Fließkomma-Option lesen
`set_option_real(name, value)`	Fließkomma-Option schreiben
`get_option_string(name, default="", *, record=False)`	Zeichenketten-Option lesen
`set_option_string(name, value)`	Zeichenketten-Option schreiben
`get_option_path(name, default="", *, record=False)`	Pfad-Option als Zeichenkette lesen
`set_option_path(name, value)`	Pfad-Option aus einer Zeichenkette schreiben
`test_option(name)`	Ob die Option registriert und lesbar ist
`record_option(name)`	Festhalten, dass auf die Option zugegriffen wurde

Jeder Getter liefert default, wenn die Option nicht registriert ist; ein unbekannter Schlüssel gibt also den übergebenen Wert zurück und nicht den Nullwert des Typs:

from linkcad.v1.env import get_option_int

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

record ist bei allen fünf Gettern nur als Schlüsselwort zulässig. Das zweite positionelle Argument bedeutet daher für jeden Typ „Standardwert“, auch für bool — get_option_boolean(name, True) bedeutet, was es liest.

Mit Option.* deklarierte Plugin-Optionen werden vor dem Aufruf von run(), read() oder write() für Sie registriert; sie über self.<attribut> zu lesen liefert also den aktuellen Wert.

Registrieren und Speichern

Plugin-Basisklassen registrieren ihre eigenen Optionen, die meisten Skripte brauchen diese Funktionen also nie. Sie sind für Code gedacht, der eigene Optionsschlüssel definiert.

Funktion	Beschreibung
`register_option_int(name, default_value, short_name="", persistent=True)`	Ganzzahlige Option deklarieren
`register_option_boolean(name, default_value, short_name="", persistent=True)`	Boolesche Option deklarieren
`register_option_real(name, default_value, short_name="", persistent=True)`	Fließkomma-Option deklarieren
`register_option_string(name, default_value, short_name="", persistent=True)`	Zeichenketten-Option deklarieren
`init_options(enable_persistence=True)`	Das Optionssystem initialisieren
`save_options()`	Optionen dauerhaft speichern

Version

Funktion	Beschreibung
`program_version(short_form=False)`	LinkCAD-Version als Zeichenkette
`program_version_number()`	LinkCAD-Version als Zahl

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)

Protokollierung

EventLog

Das Ereignisprotokoll der Anwendung. Hier geschriebene Meldungen erscheinen im Protokollbereich von 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)

Drei Schnittstellen in einer Hierarchie: IEventLog ist die Schreibseite, IEventLogReader ergänzt den Lesezugriff, und EventLog ist das konkrete Protokoll, das Sie erzeugen können. Conversion.export_log und ConversionController.export_log liefern ein IEventLog; import_log liefert ein IEventLogReader.

Eigenschaft / Methode	Definiert von	Beschreibung
`EventLog()`	`EventLog`	Ein Ereignisprotokoll erzeugen
`log.log(severity, message)`	`IEventLog`	Eine Meldung mit der angegebenen Schwere schreiben
`log.log_with_title(severity, title, description)`	`IEventLog`	Eine Meldung mit Titel schreiben
`log.log_success(message)`	`IEventLog`	Kurzform für eine Erfolgsmeldung
`log.log_info(message)`	`IEventLog`	Kurzform für eine Informationsmeldung
`log.log_warning(message)`	`IEventLog`	Kurzform für eine Warnung
`log.log_error(message)`	`IEventLog`	Kurzform für eine Fehlermeldung
`log.fatal`	`IEventLog`	`True`, sobald das Protokoll als fatal markiert wurde
`log.mark_fatal()`	`IEventLog`	Das Protokoll als fatal markieren. Das lässt sich nicht rückgängig machen
`log.entry_count`	`IEventLogReader`	Anzahl der Einträge im Protokoll
`log.highest_severity`	`IEventLogReader`	Höchste im Protokoll vorhandene Schwere
`log.log_at_line(severity, message, line)`	`EventLog`	Eine Meldung mit Zeilennummer schreiben
`log.log_at_name(severity, message, name)`	`EventLog`	Eine Meldung mit benanntem Ort schreiben
`log.clear_log()`	`EventLog`	Alle Einträge entfernen

mark_fatal() bleibt ein Verb statt fatal = True zu werden, weil es ein einseitiger Übergang ist: es gibt keinen Weg zurück.

Severity

Schweregrade von Protokollmeldungen.

Wert	Beschreibung
`Severity.Success`	Erfolgsmeldung
`Severity.Info`	Informationsmeldung
`Severity.Informational`	Informationsmeldung; gleichbedeutend mit `Severity.Info`
`Severity.Warning`	Nicht fatale Warnung
`Severity.Error`	Behebbarer Fehler