Deprecate BinaryPayloadDecoder / BinaryPayloadBuilder. (#2456)

pymodbus/payload.py

@@ -38,6 +38,15 @@ class BinaryPayloadBuilder:
         payload = builder.build()
     """
 
+    @classmethod
+    def deprecate(cls):
+        """Log warning."""
+        Log.warning(
+            "BinaryPayloadBuilder is deprecated and will be removed in v3.9.0 !\n"
+            "Please use \"client.convert_from_registers()\" or \"client.convert_to_registers\"\n"
+            "See documentation: \"https://pymodbus.readthedocs.io/en/latest/source/client.html#pymodbus.client.mixin.ModbusClientMixin.convert_from_registers\""
+        )
+
     def __init__(
         self, payload=None, byteorder=Endian.LITTLE, wordorder=Endian.BIG, repack=False
     ):
@@ -48,6 +57,7 @@ def __init__(
         :param wordorder: The endianness of the word (when wordcount is >= 2)
         :param repack: Repack the provided payload based on BO
         """
+        self.deprecate()
         self._payload = payload or []
         self._byteorder = byteorder
         self._wordorder = wordorder
@@ -79,6 +89,7 @@ def _pack_words(self, fstring: str, value) -> bytes:
 
     def encode(self) -> bytes:
         """Get the payload buffer encoded in bytes."""
+        self.deprecate()
         return b"".join(self._payload)
 
     def __str__(self) -> str:
@@ -90,13 +101,15 @@ def __str__(self) -> str:
 
     def reset(self) -> None:
         """Reset the payload buffer."""
+        self.deprecate()
         self._payload = []
 
     def to_registers(self):
         """Convert the payload buffer to register layout that can be used as a context block.
 
         :returns: The register layout to use as a block
         """
+        self.deprecate()
         # fstring = self._byteorder+"H"
         fstring = "!H"
         payload = self.build()
@@ -112,6 +125,7 @@ def to_coils(self) -> list[bool]:
 
         :returns: The coil layout to use as a block
         """
+        self.deprecate()
         payload = self.to_registers()
         coils = [bool(int(bit)) for reg in payload for bit in format(reg, "016b")]
         return coils
@@ -124,6 +138,7 @@ def build(self) -> list[bytes]:
 
         :returns: The payload buffer as a list
         """
+        self.deprecate()
         buffer = self.encode()
         length = len(buffer)
         buffer += b"\x00" * (length % 2)
@@ -138,6 +153,7 @@ def add_bits(self, values: list[bool]) -> None:
 
         :param values: The value to add to the buffer
         """
+        self.deprecate()
         value = pack_bitstring(values)
         self._payload.append(value)
 
@@ -146,6 +162,7 @@ def add_8bit_uint(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = self._byteorder + "B"
         self._payload.append(pack(fstring, value))
 
@@ -154,6 +171,7 @@ def add_16bit_uint(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = self._byteorder + "H"
         self._payload.append(pack(fstring, value))
 
@@ -162,6 +180,7 @@ def add_32bit_uint(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "I"
         # fstring = self._byteorder + "I"
         p_string = self._pack_words(fstring, value)
@@ -172,6 +191,7 @@ def add_64bit_uint(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "Q"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -181,6 +201,7 @@ def add_8bit_int(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = self._byteorder + "b"
         self._payload.append(pack(fstring, value))
 
@@ -189,6 +210,7 @@ def add_16bit_int(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = self._byteorder + "h"
         self._payload.append(pack(fstring, value))
 
@@ -197,6 +219,7 @@ def add_32bit_int(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "i"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -206,6 +229,7 @@ def add_64bit_int(self, value: int) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "q"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -215,6 +239,7 @@ def add_16bit_float(self, value: float) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "e"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -224,6 +249,7 @@ def add_32bit_float(self, value: float) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "f"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -233,6 +259,7 @@ def add_64bit_float(self, value: float) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = "d"
         p_string = self._pack_words(fstring, value)
         self._payload.append(p_string)
@@ -242,6 +269,7 @@ def add_string(self, value: str) -> None:
 
         :param value: The value to add to the buffer
         """
+        self.deprecate()
         fstring = self._byteorder + str(len(value)) + "s"
         self._payload.append(pack(fstring, value.encode()))
 
@@ -258,18 +286,29 @@ class BinaryPayloadDecoder:
         second  = decoder.decode_16bit_uint()
     """
 
+    @classmethod
+    def deprecate(cls):
+        """Log warning."""
+        Log.warning(
+            "BinaryPayloadDecoder is deprecated and will be removed in v3.9.0 !\n"
+            "Please use \"client.convert_from_registers()\" or \"client.convert_to_registers\"\n"
+            "See documentation: \"https://pymodbus.readthedocs.io/en/latest/source/client.html#pymodbus.client.mixin.ModbusClientMixin.convert_from_registers\""
+        )
+
     def __init__(self, payload, byteorder=Endian.LITTLE, wordorder=Endian.BIG):
         """Initialize a new payload decoder.
 
         :param payload: The payload to decode with
         :param byteorder: The endianness of the payload
         :param wordorder: The endianness of the word (when wordcount is >= 2)
         """
+        self.deprecate()
         self._payload = payload
         self._pointer = 0x00
         self._byteorder = byteorder
         self._wordorder = wordorder
 
+
     @classmethod
     def fromRegisters(
         cls,
@@ -291,6 +330,7 @@ def fromRegisters(
         :returns: An initialized PayloadDecoder
         :raises ParameterException:
         """
+        cls.deprecate()
         Log.debug("{}", registers)
         if isinstance(registers, list):  # repack into flat binary
             payload = pack(f"!{len(registers)}H", *registers)
@@ -300,6 +340,7 @@ def fromRegisters(
     @classmethod
     def bit_chunks(cls, coils, size=8):
         """Return bit chunks."""
+        cls.deprecate()
         chunks = [coils[i : i + size] for i in range(0, len(coils), size)]
         return chunks
 
@@ -311,6 +352,7 @@ def fromCoils(
         _wordorder=Endian.BIG,
     ):
         """Initialize a payload decoder with the result of reading of coils."""
+        cls.deprecate()
         if isinstance(coils, list):
             payload = b""
             if padding := len(coils) % 8:  # Pad zeros
@@ -343,31 +385,36 @@ def _unpack_words(self, handle) -> bytes:
 
     def reset(self):
         """Reset the decoder pointer back to the start."""
+        self.deprecate()
         self._pointer = 0x00
 
     def decode_8bit_uint(self):
         """Decode a 8 bit unsigned int from the buffer."""
+        self.deprecate()
         self._pointer += 1
         fstring = self._byteorder + "B"
         handle = self._payload[self._pointer - 1 : self._pointer]
         return unpack(fstring, handle)[0]
 
     def decode_bits(self, package_len=1):
         """Decode a byte worth of bits from the buffer."""
+        self.deprecate()
         self._pointer += package_len
         # fstring = self._endian + "B"
         handle = self._payload[self._pointer - 1 : self._pointer]
         return unpack_bitstring(handle)
 
     def decode_16bit_uint(self):
         """Decode a 16 bit unsigned int from the buffer."""
+        self.deprecate()
         self._pointer += 2
         fstring = self._byteorder + "H"
         handle = self._payload[self._pointer - 2 : self._pointer]
         return unpack(fstring, handle)[0]
 
     def decode_32bit_uint(self):
         """Decode a 32 bit unsigned int from the buffer."""
+        self.deprecate()
         self._pointer += 4
         fstring = "I"
         handle = self._payload[self._pointer - 4 : self._pointer]
@@ -376,6 +423,7 @@ def decode_32bit_uint(self):
 
     def decode_64bit_uint(self):
         """Decode a 64 bit unsigned int from the buffer."""
+        self.deprecate()
         self._pointer += 8
         fstring = "Q"
         handle = self._payload[self._pointer - 8 : self._pointer]
@@ -384,20 +432,23 @@ def decode_64bit_uint(self):
 
     def decode_8bit_int(self):
         """Decode a 8 bit signed int from the buffer."""
+        self.deprecate()
         self._pointer += 1
         fstring = self._byteorder + "b"
         handle = self._payload[self._pointer - 1 : self._pointer]
         return unpack(fstring, handle)[0]
 
     def decode_16bit_int(self):
         """Decode a 16 bit signed int from the buffer."""
+        self.deprecate()
         self._pointer += 2
         fstring = self._byteorder + "h"
         handle = self._payload[self._pointer - 2 : self._pointer]
         return unpack(fstring, handle)[0]
 
     def decode_32bit_int(self):
         """Decode a 32 bit signed int from the buffer."""
+        self.deprecate()
         self._pointer += 4
         fstring = "i"
         handle = self._payload[self._pointer - 4 : self._pointer]
@@ -406,6 +457,7 @@ def decode_32bit_int(self):
 
     def decode_64bit_int(self):
         """Decode a 64 bit signed int from the buffer."""
+        self.deprecate()
         self._pointer += 8
         fstring = "q"
         handle = self._payload[self._pointer - 8 : self._pointer]
@@ -414,6 +466,7 @@ def decode_64bit_int(self):
 
     def decode_16bit_float(self):
         """Decode a 16 bit float from the buffer."""
+        self.deprecate()
         self._pointer += 2
         fstring = "e"
         handle = self._payload[self._pointer - 2 : self._pointer]
@@ -422,6 +475,7 @@ def decode_16bit_float(self):
 
     def decode_32bit_float(self):
         """Decode a 32 bit float from the buffer."""
+        self.deprecate()
         self._pointer += 4
         fstring = "f"
         handle = self._payload[self._pointer - 4 : self._pointer]
@@ -430,6 +484,7 @@ def decode_32bit_float(self):
 
     def decode_64bit_float(self):
         """Decode a 64 bit float(double) from the buffer."""
+        self.deprecate()
         self._pointer += 8
         fstring = "d"
         handle = self._payload[self._pointer - 8 : self._pointer]
@@ -441,6 +496,7 @@ def decode_string(self, size=1):
 
         :param size: The size of the string to decode
         """
+        self.deprecate()
         self._pointer += size
         return self._payload[self._pointer - size : self._pointer]
 
@@ -449,4 +505,5 @@ def skip_bytes(self, nbytes):
 
         :param nbytes: The number of bytes to skip
         """
+        self.deprecate()
         self._pointer += nbytes