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

1""" 

2The module provides utilities for JSON debug string which can be obtained from zserio objects. 

3 

4.. note:: Zserio objects must be generated with `-withTypeInfoCode` zserio option to enable JSON debug string! 

5""" 

6 

7import io 

8import typing 

9 

10from zserio.walker import Walker, WalkFilter 

11from zserio.json import JsonWriter, JsonReader 

12 

13 

14def to_json_stream( 

15 obj: typing.Any, 

16 text_io: typing.TextIO, 

17 *, 

18 indent: typing.Union[None, int, str] = 4, 

19 walk_filter: typing.Optional[WalkFilter] = None 

20) -> None: 

21 """ 

22 Writes contents of given zserio object to debug stream in JSON format using Walker with JsonWriter. 

23 

24 Example: 

25 

26 .. code:: python 

27 

28 import io 

29 import zserio 

30 

31 obj = SomeZserioObject() 

32 text_io = io.StringIO() 

33 zserio.to_json_stream(obj, text_io) 

34 

35 The function allows usage of walk filters as well. The following example shows filtering of arrays 

36 up to 5 elements: 

37 

38 .. code:: python 

39 

40 import io 

41 import zserio 

42 

43 obj = SomeZserioObject() 

44 text_io = io.StringIO() 

45 walk_filter = zserio.ArrayLengthWalkFilter(5) 

46 zserio.to_json_stream(obj, text_io, walk_filter=walk_filter) 

47 

48 :param obj: Zserio object to use. 

49 :param text_io: Text stream to use. 

50 :param indent: Indent argument for JsonWriter. 

51 :param walk_filter: Walk filter to use by Walker. 

52 """ 

53 

54 json_writer = JsonWriter(text_io=text_io, indent=indent) 

55 walker = Walker(json_writer, walk_filter) 

56 walker.walk(obj) 

57 

58 

59def to_json_string( 

60 obj: typing.Any, 

61 *, 

62 indent: typing.Union[None, int, str] = 4, 

63 walk_filter: typing.Optional[WalkFilter] = None 

64) -> str: 

65 """ 

66 Gets debug string in JSON format using Walker with JsonWriter for given zserio object. 

67 

68 Example: 

69 

70 .. code:: python 

71 

72 import zserio 

73 

74 obj = SomeZserioObject() 

75 zserio.to_json_string(obj) 

76 

77 The function allows usage of walk filters as well. The following example shows filtering of arrays 

78 up to 5 elements: 

79 

80 .. code:: python 

81 

82 import zserio 

83 

84 obj = SomeZserioObject() 

85 walk_filter = zserio.ArrayLengthWalkFilter(5) 

86 zserio.to_json_string(obj, walk_filter=walk_filter) 

87 

88 :param obj: Zserio object to use. 

89 :param indent: Indent argument for JsonWriter. 

90 :param walk_filter: Walk filter to use by Walker. 

91 

92 :returns: JSON debug string. 

93 """ 

94 

95 text_io = io.StringIO() 

96 to_json_stream(obj, text_io, indent=indent, walk_filter=walk_filter) 

97 return text_io.getvalue() 

98 

99 

100def to_json_file( 

101 obj: typing.Any, 

102 filename: str, 

103 *, 

104 indent: typing.Union[None, int, str] = 4, 

105 walk_filter: typing.Optional[WalkFilter] = None 

106) -> None: 

107 """ 

108 Writes contents of given zserio object to debug file in JSON format using Walker with JsonWriter. 

109 

110 Example: 

111 

112 .. code:: python 

113 

114 import zserio 

115 

116 obj = SomeZserioObject() 

117 zserio.to_json_file(obj, "file_name.json") 

118 

119 The function allows usage of walk filters as well. The following example shows filtering of arrays 

120 up to 5 elements: 

121 

122 .. code:: python 

123 

124 import zserio 

125 

126 obj = SomeZserioObject() 

127 walk_filter = zserio.ArrayLengthWalkFilter(5) 

128 zserio.to_json_file(obj, "file_name.json", walk_filter=walk_filter) 

129 

130 :param obj: Zserio object to use. 

131 :param filename: Name of file to write. 

132 :param indent: Indent argument for JsonWriter. 

133 :param walk_filter: Walk filter to use by Walker. 

134 """ 

135 

136 with open(filename, "w", encoding="utf-8") as text_io: 

137 to_json_stream(obj, text_io, indent=indent, walk_filter=walk_filter) 

138 

139 

140def from_json_stream( 

141 obj_class: typing.Type[typing.Any], text_io: typing.TextIO, *arguments: typing.List[typing.Any] 

142) -> typing.Any: 

143 """ 

144 Parses JSON debug string from given text stream and creates instance of the requested zserio object 

145 according to the data contained in the debug string. 

146 

147 .. note:: The created object can be only partially initialized depending on the data stored in the 

148 JSON debug string. 

149 

150 .. code:: python 

151 

152 import io 

153 import zserio 

154 

155 text_io = io.StringIO("{\\\"field1\\\": 13}") 

156 obj = zserio.from_json_stream(SomeZserioObject, text_io) 

157 

158 :param obj_class: Class instance of the generated object to create. 

159 :param text_io: Text stream to use. 

160 :param arguments: Arguments of the generated zserio object. 

161 :returns: Instance of the requested zserio object. 

162 :raises PythonRuntimeException: In case of any error. 

163 """ 

164 

165 json_reader = JsonReader(text_io) 

166 return json_reader.read(obj_class.type_info(), *arguments) 

167 

168 

169def from_json_string( 

170 obj_class: typing.Type[typing.Any], json_string: str, *arguments: typing.List[typing.Any] 

171) -> typing.Any: 

172 """ 

173 Parses JSON debug string and creates instance of the requested zserio object 

174 according to the data contained in the debug string. 

175 

176 .. note:: The created object can be only partially initialized depending on the data stored in the 

177 JSON debug string. 

178 

179 .. code:: python 

180 

181 import zserio 

182 

183 json_string = "{\\\"field1\\\": 13}" 

184 obj = zserio.from_json_string(SomeZserioObject, json_string) 

185 

186 :param obj_class: Class instance of the generated object to create. 

187 :param json_string: JSON debug string to parse. 

188 :param arguments: Arguments of the generated zserio object. 

189 :returns: Instance of the requested zserio object. 

190 :raises PythonRuntimeException: In case of any error. 

191 """ 

192 

193 return from_json_stream(obj_class, io.StringIO(json_string), *arguments) 

194 

195 

196def from_json_file( 

197 obj_class: typing.Type[typing.Any], filename: str, *arguments: typing.List[typing.Any] 

198) -> typing.Any: 

199 """ 

200 Parses JSON debug string from given file and creates instance of the requested zserio object 

201 according to the data contained in the debug string. 

202 

203 .. note:: The created object can be only partially initialized depending on the data stored in the 

204 JSON debug string. 

205 

206 .. code:: python 

207 

208 import zserio 

209 

210 obj = zserio.from_json_file(SomeZserioObject, "file_name.json") 

211 

212 :param obj_class: Class instance of the generated object to create. 

213 :param filename: File name to read. 

214 :param arguments: Arguments of the generated zserio object. 

215 :returns: Instance of the requested zserio object. 

216 :raises PythonRuntimeException: In case of any error. 

217 """ 

218 

219 with open(filename, "r", encoding="utf-8") as text_io: 

220 return from_json_stream(obj_class, text_io, *arguments)