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.

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

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

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