Click Dialect API

Tier: Dialect Surface

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

Mapping and Runtime Helpers

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

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.

load_snapshot

load_snapshot(
    path: str | Path, *, skip_default: bool = True
) -> SystemState

Parameters:

Name	Type	Description	Default
path	str | Path	Path to a CSV file exported via Click Programming Software's Data → Read Data from PLC → All → Save.	required
skip_default	bool	If True (default), omit addresses that still hold their power-on default.	True

Returns:

Name	Type	Description
A	SystemState	class:SystemState seeded with the mapped tag values.

LadderBundle dataclass

LadderExportError

Bases: RuntimeError

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

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,
    output_path: str | Path | None = None,
) -> 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
output_path	str | Path | None	Optional path to write the generated Python file. If None, the code is returned as a string only.	None

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, or if the CSV format is invalid.
TypeError	If source is not a supported type.

ladder_to_pyrung_project

ladder_to_pyrung_project(
    source: str | Path | LadderBundle,
    *,
    nickname_csv: str | Path | None = None,
    nicknames: dict[str, str] | None = None,
    output_dir: str | Path | None = None,
    index: bool = False,
    overwrite: bool = False,
    machine_name: str = "PLC",
) -> 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
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 (tags.py, main.py, subroutines/) are always written.	False
machine_name	str	Human-readable machine name for CLAUDE.md/AGENTS.md header (e.g. from the .ckp filename).	'PLC'

Returns:

Type	Description
dict[str, str]	A dict mapping relative file paths to their content, e.g.
dict[str, str]	{"main.py": "...", "tags.py": "...", "subroutines/startup.py": "..."}.

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

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

x module-attribute

x: InputBlock = cast(
    InputBlock, _block_from_bank_config(BANKS["X"])
)

y module-attribute

y: OutputBlock = cast(
    OutputBlock, _block_from_bank_config(BANKS["Y"])
)

c module-attribute

c: Block = _block_from_bank_config(BANKS['C'])

t module-attribute

t: Block = _block_from_bank_config(BANKS['T'])

ct module-attribute

ct: Block = _block_from_bank_config(BANKS['CT'])

sc module-attribute

sc: Block = _block_from_bank_config(BANKS['SC'])

ds module-attribute

ds: Block = _block_from_bank_config(BANKS['DS'])

dd module-attribute

dd: Block = _block_from_bank_config(BANKS['DD'])

dh module-attribute

dh: Block = _block_from_bank_config(BANKS['DH'])

df module-attribute

df: Block = _block_from_bank_config(BANKS['DF'])

xd module-attribute

xd: InputBlock = cast(
    InputBlock, _block_from_bank_config(BANKS["XD"])
)

yd module-attribute

yd: OutputBlock = cast(
    OutputBlock, _block_from_bank_config(BANKS["YD"])
)

xd0u module-attribute

xd0u = InputTag('XD0u', WORD, retentive=False)

yd0u module-attribute

yd0u = OutputTag('YD0u', WORD, retentive=False)

td module-attribute

td: Block = _block_from_bank_config(BANKS['TD'])

ctd module-attribute

ctd: Block = _block_from_bank_config(BANKS['CTD'])

sd module-attribute

sd: Block = _block_from_bank_config(BANKS['SD'])

txt module-attribute

txt: Block = _block_from_bank_config(BANKS['TXT'])