Coverage for /home/jenkins/workspace/NDS/Zserio/NDS_ZSERIO-linux-build/compiler/extensions/python/runtime/src/zserio/serialization.py: 100%

27 statements  

« prev     ^ index     » next       coverage.py v6.5.0, created at 2023-12-13 15:12 +0000

1""" 

2The module provides help methods for serialization and deserialization of generated objects. 

3""" 

4 

5import typing 

6 

7from zserio.bitwriter import BitStreamWriter 

8from zserio.bitbuffer import BitBuffer 

9from zserio.bitreader import BitStreamReader 

10 

11def serialize(obj: typing.Any) -> BitBuffer: 

12 """ 

13 Serializes generated object to the bit buffer. 

14 

15 Before serialization, the method calls initialize_offsets() on the given zserio object. 

16 

17 Because serialization to the bit buffer does not have to be byte aligned (divisible by 8), it's possible 

18 that not all bits of the last byte are used. In this case, only most significant bits of the corresponded 

19 size are used. 

20 

21 Example: 

22 

23 .. code:: python 

24 

25 import zserio 

26 

27 obj = SomeZserioObject() 

28 bitbuffer = zserio.serialize(obj) 

29 

30 :param obj: Generated object to serialize. 

31 :returns: Bit buffer which represents generated object in binary format. 

32 :raises PythonRuntimeException: Throws in case of any error during serialization. 

33 """ 

34 

35 writer = _serialize(obj) 

36 

37 return BitBuffer(writer.byte_array, writer.bitposition) 

38 

39def deserialize(obj_class: typing.Type[typing.Any], bitbuffer: BitBuffer, *args) -> typing.Any: 

40 """ 

41 Deserializes bit buffer to the generated object. 

42 

43 Example: 

44 

45 .. code:: python 

46 

47 import zserio 

48 

49 bitbuffer = zserio.BitBuffer(b'\\x00\\x01\\xBD\\x5A', 31) 

50 obj = zserio.deserialize(SomeZserioObject, bitbuffer, 0xAB) 

51 

52 :param obj_class: Class instance of the generated object to deserialize. 

53 :param bitbuffer: Bit buffer which represents generated object in binary format. 

54 :param args: Additional arguments needed for obj_class.from_reader method. 

55 :returns: Generated object created from given bit buffer. 

56 :raises PythonRuntimeException: Throws in case of any error during deserialization. 

57 """ 

58 

59 reader = BitStreamReader.from_bitbuffer(bitbuffer) 

60 

61 return obj_class.from_reader(reader, *args) 

62 

63def serialize_to_bytes(obj: typing.Any) -> bytes: 

64 """ 

65 Serializes generated object to the byte buffer. 

66 

67 Before serialization, the method calls initialize_offsets() on the given zserio object. 

68 

69 This is a convenient method for users which do not need exact number of bits to which the given object 

70 will be serialized. 

71 

72 However, it's still possible that not all bits of the last byte are used. In this case, only most 

73 significant bits of the corresponding size are used. 

74 

75 Example: 

76 

77 .. code:: python 

78 

79 import zserio 

80 

81 obj = SomeZserioObject() 

82 buffer = zserio.serialize_to_bytes(obj) 

83 

84 :param obj: Generated object to serialize. 

85 :returns: Bytes which represents generated object in binary format. 

86 :raises PythonRuntimeException: Throws in case of any error during serialization. 

87 """ 

88 

89 writer = _serialize(obj) 

90 

91 return writer.byte_array 

92 

93def deserialize_from_bytes(obj_class: typing.Type[typing.Any], buffer: bytes, *args) -> typing.Any: 

94 """ 

95 Deserializes byte buffer to the generated object. 

96 

97 This method can potentially use all bits of the last byte even if not all of them were written during 

98 serialization (because there is no way how to specify exact number of bits). Thus, it could allow reading 

99 behind stream (possibly in case of damaged data). 

100 

101 Example: 

102 

103 .. code:: python 

104 

105 import zserio 

106 

107 buffer = b'\\x00\\x01\\xBD\\x5A' 

108 obj = zserio.deserialize_from_bytes(SomeZserioObject, buffer, 0xAB) 

109 

110 :param obj_class: Class instance of the generated object to deserialize. 

111 :param buffer: Byte buffer which represents generated object in binary format. 

112 :param args: Additional arguments needed for obj_class.from_reader method. 

113 :returns: Generated object created from given byte buffer. 

114 :raises PythonRuntimeException: Throws in case of any error during deserialization. 

115 """ 

116 

117 bitbuffer = BitBuffer(buffer) 

118 

119 return deserialize(obj_class, bitbuffer, *args) 

120 

121def serialize_to_file(obj: typing.Any, filename: str) -> None: 

122 """ 

123 Serializes generated object to the file. 

124 

125 Before serialization, the method calls initialize_offsets() on the given zserio object. 

126 

127 This is a convenient method for users to easily write given generated object to file. 

128 

129 Example: 

130 

131 .. code:: python 

132 

133 import zserio 

134 

135 obj = SomeZserioObject() 

136 buffer = zserio.serialize_to_file(obj, "file_name.bin") 

137 

138 :param obj: Generated object to serialize. 

139 :param filename: File to write. 

140 :raises PythonRuntimeException: Throws in case of any error during serialization. 

141 """ 

142 

143 writer = _serialize(obj) 

144 writer.to_file(filename) 

145 

146def deserialize_from_file(obj_class: typing.Type[typing.Any], filename: str, *args) -> typing.Any: 

147 """ 

148 Deserializes file to the generated object. 

149 

150 This is a convenient method for users to easily read given generated object from file. 

151 

152 Example: 

153 

154 .. code:: python 

155 

156 import zserio 

157 

158 obj = zserio.deserialize_from_file(SomeZserioObject, "file_name.bin", 0xAB) 

159 

160 :param obj_class: Class instance of the generated object to deserialize. 

161 :param filename: File which represents generated object in binary format. 

162 :param args: Additional arguments needed for obj_class.from_reader method. 

163 :returns: Generated object created from given file contents. 

164 :raises PythonRuntimeException: Throws in case of any error during deserialization. 

165 """ 

166 

167 reader = BitStreamReader.from_file(filename) 

168 

169 return obj_class.from_reader(reader, *args) 

170 

171def _serialize(obj: typing.Any) -> BitStreamWriter: 

172 writer = BitStreamWriter() 

173 obj.initialize_offsets(writer.bitposition) 

174 obj.write(writer) 

175 

176 return writer