Skip to content

Click Dialect API

Tier: Dialect Surface

Click prebuilt blocks, aliases, and validation/communication helpers.

Mapping and Runtime Helpers

WorkspaceKind module-attribute 

WorkspaceKind = Literal['temporary', 'persistent']

ValidationMode module-attribute 

ValidationMode = Literal['warn', 'strict']

TagMap

Parameters:

Name Type Description Default
mappings dict[Tag | Block, Tag | BlockRange] | Iterable[MappingEntry] | None

dict[Tag | Block, Tag | BlockRange], Iterable[MappingEntry], or None for an empty map.

 None
include_system bool

Whether to include built-in system tag mappings (SC/SD points). Default True.

 True
from_nickname_file classmethod 
from_nickname_file(
    path: str | Path,
    *,
    mode: Literal["warn", "strict"] = "warn",
) -> TagMap
to_nickname_file 
to_nickname_file(
    path: str | Path, *, blocks: Iterable[Any] | None = None
) -> int
resolve 
resolve(
    source: Tag | Block | str, index: int | None = None
) -> str
validate 
validate(
    program: Program,
    mode: ValidationMode = "warn",
    profile: HardwareProfile | None = None,
) -> ClickValidationReport

Parameters:

Name Type Description Default
program Program

The Program to validate.

 required
mode ValidationMode

"warn" (findings as hints) or "strict" (findings as errors).

 'warn'
profile HardwareProfile | None

Optional hardware capability profile override.

 None

Returns:

Type Description
ClickValidationReport

ClickValidationReport with categorized findings.
mapped_slots 
mapped_slots() -> tuple[MappedSlot, ...]
tags_from_plc_data 
tags_from_plc_data(
    data: Mapping[str, bool | int | float | str],
    *,
    blocks: Iterable[Any] | None = None,
) -> dict[str, bool | int | float | str]

Parameters:

Name Type Description Default
data Mapping[str, bool | int | float | str]

{hardware_address: value} dict — keys are normalised Click display addresses such as "X001" or "DS3".

 required
blocks Iterable[Any] | None

Click bank blocks whose slots the program uses directly, without a TagMap entry (x.slot(1, name="Button") or a bare ds[5]). Accepts a ClickBlockSet or any iterable of blocks; non-Block items are silently skipped. When omitted, only addresses mapped by this TagMap are returned.

 None

Returns:

Type Description
dict[str, bool | int | float | str]

{logical_name: value} dict containing only the addresses
dict[str, bool | int | float | str]

that appear in both data and this TagMap (or blocks).
load_snapshot 
load_snapshot(
    path: str | Path,
    *,
    skip_default: bool = True,
    blocks: Iterable[Any] | None = None,
) -> SystemState

Parameters:

Name Type Description Default
path str | Path

Path to a CSV file exported via Click Programming Software's PLC → Read Data from PLC → All → Save.

 required
skip_default bool

If True (default), omit addresses that still hold their power-on default.

 True
blocks Iterable[Any] | None

Click bank blocks to seed for slots used without a TagMap entry; see :meth:tags_from_plc_data. Generated projects export this as blocks beside mapping.

 None

Returns:

Name Type Description
A SystemState

class:SystemState seeded with the mapped tag values.

SystemNicknameRepair dataclass

SystemNicknameRepairRequired

Bases: ValueError

LadderBundle dataclass

LadderExportError

Bases: RuntimeError

CodegenIdentityError

Bases: Exception

ClickDataProvider

Parameters:

Name Type Description Default
runner PLC

The active PLC whose state is served.

 required
tag_map TagMap

Mapping from logical tag names to Click hardware addresses.

 required
fallback DataProvider | None

Optional provider for unmapped addresses. Defaults to an in-memory provider.

 None

ModbusAddress dataclass

ModbusReceiveInstruction dataclass

Bases: Instruction

external_payload_names property 
external_payload_names: frozenset[str]

ModbusRtuTarget dataclass

ModbusSendInstruction dataclass

Bases: Instruction

ModbusTcpTarget dataclass

RegisterType

Bases: Enum

WordOrder

Bases: Enum

NopInstruction

Bases: Instruction

execute 
execute(ctx: ScanContext, enabled: bool) -> None
is_terminal 
is_terminal() -> bool

RawInstruction

Bases: Instruction

execute 
execute(ctx: ScanContext, enabled: bool) -> None

ladder_to_pyrung 

ladder_to_pyrung(
    source: str | Path | LadderBundle,
    *,
    nickname_csv: str | Path | None = None,
    nicknames: dict[str, str] | None = None,
    analog_inputs: Iterable[str] = (),
    output_path: str | Path | None = None,
    validate: bool = True,
) -> str

Parameters:

Name Type Description Default
source str | Path | LadderBundle

