SCR301: invalid-event-script-header

Event script file whose first line is not the canonical header

Code	SCR301
Name	invalid-event-script-header
Category	Scripts (SCR)
Default severity	error
Enabled by default	yes
Fix available	sometimes
Fix safety	unsafe
ign-lint equivalent	none

What it does

Checks line 1 of the .py files that hold a complete function: gateway events (startup, shutdown, update, timer, scheduled, tag change, message), Perspective session and page events and WebDev handlers. Ignition never runs the header written in the file: when line 1 starts with def <name>(, it drops the whole line and compiles the rest under its own canonical header (for example def handleMessage(payload):); otherwise it compiles the whole file as the body. The rule reports:

• a header with other parameters or defaults: they have no effect, and parameters that are not in the canonical header are undefined at run time;
• a one-line function (def handleTimerEvent(): doWork()): the body on line 1 is dropped with the header and never runs;
• a header wrapped onto several lines: only line 1 is dropped, and the rest of the header becomes a syntax error;
• a file whose first code line is not indented and not the header (top level code, a header below comments or blank lines, a function with another name): Ignition compiles it as the body of the canonical header, which fails because the body is not indented.

Differences that change nothing are not reported: whitespace (def onStartup( ):), a comment after the colon, and defaults on the canonical parameters (def handleMessage(payload=None):), since Ignition always passes those arguments. A header-less file whose code is indented is the legacy body-only style and compiles; it is not reported. Vision Client event files are not checked.

Why is this bad?

The script silently runs differently from what the file says, or does not compile at all.

Example

def handleMessage(payload, retries=3):
  for i in range(retries):
    process(payload)

Use instead:

def handleMessage(payload):
  retries = 3
  for i in range(retries):
    process(payload)

Fix

Rewrites line 1 to the canonical header when it is a complete one-line def (keeping a comment after the colon); moves a one-line body to its own indented line; for a header-less file of top-level code, inserts the canonical header and indents every line with one tab, unless the file has a string that spans lines (indenting would change its value). Wrapped headers and misplaced headers are not fixed. Unsafe: code that relied on written parameters or defaults must be adapted.

---

Generated from the rule metadata by iglint generate-docs; iglint rule SCR301 prints the same page in the terminal. Source: docs/rules/SCR301.md.