Tag map

pyrung.click.tag_map

Click logical-to-hardware mapping layer.

MappedSlot dataclass

Public runtime slot metadata for a mapped logical/hardware pair.

StructuredImport dataclass

Structured metadata reconstructed during nickname import.

TagMap

Maps logical Tags and Blocks to Click hardware addresses.

TagMap is the pivot of the Click dialect. It links semantic tags (which have no hardware knowledge) to concrete Click addresses, and drives nickname file round-trips and validation.

Constructing from a dict — map individual tags and entire blocks:

.. code-block:: python

from pyrung.click import TagMap, x, y, c, ds

mapping = TagMap({
    StartButton:  x[1],              # Tag → Tag (BOOL → X001)
    Motor:        y[1],              # Tag → Tag (BOOL → Y001)
    Alarms:       c.select(1, 100),  # Block → BlockRange
    Speed:        ds[1],             # Tag → Tag (INT → DS1)
})

From a Click nickname CSV file:

.. code-block:: python

mapping = TagMap.from_nickname_file("project.csv")

Exporting back to CSV:

.. code-block:: python

mapping.to_nickname_file("project.csv")

Validating a program:

.. code-block:: python

report = mapping.validate(logic, mode="warn")
print(report.summary())

Resolving a logical tag to its hardware address:

.. code-block:: python

mapping.resolve(Speed)              # "DS1"
mapping.resolve(Alarms, index=5)   # "C5"

Type compatibility is validated at construction time — mapping a BOOL tag to a DS address (INT) raises ValueError. Hardware address conflicts (two logical tags mapped to the same Click address) also raise ValueError.

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

Build a TagMap from a Click nickname CSV file.

Reads the CSV produced by Click Programming Software and reconstructs logical-to-hardware mappings:

• Block tag pairs (rows with <Name> / </Name> comments) → Block objects mapped to hardware ranges.
• Standalone nicknames → individual Tag objects.
• _D suffix pairs (timer/counter accumulators) are linked automatically.
• Initial values and retentive flags are preserved.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the Click nickname CSV file.	required
mode	Literal['warn', 'strict']	Behavior for dotted UDT grouping failures: "warn" (default) falls back to plain blocks and records structure_warnings; "strict" raises ValueError.	'warn'

Returns:

Type	Description
TagMap	A TagMap ready for use with validate() and to_nickname_file().

Raises:

Type	Description
FileNotFoundError	If the path does not exist.
ValueError	If the CSV contains conflicting block boundaries or mismatched memory types, or if mode is invalid.

to_nickname_file

to_nickname_file(path: str | Path) -> int

Write mapped addresses to a Click nickname CSV file.

Emits one row per mapped hardware address. Block entries produce rows with <Name> / </Name> comment markers that Click Programming Software can parse as block tag groups. Unmapped addresses are omitted.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination CSV path. Parent directories must exist.	required

Returns:

Type	Description
int	Number of rows written.

resolve

resolve(
    source: Tag | Block | str, index: int | None = None
) -> str

Resolve a logical source to a hardware address string.

offset_for

offset_for(block: Block) -> int

Return affine offset for a mapped block.

block_entry_by_name

block_entry_by_name(name: str) -> _BlockEntry | None

Look up a block entry by logical block name.

validate

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

Validate a Program against Click portability rules.

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.

to_ladder

to_ladder(program: Program) -> LadderBundle

Render program logic as deterministic Click ladder CSV row matrices.

mapped_slots

mapped_slots() -> tuple[MappedSlot, ...]

Return all mapped slots for runtime hardware-facing consumers.