Files API¶

Tier: Stable Core

Nickname CSV, DataView CDV, PLC data, installed modules, and channel parameters.

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.

pyclickplc.Module `dataclass` ¶

Installed module identity and physical I/O counts.

A count of zero means the module has no I/O of that kind. Counts describe hardware capacity, not currently assigned channel addresses.

pyclickplc.Modules `dataclass` ¶

Installed CPU, CPU slots 0/1, and expansion positions 1..8.

Empty positions are omitted from the read-only mappings. CPU is None if the project does not identify one. Power supplies are not included.

pyclickplc.read_modules ¶

read_modules(path: str | Path) -> Modules

Read installed hardware and I/O counts without requiring CLICK installed.

CPU slots use keys 0 and 1; expansions use keys 1 through 8. Unpopulated positions and stale CPU slots unsupported by the installed CPU are omitted. Channel parameters are not interpreted, so malformed channel records do not prevent reading the hardware inventory.

Raises OSError for unreadable files and ValueError for malformed INI data, invalid module IDs, or unknown installed hardware. Missing CPU information returns cpu=None; a file without installed modules returns empty mappings.

pyclickplc.ChannelParameters `dataclass` ¶

Normalized DF addresses assigned to analog input and output channels.

pyclickplc.read_channel_parameters ¶

read_channel_parameters(
    path: str | Path,
) -> ChannelParameters

Read analog channel assignments for the installed CLICK hardware.

Covers built-in CPU analog channels, expansion positions 1..8, and CLICK PLUS CPU slots 0 and 1. Output addresses are separate from input addresses; scaling and electrical ranges are not interpreted. Empty assignments and settings left behind by removed or non-analog modules are ignored.

Returns empty sets if there are no assigned analog channels. Raises OSError for unreadable files and ValueError for malformed channel data or unknown installed hardware. No CLICK installation is required.

pyclickplc.read_plc_data ¶

read_plc_data(
    path: str | Path, *, skip_default: bool = False
) -> dict[str, bool | int | float | str]

Parse a Click PLC 'Read Data from PLC' CSV dump.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the CSV file exported from Click Programming Software via Data > Read Data from PLC > Save to File.	required
`skip_default`	`bool`	If True, omit addresses whose value equals the bank default (`False` for bits, `0` for ints, `0.0` for floats, `""` for text).	`False`

Returns:

Type	Description
`dict[str, bool \| int \| float \| str]`	Dict mapping normalised address strings (e.g. `"X001"`, `"DS1"`)
`dict[str, bool \| int \| float \| str]`	to native Python values (`bool` for bits, `int` for INT/INT2/HEX,
`dict[str, bool \| int \| float \| str]`	`float` for FLOAT, `str` for TXT).

pyclickplc.write_plc_data ¶

write_plc_data(
    path: str | Path,
    data: Mapping[str, bool | int | float | str],
    *,
    banks: Iterable[str] | None = None,
) -> None

Write a Click PLC data CSV that can be loaded via Write Data into PLC.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Output file path.	required
`data`	`Mapping[str, bool \| int \| float \| str]`	Dict mapping normalised address strings (e.g. `"X001"`, `"DS1"`) to native Python values — the same format :func:`read_plc_data` returns.	required
`banks`	`Iterable[str] \| None`	Bank names to include (e.g. `["DS", "DF"]`). None (default) writes every bank present in data. Pass :data:`ALL_BANKS` to force a full dump with defaults.	`None`

Files API¶

pyclickplc.read_csv ¶

pyclickplc.write_csv ¶

pyclickplc.AddressRecordMap ¶

pyclickplc.make_address_record ¶

pyclickplc.read_cdv ¶

pyclickplc.write_cdv ¶

pyclickplc.verify_cdv ¶

pyclickplc.check_cdv_file ¶

pyclickplc.DataViewFile dataclass ¶

value_to_display staticmethod ¶

validate_display staticmethod ¶

try_parse_display staticmethod ¶

validate_row_display staticmethod ¶

set_row_new_value_from_display staticmethod ¶

load classmethod ¶

save ¶

verify ¶

pyclickplc.DataViewRecord dataclass ¶

is_empty property ¶

is_writable property ¶

memory_type property ¶

address_number property ¶

from_address classmethod ¶

update_data_type ¶

clear ¶

pyclickplc.make_dataview_record ¶

pyclickplc.get_data_type_for_address ¶

pyclickplc.validate_new_value ¶

pyclickplc.Module dataclass ¶

pyclickplc.Modules dataclass ¶

pyclickplc.read_modules ¶

pyclickplc.ChannelParameters dataclass ¶

pyclickplc.read_channel_parameters ¶

pyclickplc.read_plc_data ¶

pyclickplc.write_plc_data ¶

pyclickplc.DataViewFile `dataclass` ¶

value_to_display `staticmethod` ¶

validate_display `staticmethod` ¶

try_parse_display `staticmethod` ¶

validate_row_display `staticmethod` ¶

set_row_new_value_from_display `staticmethod` ¶

load `classmethod` ¶

pyclickplc.DataViewRecord `dataclass` ¶

is_empty `property` ¶

is_writable `property` ¶

memory_type `property` ¶

address_number `property` ¶

from_address `classmethod` ¶

pyclickplc.Module `dataclass` ¶

pyclickplc.Modules `dataclass` ¶

pyclickplc.ChannelParameters `dataclass` ¶