Debian Codegraph @

pamqp/encode.py

raw
1 """
2 Functions for encoding data of various types including field tables and arrays
3
4 """
5
6 import calendar
7 import collections.abc
8 import datetime
9 import decimal as _decimal
10 import logging
11 import struct
12 import time
13
14 from pamqp import common
15
16 LOGGER = logging.getLogger(__name__)
17
18 DEPRECATED_RABBITMQ_SUPPORT = False
19 """Toggle to support older versions of RabbitMQ."""
20
21
22 def support_deprecated_rabbitmq(enabled: bool = True) -> None:
23 """Toggle the data types available in field-tables
24
25 If called with `True`, than RabbitMQ versions, the field-table integer
26 types will not support the full AMQP spec.
27
28 :param enabled: Specify if deprecated RabbitMQ versions are supported
29
30 """
31 global DEPRECATED_RABBITMQ_SUPPORT
32
33 DEPRECATED_RABBITMQ_SUPPORT = enabled
34
35
36 def by_type(value: common.FieldValue, data_type: str) -> bytes:
37 """Takes a value of any type and tries to encode it with the specified
38 encoder.
39
40 :param value: The value to encode
41 :type value: :const:`pamqp.common.FieldValue`
42 :param data_type: The data type name to use for encoding
43 :raises TypeError: when the :data:`data_type` is unknown
44
45 """
46 try:
47 return METHODS[str(data_type)](value)
48 except KeyError as err:
49 raise TypeError(f'Unknown type: {data_type}') from err
50
51
52 def bit(value: int, byte: int, position: int) -> int:
53 """Encode a bit value
54
55 :param value: Value to encode
56 :param byte: The byte to apply the value to
57 :param position: The position in the byte to set the bit on
58
59 """
60 return byte | (value << position)
61
62
63 def boolean(value: bool) -> bytes:
64 """Encode a boolean value
65
66 :param value: Value to encode
67 :raises TypeError: when the value is not the correct type
68
69 """
70 if not isinstance(value, bool):
71 raise TypeError(f'bool required, received {type(value)}')
72 return common.Struct.short_short_uint.pack(int(value))
73
74
75 def byte_array(value: bytearray) -> bytes:
76 """Encode a byte array value
77
78 :param value: Value to encode
79 :raises TypeError: when the value is not the correct type
80
81 """
82 if not isinstance(value, bytearray):
83 raise TypeError(f'bytearray required, received {type(value)}')
84 return common.Struct.integer.pack(len(value)) + value
85
86
87 def decimal(value: _decimal.Decimal) -> bytes:
88 """Encode a decimal.Decimal value
89
90 :param value: Value to encode
91 :raises TypeError: when the value is not the correct type
92
93 """
94 if not isinstance(value, _decimal.Decimal):
95 raise TypeError(f'decimal.Decimal required, received {type(value)}')
96 tmp = str(value)
97 if '.' in tmp:
98 decimals = len(tmp.split('.')[-1])
99 value = value.normalize()
100 raw = int(value * (_decimal.Decimal(10) ** decimals))
101 return struct.pack('>Bi', decimals, raw)
102 return struct.pack('>Bi', 0, int(value))
103
104
105 def double(value: float) -> bytes:
106 """Encode a floating point value as a double
107
108 :param value: Value to encode
109 :raises TypeError: when the value is not the correct type
110
111 """
112 if not isinstance(value, float):
113 raise TypeError(f'float required, received {type(value)}')
114 return common.Struct.double.pack(value)
115
116
117 def floating_point(value: float) -> bytes:
118 """Encode a floating point value
119
120 :param value: Value to encode
121 :raises TypeError: when the value is not the correct type
122
123 """
124 if not isinstance(value, float):
125 raise TypeError(f'float required, received {type(value)}')
126 return common.Struct.float.pack(value)
127
128
129 def long_int(value: int) -> bytes:
130 """Encode a long integer
131
132 :param value: Value to encode
133 :raises TypeError: when the value is not the correct type or outside the
134 acceptable range for the data type
135
136 """
137 if not isinstance(value, int):
138 raise TypeError(f'int required, received {type(value)}')
139 elif not (-2147483648 <= value <= 2147483647):
140 raise TypeError('Long integer range: -2147483648 to 2147483647')
141 return common.Struct.long.pack(value)
142
143
144 def long_uint(value: int) -> bytes:
145 """Encode a long unsigned integer
146
147 :param value: Value to encode
148 :raises TypeError: when the value is not the correct type or outside the
149 acceptable range for the data type
150
151 """
152 if not isinstance(value, int):
153 raise TypeError(f'int required, received {type(value)}')
154 elif not (0 <= value <= 4294967295):
155 raise TypeError('Long unsigned-integer range: 0 to 4294967295')
156 return common.Struct.ulong.pack(value)
157
158
159 def long_long_int(value: int) -> bytes:
160 """Encode a long-long int
161
162 :param value: Value to encode
163 :raises TypeError: when the value is not the correct type or outside the
164 acceptable range for the data type
165
166 """
167 if not isinstance(value, int):
168 raise TypeError(f'int required, received {type(value)}')
169 elif not (-9223372036854775808 <= value <= 9223372036854775807):
170 raise TypeError(
171 'long-long integer range: '
172 '-9223372036854775808 to 9223372036854775807'
173 )
174 return common.Struct.long_long_int.pack(value)
175
176
177 def long_string(value: str) -> bytes:
178 """Encode a "long string"
179
180 :param value: Value to encode
181 :raises TypeError: when the value is not the correct type
182
183 """
184 return _string(common.Struct.integer, value)
185
186
187 def octet(value: int) -> bytes:
188 """Encode an octet value
189
190 :param value: Value to encode
191 :raises TypeError: when the value is not the correct type
192
193 """
194 if not isinstance(value, int):
195 raise TypeError(f'int required, received {type(value)}')
196 return common.Struct.byte.pack(value)
197
198
199 def short_int(value: int) -> bytes:
200 """Encode a short integer
201
202 :param value: Value to encode
203 :raises TypeError: when the value is not the correct type or outside the
204 acceptable range for the data type
205
206 """
207 if not isinstance(value, int):
208 raise TypeError(f'int required, received {type(value)}')
209 elif not (-32768 <= value <= 32767):
210 raise TypeError('Short integer range: -32678 to 32767')
211 return common.Struct.short.pack(value)
212
213
214 def short_uint(value: int) -> bytes:
215 """Encode an unsigned short integer
216
217 :param value: Value to encode
218 :raises TypeError: when the value is not the correct type or outside the
219 acceptable range for the data type
220
221 """
222 if not isinstance(value, int):
223 raise TypeError(f'int required, received {type(value)}')
224 elif not (0 <= value <= 65535):
225 raise TypeError('Short unsigned integer range: 0 to 65535')
226 return common.Struct.ushort.pack(value)
227
228
229 def short_string(value: str) -> bytes:
230 """Encode a string
231
232 :param value: Value to encode
233 :raises TypeError: when the value is not the correct type
234
235 """
236 return _string(common.Struct.byte, value)
237
238
239 def timestamp(
240 value: datetime.datetime | time.struct_time,
241 ) -> bytes:
242 """Encode a datetime.datetime object or time.struct_time
243
244 :param value: Value to encode
245 :raises TypeError: when the value is not the correct type
246
247 """
248 if isinstance(value, datetime.datetime):
249 if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
250 # assume datetime object is UTC
251 value = value.replace(tzinfo=datetime.UTC)
252 return common.Struct.timestamp.pack(int(value.timestamp()))
253 if isinstance(value, time.struct_time):
254 return common.Struct.timestamp.pack(calendar.timegm(value))
255 raise TypeError(
256 f'datetime.datetime or time.struct_time required, received {type(value)}'
257 )
258
259
260 def field_array(value: common.FieldArray) -> bytes:
261 """Encode a field array from a list of values
262
263 :param value: Value to encode
264 :type value: :const:`pamqp.common.FieldArray`
265 :raises TypeError: when the value is not the correct type
266
267 """
268 if not isinstance(value, list):
269 raise TypeError(f'list of values required, received {type(value)}')
270 data = []
271 for item in value:
272 data.append(encode_table_value(item))
273 output = b''.join(data)
274 return common.Struct.integer.pack(len(output)) + output
275
276
277 def field_table(value: common.FieldTable) -> bytes:
278 """Encode a field table from a dict
279
280 :param value: Value to encode
281 :type value: :const:`pamqp.common.FieldTable`
282 :raises TypeError: when the value is not the correct type
283
284 """
285 if not value: # If there is no value, return a standard 4 null bytes
286 return common.Struct.integer.pack(0)
287 elif not isinstance(value, dict):
288 raise TypeError(f'dict required, received {type(value)}')
289 data = []
290 for key, item in sorted(value.items()):
291 if len(key) > 128: # field names have 128 char max
292 LOGGER.warning('Truncating key %s to 128 bytes', key)
293 key = key[0:128]
294 data.append(short_string(key))
295 try:
296 data.append(encode_table_value(item))
297 except TypeError as err:
298 raise TypeError(f'{key} error: {err}') from err
299 output = b''.join(data)
300 return common.Struct.integer.pack(len(output)) + output
301
302
303 def table_integer(value: int) -> bytes:
304 """Determines the best type of numeric type to encode value as, preferring
305 the smallest data size first.
306
307 :param value: Value to encode
308 :raises TypeError: when the value is not the correct type or outside the
309 acceptable range for the data type
310
311 """
312 if DEPRECATED_RABBITMQ_SUPPORT:
313 return _deprecated_table_integer(value)
314 if -128 <= value <= 127:
315 return b'b' + common.Struct.short_short_int.pack(value)
316 elif -32768 <= value <= 32767:
317 return b's' + short_int(value)
318 elif 0 <= value <= 65535:
319 return b'u' + short_uint(value)
320 elif -2147483648 <= value <= 2147483647:
321 return b'I' + long_int(value)
322 elif 0 <= value <= 4294967295:
323 return b'i' + long_uint(value)
324 elif -9223372036854775808 <= value <= 9223372036854775807:
325 return b'l' + long_long_int(value)
326 raise TypeError(f'Unsupported numeric value: {value}')
327
328
329 def _deprecated_table_integer(value: int) -> bytes:
330 """Determines the best type of numeric type to encode value as, preferring
331 the smallest data size first, supporting versions of RabbitMQ < 3.6
332
333 :param value: Value to encode
334 :raises TypeError: when the value is not the correct type or outside the
335 acceptable range for the data type
336
337 """
338 if -128 <= value <= 127:
339 return b'b' + common.Struct.short_short_int.pack(value)
340 elif -32768 <= value <= 32767:
341 return b's' + short_int(value)
342 elif -2147483648 <= value <= 2147483647:
343 return b'I' + long_int(value)
344 elif -9223372036854775808 <= value <= 9223372036854775807:
345 return b'l' + long_long_int(value)
346 raise TypeError(f'Unsupported numeric value: {value}')
347
348
349 def _string(encoder: struct.Struct, value: str) -> bytes:
350 """Reduce a small amount of duplication in string handling
351
352 :raises: TypeError
353
354 """
355 if not isinstance(value, str):
356 raise TypeError(f'str required, received {type(value)}')
357 temp = value.encode('utf-8')
358 return encoder.pack(len(temp)) + temp
359
360
361 def encode_table_value(
362 value: common.FieldArray | common.FieldTable | common.FieldValue,
363 ) -> bytes:
364 """Takes a value of any type and tries to encode it with the proper encoder
365
366 :param value: Value to encode
367 :type value: :const:`pamqp.common.FieldArray` or
368 :const:`pamqp.common.FieldTable` or
369 :const:`pamqp.common.FieldValue`
370 :raises TypeError: when the type of the value is not supported
371
372 """
373 if isinstance(value, bool):
374 return b't' + boolean(value)
375 elif isinstance(value, int):
376 return table_integer(value)
377 elif isinstance(value, _decimal.Decimal):
378 return b'D' + decimal(value)
379 elif isinstance(value, float):
380 return b'f' + floating_point(value)
381 elif isinstance(value, str):
382 return b'S' + long_string(value)
383 elif isinstance(value, (datetime.datetime, time.struct_time)):
384 return b'T' + timestamp(value)
385 elif isinstance(value, dict):
386 return b'F' + field_table(value)
387 elif isinstance(value, list):
388 return b'A' + field_array(value)
389 elif isinstance(value, bytearray):
390 return b'x' + byte_array(value)
391 elif value is None:
392 return b'V'
393 raise TypeError(f'Unknown type: {type(value)} ({value!r})')
394
395
396 METHODS: dict[str, collections.abc.Callable[..., bytes]] = {
397 'bytearray': byte_array,
398 'double': double,
399 'field_array': field_array,
400 'long': long_uint,
401 'longlong': long_long_int,
402 'longstr': long_string,
403 'octet': octet,
404 'short': short_uint,
405 'shortstr': short_string,
406 'table': field_table,
407 'timestamp': timestamp,
408 'void': lambda _: b'',
409 }