etm.wccoa.services.data

Data transfer objects for WinCC OA service responses.

This module contains the data classes used to transfer information between services and callers.

Package Contents

Classes

OaDpValueItem Immutable data object holding information about one datapoint value.
OaDpTimedValueItem Immutable data object holding information about a datapoint value at a specific time.
OaPeriodResultSeries Historical values for a single DPE (level 1 grouping).
OaPeriodResult Grouped historical period result.
OaAlertValueItem Immutable data object holding information about one alert value.
OaDpAliasItem Immutable data object holding information about one datapoint alias.
OaDpDescriptionItem Immutable data object holding information about one datapoint description.
OaElementType Element type for datapoint type definition nodes.
OaDpTypeReference Immutable reference to a datapoint type.
OaDpTypeRefItem Forward reference item for dp_get_dp_type_refs().
OaDpTypeUsageRefItem Backward reference item for dp_get_refs_to_dp_type().
OaDpTypeDefinition Mutable definition of a datapoint type element.
OaQueryResult Immutable query result represented as a table.
OaQueryResultColumn Immutable metadata about a query result column.
OaQueryResultRow Accessor for a single row in an OaQueryResult.
OaSplitResult Result envelope for split requests.
OaConnectUpdateType Type of update received by connect callbacks.
OaDpDescriptionFormattingMode Defines how the description of a datapoint should be formatted.

API

class etm.wccoa.services.data.OaDpValueItem

Immutable data object holding information about one datapoint value.

This is returned by GetDpValue operations.

  • Variables:
    • dp_reference – The datapoint reference (path + identifier).
    • dp_value – The datapoint value (may be None).

property dp_path : str

The datapoint element path.

class etm.wccoa.services.data.OaDpTimedValueItem

Immutable data object holding information about a datapoint value at a specific time.

This is returned by historical value queries.

  • Variables:
    • dp_reference – The datapoint reference (path + identifier).
    • source_time – The timestamp of the value.
    • dp_value – The datapoint value (may be None).

source_time : datetime.datetime

None

property dp_path : str

The datapoint element path.

class etm.wccoa.services.data.OaPeriodResultSeries

Historical values for a single DPE (level 1 grouping).

Internal raw storage keeps parallel raw time/value tuples for memory efficiency and LAZY conversion (see bug239092): timestamps are stored as raw (seconds, nanoseconds) integers and values as raw Python scalars. datetime and OaVariant objects are reconstructed only on access, so value_count and unread values cost nothing. Public access exposes OaDpTimedValueItem objects carrying the DPE context.

property dp_path : str

The datapoint element path for this series.

property value_count : int

Number of time/value entries in this series.

property times : tuple

Timestamps as immutable tuple (reconstructed on access).

property values : tuple[etm.wccoa.datatypes.OaVariant | None, ...]

Values as immutable tuple (reconstructed on access).

This can be found at: etm.wccoa.datatypes.OaVariant

get_value_item(index: int) → etm.wccoa.services.data._dp_value_items.OaDpTimedValueItem

Get a DPE-aware timed value item by index (reconstructed on access).

  • Returns: The timed value item at index, with the DPE reference of this series.

value_items() → tuple[etm.wccoa.services.data._dp_value_items.OaDpTimedValueItem, ...]

Return all DPE-aware timed value items for this series.

  • Returns: All timed value items of this series, with the DPE reference of this series.

class etm.wccoa.services.data.OaPeriodResult

Grouped historical period result.

Level 1 groups by DPE via OaPeriodResultSeries. Level 2 stores time/value pairs within each series.

Iteration and indexing on this object provide a flat, list-like view of OaDpTimedValueItem for convenience and backward compatibility.

For example, find all DPE and times where the value was between x and y:

result = manager.dp_get_period(start, end, dpe_list)
filtered = [
    (item.dp_path, item.source_time, item.dp_value)
    for item in result
    if x <= item.dp_value <= y
]

property series_count : int

Number of DPE groups.

property total_value_count : int

Total number of time/value items across all DPE groups.

get_series(index: int) → etm.wccoa.services.data._dp_period_result.OaPeriodResultSeries

Get a DPE series by index.

  • Returns: The series at index.

get_series_by_dp_path(dp_path: str) → etm.wccoa.services.data._dp_period_result.OaPeriodResultSeries | None