A file path (to main.csv or a directory containing main.csv and optional subroutines/*.csv files), or a :class:LadderBundle for in-memory round-trip without disk I/O.

 required
nickname_csv str | Path | None

Optional path to a Click nickname CSV file (Address.csv). Read via pyclickplc.read_csv(), extracts {display_address: nickname} pairs for variable name substitution.

 None
nicknames dict[str, str] | None

Optional pre-parsed {operand: nickname} dict. Alternative to nickname_csv; useful when the caller already has the map.

 None
analog_inputs Iterable[str]

Analog input DF addresses supplied by project channel parameters; their generated tags are marked external.

 ()
output_path str | Path | None

Optional path to write the generated Python file. If None, the code is returned as a string only.

 None
validate bool

When True (default), run codegen self-checks: a decl-level identity check that the generated structure defaults reconstruct every source per-slot value (raises :class:CodegenIdentityError), and a rung-analysis check that no source contact is silently dropped for lack of wiring into an output (raises ValueError). When False, a dropped contact only warns instead of raising.

 True

Returns:

Type Description
str

The generated Python source code as a string.

Raises:

Type Description
ValueError

If both nickname_csv and nicknames are provided, if required subroutine CSV files are missing, if the CSV format is invalid, or if validate is True and a rung drops a source contact that reaches no output.
TypeError

If source is not a supported type.
CodegenIdentityError

If validate is True and the generated code would not reconstruct the source project's per-slot values.

ladder_to_pyrung_project 

ladder_to_pyrung_project(
    source: str | Path | LadderBundle,
    *,
    nickname_csv: str | Path | None = None,
    nicknames: dict[str, str] | None = None,
    analog_inputs: Iterable[str] = (),
    output_dir: str | Path | None = None,
    index: bool = False,
    overwrite: bool = False,
    machine_name: str = "PLC",
    workspace_kind: WorkspaceKind = "temporary",
    validate: bool = True,
) -> dict[str, str]

Parameters:

Name Type Description Default
source str | Path | LadderBundle

A file path (to main.csv or a directory containing main.csv and optional subroutines/*.csv files), or a :class:LadderBundle for in-memory round-trip without disk I/O.

 required
nickname_csv str | Path | None

Optional path to a Click nickname CSV file (Address.csv).

 None
nicknames dict[str, str] | None

Optional pre-parsed {operand: nickname} dict.

 None
analog_inputs Iterable[str]

Analog input DF addresses supplied by project channel parameters; their generated tags are marked external.

 ()
output_dir str | Path | None

Optional directory to write the project files into. If None, files are returned as strings only.

 None
overwrite bool

When False (default), scaffolding files (pyproject.toml, README.md, .vscode/) are skipped if they already exist on disk. Logic files under src/plc/ are always written.

 False
machine_name str

Human-readable machine name for AGENTS.md header (e.g. from the .ckp filename).

 'PLC'
workspace_kind WorkspaceKind

Whether generated lifecycle guidance describes a temporary CLICK project folder or a configured persistent workspace.

 'temporary'
validate bool

When True (default), run codegen self-checks (see :func:ladder_to_pyrung): a structure-default identity check (raises :class:CodegenIdentityError) and a dropped-contact check (raises ValueError). When False, dropped contacts only warn.

 True

Returns:

Type Description
dict[str, str]

A dict mapping relative file paths to their content, e.g.
dict[str, str]

{"src/plc/main.py": "...", "src/plc/tags.py": "..."}.

refresh_workspace_lifecycle_guidance 

refresh_workspace_lifecycle_guidance(
    existing: str, generated: str
) -> str

pyrung_to_ladder 

pyrung_to_ladder(
    program: Program,
    tag_map: TagMap,
    *,
    index: bool = False,
    validate: bool = True,
) -> LadderBundle

Parameters:

Name Type Description Default
program Program

The Program to export.

 required
tag_map TagMap

TagMap mapping logical tags to Click hardware addresses.

 required
index bool

When True, number rung markers sequentially (R1, R2, ...) instead of bare R. Counter restarts per program scope.

 False
validate bool

When True (default), run pre-export checks and round-trip verification. Set to False to skip validation for speed.

 True

Returns:

Type Description
LadderBundle

A LadderBundle containing main and subroutine row matrices.

send 

send(
    *,
    target: str | ModbusTcpTarget | ModbusRtuTarget,
    remote_start: str | ModbusAddress,
    source: Tag | BlockRange,
    sending: Tag,
    success: Tag,
    error: Tag,
    exception_response: Tag,
    count: int | None = None,
    word_swap: bool = False,
) -> None

receive 

receive(
    *,
    target: str | ModbusTcpTarget | ModbusRtuTarget,
    remote_start: str | ModbusAddress,
    dest: Tag | BlockRange,
    receiving: Tag,
    success: Tag,
    error: Tag,
    exception_response: Tag,
    count: int | None = None,
    word_swap: bool = False,
) -> None

validate_click_program 

validate_click_program(
    program: Program,
    tag_map: TagMap,
    mode: ValidationMode = "warn",
    profile: HardwareProfile | None = None,
) -> ClickValidationReport

Prebuilt Blocks and Aliases

Bit module-attribute 
Bit = Bool
Int2 module-attribute 
Int2 = Dint
Float module-attribute 
Float = Real
Hex module-attribute 
Hex = Word
Txt module-attribute 
Txt = Char
ClickBlockSet

Bases: NamedTuple

ClickBlocks 
ClickBlocks() -> ClickBlockSet