Coverage for /home/runner/work/zserio/zserio/compiler/extensions/python/runtime/src/zserio/serialization.py: 100%

27 statements  

« prev     ^ index     » next       coverage.py v6.5.0, created at 2024-10-29 13:10 +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 

11 

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

13 """ 

14 Serializes generated object to the bit buffer. 

15 

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

17 

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

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

20 size are used. 

21 

22 Example: 

23 

24 .. code:: python 

25 

26 import zserio 

27 

28 obj = SomeZserioObject() 

29 bitbuffer = zserio.serialize(obj) 

30 

31 :param obj: Generated object to serialize. 

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

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

34 """ 

35 

36 writer = _serialize(obj) 

37 

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

39 

40 

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

42 """ 

43 Deserializes bit buffer to the generated object. 

44 

45 Example: 

46 

47 .. code:: python 

48 

49 import zserio 

50 

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

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

53 

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

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

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

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

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

59 """ 

60 

61 reader = BitStreamReader.from_bitbuffer(bitbuffer) 

62 

63 return obj_class.from_reader(reader, *args) 

64 

65 

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

67 """ 

68 Serializes generated object to the byte buffer. 

69 

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

71 

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

73 will be serialized. 

74 

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

76 significant bits of the corresponding size are used. 

77 

78 Example: 

79 

80 .. code:: python 

81 

82 import zserio 

83 

84 obj = SomeZserioObject() 

85 buffer = zserio.serialize_to_bytes(obj) 

86 

87 :param obj: Generated object to serialize. 

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

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

90 """ 

91 

92 writer = _serialize(obj) 

93 

94 return writer.byte_array 

95 

96 

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

98 """ 

99 Deserializes byte buffer to the generated object. 

100 

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

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

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

104 

105 Example: 

106 

107 .. code:: python 

108 

109 import zserio 

110 

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

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

113 

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

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

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

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

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

119 """ 

120 

121 bitbuffer = BitBuffer(buffer) 

122 

123 return deserialize(obj_class, bitbuffer, *args) 

124 

125 

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

127 """ 

128 Serializes generated object to the file. 

129 

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

131 

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

133 

134 Example: 

135 

136 .. code:: python 

137 

138 import zserio 

139 

140 obj = SomeZserioObject() 

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

142 

143 :param obj: Generated object to serialize. 

144 :param filename: File to write. 

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

146 """ 

147 

148 writer = _serialize(obj) 

149 writer.to_file(filename) 

150 

151 

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

153 """ 

154 Deserializes file to the generated object. 

155 

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

157 

158 Example: 

159 

160 .. code:: python 

161 

162 import zserio 

163 

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

165 

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

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

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

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

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

171 """ 

172 

173 reader = BitStreamReader.from_file(filename) 

174 

175 return obj_class.from_reader(reader, *args) 

176 

177 

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

179 writer = BitStreamWriter() 

180 obj.initialize_offsets(writer.bitposition) 

181 obj.write(writer) 

182 

183 return writer