Get the first series matching a DPE path, or None.

  • Returns: The first series of the DPE path, or None if there is none.

get_series_dp_reference(index: int) → etm.wccoa.datatypes.DpReference

Get the DPE reference of a series.

  • Returns: The DPE reference of the series at index.

get_series_dp_path(index: int) → str

Get the DPE path of a series.

  • Returns: The DPE path of the series at index.

get_series_dp_identifier(index: int) → etm.wccoa.datatypes.DpIdentifier

Get the DPE identifier of a series.

  • Returns: The DPE identifier of the series at index.

class etm.wccoa.services.data.OaAlertValueItem

Immutable data object holding information about one alert value.

This is returned by alert operations.

  • Variables:
    • dp_reference – The datapoint reference (path + identifier).
    • internal_alarm_time – The internal alert time (AlertTime).
    • dp_value – The datapoint value (may be None).

property dp_path : str

The datapoint element path.

property alarm_index : int

Get the alarm index from the internal alarm time.

property alarm_time : datetime.datetime

Get the alarm time from the internal alarm time.

class etm.wccoa.services.data.OaDpAliasItem

Immutable data object holding information about one datapoint alias.

  • Variables:
    • dp_reference – The datapoint reference (path + identifier).
    • alias – The alias string.

alias : str

None

property dp_path : str

The datapoint element path.

class etm.wccoa.services.data.OaDpDescriptionItem

Immutable data object holding information about one datapoint description.

  • Variables:
    • dp_reference – The datapoint reference (path + identifier).
    • description – The localized description.

property dp_path : str

The datapoint element path.

class etm.wccoa.services.data.OaElementType

Bases: enum.IntEnum

Element type for datapoint type definition nodes.

This enum defines the possible element types in a WinCC OA datapoint type structure.

Initialization

Initialize self. See help(type(self)) for accurate signature.

NO_ELEMENT

0

No element type.

STRUCTURE

1

Structure node (container for other elements).

ARRAY

2

Array type flag (can be OR’d with other types).

DYN_CHAR

3

Dynamic byte array.

DYN_UINT

4

Dynamic uint array.

DYN_INT

5

Dynamic int array.

DYN_FLOAT

6

Dynamic float array.

DYN_BIT

7

Dynamic bool array.

DYN_BIT32

8

Dynamic bit32 array.

DYN_TEXT

9

Dynamic string array.

DYN_TIME

10

Dynamic time array.

CHAR_STRUCT

11

Byte in structure.

UINT_STRUCT

12

UInt in structure.

INT_STRUCT

13

Int in structure.

FLOAT_STRUCT

14

Float in structure.

BIT_STRUCT

15

Bool in structure.

BIT32_STRUCT

16

Bit32 in structure.

TEXT_STRUCT

17

String in structure.

TIME_STRUCT

18

Time in structure.

CHAR

19

8-bit unsigned integer (byte).

UINT

20

32-bit unsigned integer.

INT

21

32-bit signed integer.

FLOAT

22

64-bit floating point.

BOOL

23

Boolean value (Bit).

BIT32

24

32-bit bitfield.

STRING

25

Text string.

TIME

26

Date/time value.

DPID

27

Datapoint identifier.

NO_VALUE

28

No value type.

DYN_DPID

29

Dynamic DpId array.

DYN_CHAR_STRUCT

30

Dynamic byte struct array.

DYN_UINT_STRUCT

31

Dynamic uint struct array.

DYN_INT_STRUCT

32

Dynamic int struct array.

DYN_FLOAT_STRUCT

33

Dynamic float struct array.

DYN_BIT_STRUCT

34

Dynamic bool struct array.

DYN_BIT32_STRUCT

35

Dynamic bit32 struct array.

DYN_TEXT_STRUCT

36

Dynamic string struct array.

DYN_TIME_STRUCT

37

Dynamic time struct array.

DYN_DPID_STRUCT

38

Dynamic DpId struct array.

DPID_STRUCT

39

DpId in structure.

NO_VALUE_STRUCT

40

No value in structure.

TYPE_REFERENCE

41

Reference to another datapoint type.

LANG_STRING

42

Localized string (LangText).

LANG_STRING_STRUCT

43

LangText in structure.

