Skip to content

Validation API

Tier: Stable Core

Nickname/comment/initial-value validators and system nickname constants.

pyclickplc.AUTOMATIONDIRECT_SYSTEM_CONTROL_RELAY_SOURCE module-attribute 

AUTOMATIONDIRECT_SYSTEM_CONTROL_RELAY_SOURCE = "https://cdn.automationdirect.com/static/helpfiles/click/Content/109.htm"

pyclickplc.AUTOMATIONDIRECT_SYSTEM_DATA_REGISTER_SOURCE module-attribute 

AUTOMATIONDIRECT_SYSTEM_DATA_REGISTER_SOURCE = "https://cdn.automationdirect.com/static/helpfiles/click/Content/110.htm"

pyclickplc.AUTOMATIONDIRECT_SYSTEM_NICKNAME_REVIEWED_ON module-attribute 

AUTOMATIONDIRECT_SYSTEM_NICKNAME_REVIEWED_ON = date(
    2026, 9, 2
)

pyclickplc.AUTOMATIONDIRECT_SYSTEM_NICKNAMES module-attribute 

AUTOMATIONDIRECT_SYSTEM_NICKNAMES: dict[
    tuple[str, int], SystemNicknameGuidance
] = {
    key: (
        SystemNicknameGuidance(
            nickname=nickname,
            repair_from=get(key, _NO_AUTOMATIC_REPAIR),
            source=_source_for(key[0]),
            reviewed_on=AUTOMATIONDIRECT_SYSTEM_NICKNAME_REVIEWED_ON,
        )
    )
    for key, nickname in (items())
}

pyclickplc.SystemNicknameGuidance dataclass

Vendor guidance and safe repair inputs for one system address.

pyclickplc.SYSTEM_NICKNAME_TYPES module-attribute 

SYSTEM_NICKNAME_TYPES: frozenset[str] = frozenset(
    {"SC", "SD", "X"}
)

pyclickplc.canonical_system_nickname 

canonical_system_nickname(
    memory_type: str, address: int
) -> str | None

Return the documented nickname for a maintained system address.

pyclickplc.canonicalize_system_nickname 

canonicalize_system_nickname(
    memory_type: str, address: int, nickname: str
) -> str

Repair an explicitly known stale vendor nickname, preserving other data.

pyclickplc.is_canonical_system_nickname 

is_canonical_system_nickname(
    memory_type: str, address: int, nickname: str
) -> bool

Return whether nickname is the maintained vendor value for the address.

pyclickplc.validate_nickname 

validate_nickname(
    nickname: str, *, system_bank: str | None = None
) -> tuple[bool, str]

Validate nickname format (length, characters, reserved words).

Does NOT check uniqueness -- that is application-specific.

Parameters:

Name Type Description Default
nickname str

The nickname to validate

 required
system_bank str | None

Optional system bank context: - "SC"/"SD": allows PLC system punctuation - "X": allows only _IO... style system names - None: standard user nickname rules

 None

Returns:

Type Description
tuple[bool, str]

Tuple of (is_valid, error_message) - error_message is "" if valid

pyclickplc.validate_comment 

validate_comment(comment: str) -> tuple[bool, str]

Validate comment length.

Does NOT check block tag uniqueness -- that requires blocks.py context.

Parameters:

Name Type Description Default
comment str

The comment to validate

 required

Returns:

Type Description
tuple[bool, str]

Tuple of (is_valid, error_message) - error_message is "" if valid

pyclickplc.validate_initial_value 

validate_initial_value(
    initial_value: str, data_type: int
) -> tuple[bool, str]

Validate an initial value against the data type rules.

Parameters:

Name Type Description Default
initial_value str

The initial value string to validate

 required
data_type int

The DataType number (0=bit, 1=int, 2=int2, 3=float, 4=hex, 6=txt)

 required

Returns:

Type Description
tuple[bool, str]

Tuple of (is_valid, error_message) - error_message is "" if valid