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
« 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"""
5import typing
7from zserio.bitwriter import BitStreamWriter
8from zserio.bitbuffer import BitBuffer
9from zserio.bitreader import BitStreamReader
11def serialize(obj: typing.Any) -> BitBuffer:
12 """
13 Serializes generated object to the bit buffer.
15 Before serialization, the method calls initialize_offsets() on the given zserio object.
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.
21 Example:
23 .. code:: python
25 import zserio
27 obj = SomeZserioObject()
28 bitbuffer = zserio.serialize(obj)
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 """
35 writer = _serialize(obj)
37 return BitBuffer(writer.byte_array, writer.bitposition)
39def deserialize(obj_class: typing.Type[typing.Any], bitbuffer: BitBuffer, *args) -> typing.Any:
40 """
41 Deserializes bit buffer to the generated object.
43 Example:
45 .. code:: python
47 import zserio
49 bitbuffer = zserio.BitBuffer(b'\\x00\\x01\\xBD\\x5A', 31)
50 obj = zserio.deserialize(SomeZserioObject, bitbuffer, 0xAB)
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 """
59 reader = BitStreamReader.from_bitbuffer(bitbuffer)
61 return obj_class.from_reader(reader, *args)
63def serialize_to_bytes(obj: typing.Any) -> bytes:
64 """
65 Serializes generated object to the byte buffer.
67 Before serialization, the method calls initialize_offsets() on the given zserio object.
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.
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.
75 Example:
77 .. code:: python
79 import zserio
81 obj = SomeZserioObject()
82 buffer = zserio.serialize_to_bytes(obj)
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 """
89 writer = _serialize(obj)
91 return writer.byte_array
93def deserialize_from_bytes(obj_class: typing.Type[typing.Any], buffer: bytes, *args) -> typing.Any:
94 """
95 Deserializes byte buffer to the generated object.
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).
101 Example:
103 .. code:: python
105 import zserio
107 buffer = b'\\x00\\x01\\xBD\\x5A'
108 obj = zserio.deserialize_from_bytes(SomeZserioObject, buffer, 0xAB)
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 """
117 bitbuffer = BitBuffer(buffer)
119 return deserialize(obj_class, bitbuffer, *args)
121def serialize_to_file(obj: typing.Any, filename: str) -> None:
122 """
123 Serializes generated object to the file.
125 Before serialization, the method calls initialize_offsets() on the given zserio object.
127 This is a convenient method for users to easily write given generated object to file.
129 Example:
131 .. code:: python
133 import zserio
135 obj = SomeZserioObject()
136 buffer = zserio.serialize_to_file(obj, "file_name.bin")
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 """
143 writer = _serialize(obj)
144 writer.to_file(filename)
146def deserialize_from_file(obj_class: typing.Type[typing.Any], filename: str, *args) -> typing.Any:
147 """
148 Deserializes file to the generated object.
150 This is a convenient method for users to easily read given generated object from file.
152 Example:
154 .. code:: python
156 import zserio
158 obj = zserio.deserialize_from_file(SomeZserioObject, "file_name.bin", 0xAB)
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 """
167 reader = BitStreamReader.from_file(filename)
169 return obj_class.from_reader(reader, *args)
171def _serialize(obj: typing.Any) -> BitStreamWriter:
172 writer = BitStreamWriter()
173 obj.initialize_offsets(writer.bitposition)
174 obj.write(writer)
176 return writer