DYN_LANG_STRING

44

Dynamic LangText array.

DYN_LANG_STRING_STRUCT

45

Dynamic LangText struct array.

BLOB

46

Binary large object.

BLOB_STRUCT

47

Blob in structure.

DYN_BLOB

48

Dynamic Blob array.

DYN_BLOB_STRUCT

49

Dynamic Blob struct array.

BIT64

50

64-bit bitfield.

DYN_BIT64

51

Dynamic bit64 array.

BIT64_STRUCT

52

Bit64 in structure.

DYN_BIT64_STRUCT

53

Dynamic bit64 struct array.

LONG

54

64-bit signed integer.

DYN_LONG

55

Dynamic long array.

LONG_STRUCT

56

Long in structure.

DYN_LONG_STRUCT

57

Dynamic long struct array.

ULONG

58

64-bit unsigned integer.

DYN_ULONG

59

Dynamic ulong array.

ULONG_STRUCT

60

ULong in structure.

DYN_ULONG_STRUCT

61

Dynamic ulong struct array.

as_integer_ratio()

bit_count()

bit_length()

conjugate()

class denominator

class imag

class numerator

class real

to_bytes()

name()

value()

class etm.wccoa.services.data.OaDpTypeReference

Immutable reference to a datapoint type.

A type reference can be specified either by name or by ID. After reading from the system, both may be available.

  • Variables:
    • name – The name of the referenced type (if available).
    • id – The ID of the referenced type (if available).

name : str | None

None

id : int | None

None

property is_name : bool

Check if reference by name is available.

property is_id : bool

Check if reference by ID is available.

classmethod from_name(name: str) → etm.wccoa.services.data._dp_type_definition.OaDpTypeReference

Create a type reference by name.

  • Returns: A type reference that holds only the name.

classmethod from_id(type_id: int) → etm.wccoa.services.data._dp_type_definition.OaDpTypeReference

Create a type reference by ID.

  • Returns: A type reference that holds only the ID.

classmethod from_name_and_id(name: str, type_id: int) → etm.wccoa.services.data._dp_type_definition.OaDpTypeReference

Create a type reference with both name and ID.

  • Returns: A type reference that holds the name and the ID.

class etm.wccoa.services.data.OaDpTypeRefItem

Forward reference item for dp_get_dp_type_refs().

  • Variables:
    • ref_name – Name of the reference field.
    • dpe_path – Datapoint element path where the reference is defined.

ref_name : str

None

dpe_path : str

None

class etm.wccoa.services.data.OaDpTypeUsageRefItem

Backward reference item for dp_get_refs_to_dp_type().

  • Variables:
    • dpt_name – Name of the referring datapoint type.
    • dpe_path – Datapoint element path where the reference is used.

dpt_name : str

None

dpe_path : str

None

class etm.wccoa.services.data.OaDpTypeDefinition

Mutable definition of a datapoint type element.

This class represents one node in a datapoint type hierarchy. It can have child elements, forming a tree structure.

Note: This class is intentionally mutable (unlike other data items) because type definitions need to be built up incrementally when creating or modifying types.

  • Variables:
    • name – Name of the element.
    • element_type – The element type.
    • id – Optional element ID (set after creation in system).
    • dp_type_reference – Reference to another type (for TypeReference elements).

name : str

None

element_type : etm.wccoa.services.data._element_type.OaElementType

None

id : int | None

None

dp_type_reference : etm.wccoa.services.data._dp_type_definition.OaDpTypeReference | None

None

property elements : tuple[etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition, ...]

Get child elements as immutable tuple.

add_element(element: etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition) → None

Add a child element.

add_structure(name: str, element_id: int | None = None) → etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition

Add a structure child element.

  • Parameters:
    • name – Name of the element.
    • element_id – Optional element ID.
  • Returns: The created child element.

add_leaf(name: str, element_type: etm.wccoa.services.data._element_type.OaElementType, element_id: int | None = None) → etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition

Add a leaf element (non-structure).

  • Parameters:
    • name – Name of the element.
    • element_type – The element type.
    • element_id – Optional element ID.
  • Returns: The created child element.

add_type_reference(name: str, ref_type: str | int, element_id: int | None = None) → etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition

