Make global DataType. (#2794)

Author: janiversen

doc/source/_static/examples.tgz

@@ -23,31 +23,18 @@ Usage examples
 
 Class definitions
 ^^^^^^^^^^^^^^^^^
-.. autoclass:: pymodbus.simulator.SimData
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :member-order: bysource
-
-.. autoclass:: pymodbus.simulator.SimDevice
+.. autoclass:: pymodbus.constants.DataType
     :members:
     :undoc-members:
-    :show-inheritance:
     :member-order: bysource
 
-.. autoclass:: pymodbus.simulator.SimDataType
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :member-order: bysource
-
-.. autoclass:: pymodbus.simulator.SimValueType
+.. autoclass:: pymodbus.simulator.SimData
     :members:
     :undoc-members:
     :show-inheritance:
     :member-order: bysource
 
-.. autoclass:: pymodbus.simulator.SimAction
+.. autoclass:: pymodbus.simulator.SimDevice
     :members:
     :undoc-members:
     :show-inheritance:

doc/source/_static/examples.zip

@@ -6,7 +6,8 @@
 There are different examples showing the flexibility of the datamodel.
 """
 
-from pymodbus.simulator import SimData, SimDataType, SimDevice
+from pymodbus.constants import DataType
+from pymodbus.simulator import SimData, SimDevice
 
 
 def define_datamodel():
@@ -29,25 +30,26 @@ def define_datamodel():
     """
     # SimData can be instantiated with positional or optional parameters:
     assert SimData(
-            5, 17, 10, SimDataType.REGISTERS
+            5, 17, 10, DataType.REGISTERS
         ) == SimData(
-            address=5, value=17, count=10, datatype=SimDataType.REGISTERS
+            address=5, value=17, count=10, datatype=DataType.REGISTERS
         )
 
     # Define a group of coils/direct inputs non-shared (address=15..31 each 1 bit)
-    block1 = SimData(address=15, value=True, count=16, datatype=SimDataType.BITS)
+    block1 = SimData(address=15, value=True, count=16, datatype=DataType.BITS)
     # Define a group of coils/direct inputs shared (address=15..31 each 16 bit)
-    block2 = SimData(address=15, value=0xFFFF, count=16, datatype=SimDataType.BITS)
+    block2 = SimData(address=15, value=0xFFFF, count=16, datatype=DataType.BITS)
 
     # Define a group of holding/input registers (remark NO difference between shared and non-shared)
-    block3 = SimData(10, 123.4, datatype=SimDataType.FLOAT32)
-    block4 = SimData(17, value=123, count=5, datatype=SimDataType.INT64)
-    block5 = SimData(27, "Hello ", datatype=SimDataType.STRING)
-
-    # Please use SimDataType.DEFAULT to define register limits.
-    # this datatype only uses 1 object, whereas SimDataType.REGISTERS uses <count> objects,
-    # mean SimDataType.DEFAULT is factors more efficient and much less memory consuming
-    block_def = SimData(0, count=1000, datatype=SimDataType.DEFAULT)
+    block3 = SimData(10, 123.4, datatype=DataType.FLOAT32)
+    block4 = SimData(17, value=123, count=5, datatype=DataType.INT64)
+    block5 = SimData(27, "Hello ", datatype=DataType.STRING)
+
+    # Please use DataType.DEFAULT to define register limits.
+    # this datatype only uses 1 object, whereas DataType.REGISTERS uses <count> objects,
+    # mean DataType.DEFAULT is factors more efficient and much less memory consuming
+    # JAN TO CORRECT.
+    block_def = SimData(0, count=1000, datatype=DataType.REGISTERS)
 
     # SimDevice can be instantiated with positional or optional parameters:
     assert SimDevice(

doc/source/simulator/datamodel.rst

@@ -1,9 +1,9 @@
 """Modbus Client Common."""
 from __future__ import annotations
 
+import enum
 import struct
 from abc import abstractmethod
-from enum import Enum
 from typing import Generic, Literal, TypeVar, cast
 
 import pymodbus.pdu.bit_message as pdu_bit
@@ -677,7 +677,7 @@ def read_device_information(self, *, read_code: int | None = None,
     # Converter methods
     # ------------------
 
-    class DATATYPE(Enum):
+    class DATATYPE(enum.Enum):
         """Datatype enum (name and internal data), used for convert_* calls."""
 
         INT16 = ("h", 1)
@@ -692,7 +692,7 @@ class DATATYPE(Enum):
         BITS = ("bits", 0)
 
     @classmethod
-    def convert_from_registers(
+    def convert_from_registers(  # noqa: C901
         cls, registers: list[int], data_type: DATATYPE, word_order: Literal["big", "little"] = "big", string_encoding: str = "utf-8"
     ) -> int | float | str | list[bool] | list[int] | list[float]:
         """Convert registers to int/float/str.
@@ -702,9 +702,15 @@ def convert_from_registers(
         :param word_order: "big"/"little" order of words/registers
         :param string_encoding: The encoding with which to decode the bytearray, only used when data_type=DATATYPE.STRING
         :returns: scalar or array of "data_type"
+        :raises TypeError: when data_type is not DATATYPE
         :raises ModbusException: when size of registers is not a multiple of data_type
         :raises ParameterException: when the specified string encoding is not supported
         """
+        if not isinstance(data_type, cls.DATATYPE):
+            raise TypeError(
+                "Illegal data_type, please use <client>.DATATYPE!"
+            )
+
         if not (data_len := data_type.value[1]):
             byte_list = bytearray()
             if word_order == "little":
@@ -735,7 +741,7 @@ def convert_from_registers(
         return result if len(result) != 1 else result[0]
 
     @classmethod
-    def convert_to_registers(
+    def convert_to_registers(  # noqa: C901
         cls, value: int | float | str | list[bool] | list[int] | list[float], data_type: DATATYPE, word_order: Literal["big", "little"] = "big", string_encoding: str = "utf-8"
     ) -> list[int]:
         """Convert int/float/str to registers (16/32/64 bit).
@@ -745,9 +751,12 @@ def convert_to_registers(
         :param word_order: "big"/"little" order of words/registers
         :param string_encoding: The encoding with which to encode the bytearray, only used when data_type=DATATYPE.STRING
         :returns: List of registers, can be used directly in e.g. write_registers()
-        :raises TypeError: when there is a mismatch between data_type and value
+        :raises TypeError: when there is a mismatch between data_type and value or data_type is not DATATYPE
         :raises ParameterException: when the specified string encoding is not supported
         """
+        if not isinstance(data_type, cls.DATATYPE):
+            raise TypeError("Illegal data_type, please use <client>.DATATYPE!")
+
         if data_type == cls.DATATYPE.BITS:
             if not isinstance(value, list):
                 raise TypeError(f"Value should be list of bool but is {type(value)}.")

examples/server_datamodel.py

@@ -9,7 +9,7 @@
 INTERNAL_ERROR = "Pymodbus internal error"
 
 
-class ModbusStatus(int, enum.Enum):
+class ModbusStatus(enum.IntEnum):
     """These represent various status codes in the modbus protocol.
 
     .. attribute:: WAITING
@@ -37,7 +37,7 @@ class ModbusStatus(int, enum.Enum):
     OFF = 0x0000
 
 
-class ExcCodes(int, enum.Enum):
+class ExcCodes(enum.IntEnum):
    """Represents the allowed exception codes."""
 
    ILLEGAL_FUNCTION = 0x01
@@ -52,7 +52,7 @@ class ExcCodes(int, enum.Enum):
    GATEWAY_NO_RESPONSE = 0x0B
 
 
-class ModbusPlusOperation(int, enum.Enum):
+class ModbusPlusOperation(enum.IntEnum):
     """Represents the type of modbus plus request.
 
     .. attribute:: GET_STATISTICS
@@ -70,7 +70,7 @@ class ModbusPlusOperation(int, enum.Enum):
     CLEAR_STATISTICS = 0x0004
 
 
-class DeviceInformation(int, enum.Enum):
+class DeviceInformation(enum.IntEnum):
     """Represents what type of device information to read.
 
     .. attribute:: BASIC
@@ -103,7 +103,7 @@ class DeviceInformation(int, enum.Enum):
     SPECIFIC = 0x04
 
 
-class MoreData(int, enum.Enum):
+class MoreData(enum.IntEnum):
     """Represents the more follows condition.
 
     .. attribute:: NOTHING
@@ -117,3 +117,46 @@ class MoreData(int, enum.Enum):
 
     NOTHING = 0x00
     KEEP_READING = 0xFF
+
+
+class DataType(enum.IntEnum):
+    """Register types, used to define of a group of registers.
+
+    This is the types pymodbus recognizes, actually the modbus standard do NOT define e.g. INT32,
+    but since nearly every device contain e.g. values of type INT32, it is available in pymodbus,
+    with automatic conversions to/from registers.
+    """
+
+    #: 1 integer == 1 register
+    INT16 = enum.auto()
+
+    #: 1 positive integer == 1 register
+    UINT16 = enum.auto()
+
+    #: 1 integer == 2 registers
+    INT32 = enum.auto()
+
+    #: 1 positive integer == 2 registers
+    UINT32 = enum.auto()
+
+    #: 1 integer == 4 registers
+    INT64 = enum.auto()
+
+    #: 1 positive integer == 4 register
+    UINT64 = enum.auto()
+
+    #: 1 float == 2 registers
+    FLOAT32 = enum.auto()
+
+    #: 1 float == 4 registers
+    FLOAT64 = enum.auto()
+
+    #: 1 string == (len(string) / 2) registers
+    STRING = enum.auto()
+
+    #: 16 bits == 1 register
+    BITS = enum.auto()
+
+    #: Registers == 16bit
+    REGISTERS = enum.auto()
+

pymodbus/client/mixin.py

@@ -4,7 +4,6 @@
     "SimAction",
     "SimCore",
     "SimData",
-    "SimDataType",
     "SimDevice",
     "SimValueType",
 ]
@@ -13,7 +12,6 @@
 from pymodbus.simulator.simdata import (
     SimAction,
     SimData,
-    SimDataType,
     SimDevice,
     SimValueType,
 )