Files API

Tier: Stable Core

Nickname CSV and DataView CDV models and file I/O helpers.

pyclickplc.read_csv

read_csv(path: str | Path) -> AddressRecordMap

Read a user-format CSV file into AddressRecords.

The user CSV has columns: Address, Data Type, Nickname, Initial Value, Retentive, Address Comment.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the CSV file.	required

Returns:

Type	Description
AddressRecordMap	AddressRecordMap keyed by addr_key (int) with .addr and .tag views.

pyclickplc.write_csv

write_csv(
    path: str | Path,
    records: Mapping[int, AddressRecord]
    | Iterable[AddressRecord],
) -> int

Write AddressRecords to a user-format CSV file.

Only records with content (nickname, comment, non-default initial value or retentive) are written. Records are sorted by memory type order then address.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to write the CSV file.	required
records	Mapping[int, AddressRecord] | Iterable[AddressRecord]	Address records to write. Accepts a mapping keyed by addr_key or any iterable of AddressRecord values.	required

Returns:

Type	Description
int	Number of rows written.

pyclickplc.AddressRecordMap

Bases: dict[int, AddressRecord]

Address record mapping with helper lookup views.

pyclickplc.make_address_record

make_address_record(
    address: str,
    *,
    nickname: str = "",
    comment: str = "",
    initial_value: str = "",
    retentive: bool | None = None,
    used: bool | None = None,
) -> AddressRecord

Create an AddressRecord from a display address with inferred defaults.

pyclickplc.read_cdv

read_cdv(path: Path | str) -> DataViewFile

Read a CDV file into a DataViewFile model.

pyclickplc.write_cdv

write_cdv(
    path: Path | str,
    dataview: DataViewFile | Iterable[DataViewRecord],
) -> None

Write a DataViewFile or list of DataViewRecords to a CDV path.

pyclickplc.verify_cdv

verify_cdv(
    path: Path | str,
    rows: list[DataViewRecord],
    has_new_values: bool | None = None,
) -> list[str]

Verify in-memory rows against a CDV file using native value comparison.

pyclickplc.check_cdv_file

check_cdv_file(path: Path | str) -> list[str]

Validate a single CDV file and return issue strings.

pyclickplc.DataViewFile dataclass

CDV file model with row data in native Python types.

value_to_display staticmethod

value_to_display(
    value: DataViewValue, data_type: DataType | None
) -> str

Render a native value as a display string.

validate_display staticmethod

validate_display(
    display_str: str, data_type: DataType | None
) -> tuple[bool, str]

Validate display text for a target data type.

try_parse_display staticmethod

try_parse_display(
    display_str: str, data_type: DataType | None
) -> DisplayParseResult

Parse a display string to a native value without raising.

validate_row_display staticmethod

validate_row_display(
    row: DataViewRecord, display_str: str
) -> tuple[bool, str]

Validate a user edit for a specific row.

set_row_new_value_from_display staticmethod

set_row_new_value_from_display(
    row: DataViewRecord, display_str: str
) -> None

Strictly set a row's native new_value from a display string.

load classmethod

load(path: Path | str) -> DataViewFile

Load a CDV file and parse new values into native Python types.

save

save(path: Path | str | None = None) -> None

Save CDV back to disk, converting native values at the file boundary.

verify

verify(path: Path | str | None = None) -> list[str]

Compare this in-memory dataview to a CDV file on disk.

pyclickplc.DataViewRecord dataclass

Represents a single row in a CLICK DataView.

A dataview row contains an address to monitor and optionally a new value to write to that address. The nickname and comment are display-only fields populated from SharedAddressData. For user-facing creation from display addresses, prefer make_dataview_record(...).

is_empty property

is_empty: bool

Check if this row is empty (no address set).

is_writable property

is_writable: bool

Check if this address can have a New Value written to it.

memory_type property

memory_type: str | None

Get the memory type prefix (X, Y, DS, etc.) or None if invalid.

address_number property

address_number: str | None

Get the address number as a display string, or None if invalid.

from_address classmethod

from_address(
    address: str, *, new_value: DataViewValue = None
) -> DataViewRecord

Build a DataViewRecord from a display address string.

update_data_type

update_data_type() -> bool

Update the DataType based on the current address.

Returns:

Type	Description
bool	True if data_type was updated, False if address is invalid.

clear

clear() -> None

Clear all fields in this row.

pyclickplc.make_dataview_record

make_dataview_record(
    address: str, *, new_value: DataViewValue = None
) -> DataViewRecord

Create a DataViewRecord from a display address with inferred defaults.

pyclickplc.get_data_type_for_address

get_data_type_for_address(address: str) -> DataType | None

Get the DataType for an address.

Parameters:

Name	Type	Description	Default
address	str	Address string like "X001", "DS1"	required

Returns:

Type	Description
DataType | None	DataType or None if address is invalid.

pyclickplc.validate_new_value

validate_new_value(
    display_str: str, data_type: DataType
) -> tuple[bool, str]

Validate a user-entered display string for the New Value column.