Add a type reference element.

  • Parameters:
    • name – Name of the element.
    • ref_type – Referenced type name or ID.
    • element_id – Optional element ID.
  • Returns: The created child element.

contains_element(name: str) → bool

Check if a child element with the given name exists.

  • Returns: True if a direct child element has that name.

get_element(name: str) → etm.wccoa.services.data._dp_type_definition.OaDpTypeDefinition

Get a child element by name.

  • Returns: The direct child element with that name.
  • Raises:
    • KeyError – If no element with the name exists.

remove_element(name: str) → None

Remove a child element by name.

  • Raises:
    • KeyError – If no element with the name exists.

clear_elements() → None

Remove all child elements.

class etm.wccoa.services.data.OaQueryResult

Immutable query result represented as a table.

Logical table model:

  • Row 0 is the header row and contains column DP references.
  • Rows 1..n are data rows.
  • Column 0 in each data row holds the DP reference to that dataset.
  • Columns 1..m in each data row hold the actual data values.
  • Variables:
    • _raw_columns – Header column metadata (including header column 0).
    • _raw_rows – Data rows including column 0 DP references.
    • table_name – Optional name of the result table.

table_name : str = <Multiline-String>

property record_count : int

Get the number of records (rows).

property column_count : int

Get the number of data columns (excluding the header column).

property raw_column_count : int

Get the number of raw columns (including the header column).

get_row(row: int) → etm.wccoa.services.data._query_result.OaQueryResultRow

Get a row accessor for convenient typed access.

  • Parameters:
    • row – The row index (0-based).
  • Returns: An OaQueryResultRow accessor.
  • Raises:
    • IndexError – If row is out of range.
get_row_dp_path(row: int) → str

Get the DP path from column 0 of a specific row.

  • Parameters:
    • row – The row index (0-based).
  • Returns: The DP path string.
  • Raises:
    • IndexError – If row is out of range.
get_row_dp_identifier(row: int) → etm.wccoa.datatypes.DpIdentifier | None

Get the DpIdentifier from column 0 of a specific row.

  • Parameters:
    • row – The row index (0-based).
  • Returns: The DpIdentifier or None.
  • Raises:
    • IndexError – If row is out of range.
get_row_dp_reference(row: int) → etm.wccoa.datatypes.DpReference | None

Get the DpReference from column 0 of a specific row.

  • Parameters:
    • row – The row index (0-based).
  • Returns: The DpReference or None.
  • Raises:
    • IndexError – If row is out of range.
get_value(row: int, column: int) → etm.wccoa.datatypes.OaVariant

Get the value at a specific data cell.

  • Parameters:
    • row – The row index (0-based).
    • column – The data-column index (0-based, excludes header column).
  • Returns: The value as OaVariant.
  • Raises:
    • IndexError – If row or column is out of range.
get_column_name(column: int) → str

Get the name of a data column.

  • Parameters:
    • column – The data-column index (0-based, excludes header column).
  • Returns: The column name.
  • Raises:
    • IndexError – If column is out of range.
get_column_oa_type(column: int) → etm.wccoa.datatypes.OaVariantType

Get the OA type of a data column.

  • Parameters:
    • column – The data-column index (0-based, excludes header column).
  • Returns: The OA variant type.
  • Raises:
    • IndexError – If column is out of range.
get_column_type(column: int) → type

Get the Python type of a data column.

  • Parameters:
    • column – The data-column index (0-based, excludes header column).
  • Returns: The Python type.
  • Raises:
    • IndexError – If column is out of range.
get_raw_value(row: int, column: int) → etm.wccoa.datatypes.OaVariant

Get a value at a specific raw cell including the header column.

  • Returns: The value of the cell.

class etm.wccoa.services.data.OaQueryResultColumn

Immutable metadata about a query result column.

  • Variables:
    • dp_reference – The resolved DpReference for this column (if available).
    • oa_type – The WinCC OA variant type of the column.
    • py_type – The Python type of the column.
py_type : type

None

property name : str

The column name.

property dp_path : str

The DP path string.

property dp_identifier : etm.wccoa.datatypes.DpIdentifier | None

The DpIdentifier for this column (if available).

This can be found at: etm.wccoa.datatypes.DpIdentifier

class etm.wccoa.services.data.OaQueryResultRow(data: tuple, columns: tuple[etm.wccoa.services.data._query_result.OaQueryResultColumn, ...] | None = None)

Accessor for a single row in an OaQueryResult.

Provides convenient typed access to the DP reference in column 0 and data values in columns 1+.

Initialization

property dp_reference : etm.wccoa.datatypes.DpReference | None

The DpReference from column 0, or None if not available.

This can be found at: etm.wccoa.datatypes.DpReference

property dp_path : str

The DP path from column 0.

property dp_identifier : etm.wccoa.datatypes.DpIdentifier | None

The DpIdentifier from column 0, or None.

This can be found at: etm.wccoa.datatypes.DpIdentifier

property values : tuple[etm.wccoa.datatypes.OaVariant, ...]

The row values excluding the header column (column 0).

This can be found at: etm.wccoa.datatypes.OaVariant

property column_count : int

The number of data columns excluding the header column.

get_value(column: int) → etm.wccoa.datatypes.OaVariant

Get a value at a specific data-column index (0-based).

Data columns exclude the header/reference column at index 0.

  • Parameters:
    • column – The data-column index.
  • Returns: The data value.
  • Raises:
    • IndexError – If column is out of range.
get_raw_value(column: int) → etm.wccoa.datatypes.OaVariant

Get a raw value at a specific column index (0-based).

Raw columns include the header/reference column at index 0.

  • Returns: The value of the cell.

class etm.wccoa.services.data.OaSplitResult

Bases: typing.Generic

Result envelope for split requests.

Wraps the partial data returned by dp_query_split or dp_get_period_split together with the metadata needed to drive the iteration loop.

  • Parameters:
    • request_id – ID for subsequent calls (invalid when progress is 100).
    • answer_id – Request/answer ID from the data manager.
    • progress – Execution progress from 0 to 100, where 100 means complete.
    • data – The (partial) result data whose type depends on the originating split method.
request_id : int

None

answer_id : int

None

progress : int

None

data : etm.wccoa.services.data._split_result.T

None

class etm.wccoa.services.data.OaConnectUpdateType

Bases: enum.IntEnum

Type of update received by connect callbacks.

Distinguishes initial answers from regular value-change hotlinks and redundancy/distribution refresh events.

Initialization

Initialize self. See help(type(self)) for accurate signature.

NORMAL

0

Normal update after a value change.

ANSWER

1

Initial answer with current values.

REFRESH

2

Refresh after a redundancy switch or distribution reconnect.

as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
class numerator
class real
to_bytes()
name()
value()

class etm.wccoa.services.data.OaDpDescriptionFormattingMode

Bases: enum.IntEnum

Defines how the description of a datapoint should be formatted.

This enum controls the behavior of description retrieval operations.

Initialization

Initialize self. See help(type(self)) for accurate signature.

SYSTEM_DEFAULT

99

The system default is used.

Normally the default is DescriptionOrDpPathWithMasterDp, but could be changed with config file entry dpGetDescriptionMode in section.

DESCRIPTION_OF_ELEMENT_OR_ERROR

None

Returns only the description at the DPE.

Returns error if none exists.

DESCRIPTION_OR_NAME_OF_ELEMENT

None

Returns the description from the DPE.

If no description exists, the element name is returned. For the root DPE the DP name is returned.

DESCRIPTION_OR_DP_PATH

0

Returns the description from the DPE.

If no description exists, the DPE name (System1:DP.EL1.EL2) is returned.

DESCRIPTION_OR_DP_PATH_WITH_MASTER_DP

1

Returns the description from the DPE with master DP fallback.

If no description exists, the description of the DPE from the master datapoint is linked with the description from the root element resp. the DP name: Description = root DP + “ “ + master DP. If no master DP or no description exists, the DPE name is returned.

DESCRIPTION_OR_DP_PATH_WITH_MASTER_DP_INVERSE

2

Like DescriptionOrDpPathWithMasterDp, but reversed.

Description = master DPE + “ “ + root DP.

DESCRIPTION_OR_DP_PATH_WITH_MASTER_DP_RECURSIVE

3

Returns description with recursive master DP lookup.

The description is assembled from items from the root: Description = root DP + “ “ + master DPE1 + “ “ + … + master DPE.

as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
class numerator
class real
to_bytes()
name()
value()