bindings/python/bt2/bt2/field.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23 from bt2 import native_bt, object, utils
  24 import bt2.field_class
  25 import collections.abc
  26 import functools
  27 import numbers
  28 import math
  29 import abc
  30 import bt2
  31
  32
  33 def _get_leaf_field(obj):
  34     if type(obj) is not _VariantField:
  35         return obj
  36
  37     return _get_leaf_field(obj.selected_field)
  38
  39
  40 def _create_field_from_ptr(ptr, owner_ptr, owner_get_ref, owner_put_ref):
  41     field_class_ptr = native_bt.field_borrow_class_const(ptr)
  42     utils._handle_ptr(field_class_ptr, "cannot get field object's class")
  43     typeid = native_bt.field_class_get_type(field_class_ptr)
  44     field = _TYPE_ID_TO_OBJ[typeid]._create_from_ptr_and_get_ref(
  45         ptr, owner_ptr, owner_get_ref, owner_put_ref)
  46     return field
  47
  48
  49 class _Field(object._UniqueObject, metaclass=abc.ABCMeta):
  50     def __copy__(self):
  51         ptr = native_bt.field_copy(self._ptr)
  52         utils._handle_ptr(ptr, 'cannot copy {} field object'.format(self._NAME.lower()))
  53         return _create_from_ptr(ptr)
  54
  55     def __deepcopy__(self, memo):
  56         cpy = self.__copy__()
  57         memo[id(self)] = cpy
  58         return cpy
  59
  60     def __eq__(self, other):
  61         # special case: two unset fields with the same field class are equal
  62         if isinstance(other, _Field):
  63             if not self.is_set or not other.is_set:
  64                 if not self.is_set and not other.is_set and self.field_class == other.field_class:
  65                     return True
  66                 return False
  67
  68         other = _get_leaf_field(other)
  69         return self._spec_eq(other)
  70
  71     @property
  72     def field_class(self):
  73         return self._field_class
  74
  75     @property
  76     def is_set(self):
  77         is_set = native_bt.field_is_set(self._ptr)
  78         return is_set > 0
  79
  80     def reset(self):
  81         ret = native_bt.field_reset(self._ptr)
  82         utils._handle_ret(ret, "cannot reset field object's value")
  83
  84     def _repr(self):
  85         raise NotImplementedError
  86
  87     def __repr__(self):
  88         return self._repr() if self.is_set else 'Unset'
  89
  90
  91 @functools.total_ordering
  92 class _NumericField(_Field):
  93     @staticmethod
  94     def _extract_value(other):
  95         if other is True or other is False:
  96             return other
  97
  98         if isinstance(other, numbers.Integral):
  99             return int(other)
 100
 101         if isinstance(other, numbers.Real):
 102             return float(other)
 103
 104         if isinstance(other, numbers.Complex):
 105             return complex(other)
 106
 107         raise TypeError("'{}' object is not a number object".format(other.__class__.__name__))
 108
 109     def __int__(self):
 110         return int(self._value)
 111
 112     def __float__(self):
 113         return float(self._value)
 114
 115     def _repr(self):
 116         return repr(self._value)
 117
 118     def __lt__(self, other):
 119         if not isinstance(other, numbers.Number):
 120             raise TypeError('unorderable types: {}() < {}()'.format(self.__class__.__name__,
 121                                                                     other.__class__.__name__))
 122
 123         return self._value < float(other)
 124
 125     def __le__(self, other):
 126         if not isinstance(other, numbers.Number):
 127             raise TypeError('unorderable types: {}() <= {}()'.format(self.__class__.__name__,
 128                                                                      other.__class__.__name__))
 129
 130         return self._value <= float(other)
 131
 132     def _spec_eq(self, other):
 133         if not isinstance(other, numbers.Number):
 134             return False
 135
 136         return self._value == complex(other)
 137
 138     def __rmod__(self, other):
 139         return self._extract_value(other) % self._value
 140
 141     def __mod__(self, other):
 142         return self._value % self._extract_value(other)
 143
 144     def __rfloordiv__(self, other):
 145         return self._extract_value(other) // self._value
 146
 147     def __floordiv__(self, other):
 148         return self._value // self._extract_value(other)
 149
 150     def __round__(self, ndigits=None):
 151         if ndigits is None:
 152             return round(self._value)
 153         else:
 154             return round(self._value, ndigits)
 155
 156     def __ceil__(self):
 157         return math.ceil(self._value)
 158
 159     def __floor__(self):
 160         return math.floor(self._value)
 161
 162     def __trunc__(self):
 163         return int(self._value)
 164
 165     def __abs__(self):
 166         return abs(self._value)
 167
 168     def __add__(self, other):
 169         return self._value + self._extract_value(other)
 170
 171     def __radd__(self, other):
 172         return self.__add__(other)
 173
 174     def __neg__(self):
 175         return -self._value
 176
 177     def __pos__(self):
 178         return +self._value
 179
 180     def __mul__(self, other):
 181         return self._value * self._extract_value(other)
 182
 183     def __rmul__(self, other):
 184         return self.__mul__(other)
 185
 186     def __truediv__(self, other):
 187         return self._value / self._extract_value(other)
 188
 189     def __rtruediv__(self, other):
 190         return self._extract_value(other) / self._value
 191
 192     def __pow__(self, exponent):
 193         return self._value ** self._extract_value(exponent)
 194
 195     def __rpow__(self, base):
 196         return self._extract_value(base) ** self._value
 197
 198     def __iadd__(self, other):
 199         self.value = self + other
 200         return self
 201
 202     def __isub__(self, other):
 203         self.value = self - other
 204         return self
 205
 206     def __imul__(self, other):
 207         self.value = self * other
 208         return self
 209
 210     def __itruediv__(self, other):
 211         self.value = self / other
 212         return self
 213
 214     def __ifloordiv__(self, other):
 215         self.value = self // other
 216         return self
 217
 218     def __imod__(self, other):
 219         self.value = self % other
 220         return self
 221
 222     def __ipow__(self, other):
 223         self.value = self ** other
 224         return self
 225
 226
 227 class _IntegralField(_NumericField, numbers.Integral):
 228     def __lshift__(self, other):
 229         return self._value << self._extract_value(other)
 230
 231     def __rlshift__(self, other):
 232         return self._extract_value(other) << self._value
 233
 234     def __rshift__(self, other):
 235         return self._value >> self._extract_value(other)
 236
 237     def __rrshift__(self, other):
 238         return self._extract_value(other) >> self._value
 239
 240     def __and__(self, other):
 241         return self._value & self._extract_value(other)
 242
 243     def __rand__(self, other):
 244         return self._extract_value(other) & self._value
 245
 246     def __xor__(self, other):
 247         return self._value ^ self._extract_value(other)
 248
 249     def __rxor__(self, other):
 250         return self._extract_value(other) ^ self._value
 251
 252     def __or__(self, other):
 253         return self._value | self._extract_value(other)
 254
 255     def __ror__(self, other):
 256         return self._extract_value(other) | self._value
 257
 258     def __invert__(self):
 259         return ~self._value
 260
 261     def __ilshift__(self, other):
 262         self.value = self << other
 263         return self
 264
 265     def __irshift__(self, other):
 266         self.value = self >> other
 267         return self
 268
 269     def __iand__(self, other):
 270         self.value = self & other
 271         return self
 272
 273     def __ixor__(self, other):
 274         self.value = self ^ other
 275         return self
 276
 277     def __ior__(self, other):
 278         self.value = self | other
 279         return self
 280
 281
 282 class _IntegerField(_IntegralField, _Field):
 283     pass
 284
 285
 286 class _UnsignedIntegerField(_IntegerField, _Field):
 287     _NAME = 'Unsigned integer'
 288     def _value_to_int(self, value):
 289         if not isinstance(value, numbers.Real):
 290             raise TypeError('expecting a real number object')
 291
 292         value = int(value)
 293         utils._check_uint64(value)
 294
 295         return value
 296
 297     @property
 298     def _value(self):
 299         return native_bt.field_unsigned_integer_get_value(self._ptr)
 300
 301     def _set_value(self, value):
 302         value = self._value_to_int(value)
 303         native_bt.field_unsigned_integer_set_value(self._ptr, value)
 304
 305     value = property(fset=_set_value)
 306
 307
 308 class _SignedIntegerField(_IntegerField, _Field):
 309     _NAME = 'Signed integer'
 310     def _value_to_int(self, value):
 311         if not isinstance(value, numbers.Real):
 312             raise TypeError('expecting a real number object')
 313
 314         value = int(value)
 315         utils._check_int64(value)
 316
 317         return value
 318
 319     @property
 320     def _value(self):
 321         return native_bt.field_signed_integer_get_value(self._ptr)
 322
 323     def _set_value(self, value):
 324         value = self._value_to_int(value)
 325         native_bt.field_signed_integer_set_value(self._ptr, value)
 326
 327     value = property(fset=_set_value)
 328
 329
 330 class _RealField(_NumericField, numbers.Real):
 331     _NAME = 'Real'
 332
 333     def _value_to_float(self, value):
 334         if not isinstance(value, numbers.Real):
 335             raise TypeError("expecting a real number object")
 336
 337         return float(value)
 338
 339     @property
 340     def _value(self):
 341         return native_bt.field_real_get_value(self._ptr)
 342
 343     def _set_value(self, value):
 344         value = self._value_to_float(value)
 345         native_bt.field_real_set_value(self._ptr, value)
 346
 347     value = property(fset=_set_value)
 348
 349
 350 class _EnumerationField(_IntegerField):
 351     _NAME = 'Enumeration'
 352
 353     @property
 354     def integer_field(self):
 355         int_field_ptr = native_bt.field_enumeration_get_container(self._ptr)
 356         assert(int_field_ptr)
 357         return _create_from_ptr(int_field_ptr)
 358
 359     def _set_value(self, value):
 360         self.integer_field.value = value
 361
 362     def _repr(self):
 363         labels = [repr(v.name) for v in self.mappings]
 364         return '{} ({})'.format(self._value, ', '.join(labels))
 365
 366     value = property(fset=_set_value)
 367
 368     @property
 369     def _value(self):
 370         return self.integer_field._value
 371
 372     @property
 373     def mappings(self):
 374         iter_ptr = native_bt.field_enumeration_get_mappings(self._ptr)
 375         assert(iter_ptr)
 376         return bt2.field_class._EnumerationFieldClassMappingIterator(iter_ptr,
 377                                                                     self.field_class.is_signed)
 378
 379
 380 @functools.total_ordering
 381 class _StringField(_Field, collections.abc.Sequence):
 382     _NAME = 'String'
 383
 384     def _value_to_str(self, value):
 385         if isinstance(value, self.__class__):
 386             value = value._value
 387
 388         if not isinstance(value, str):
 389             raise TypeError("expecting a 'str' object")
 390
 391         return value
 392
 393     @property
 394     def _value(self):
 395         value = native_bt.field_string_get_value(self._ptr)
 396         return value
 397
 398     def _set_value(self, value):
 399         value = self._value_to_str(value)
 400         ret = native_bt.field_string_set_value(self._ptr, value)
 401         utils._handle_ret(ret, "cannot set string field object's value")
 402
 403     value = property(fset=_set_value)
 404
 405     def _spec_eq(self, other):
 406         try:
 407             other = self._value_to_str(other)
 408         except:
 409             return False
 410
 411         return self._value == other
 412
 413     def __le__(self, other):
 414         return self._value <= self._value_to_str(other)
 415
 416     def __lt__(self, other):
 417         return self._value < self._value_to_str(other)
 418
 419     def __bool__(self):
 420         return bool(self._value)
 421
 422     def _repr(self):
 423         return repr(self._value)
 424
 425     def __str__(self):
 426         return self._value if self.is_set else repr(self)
 427
 428     def __getitem__(self, index):
 429         return self._value[index]
 430
 431     def __len__(self):
 432         return len(self._value)
 433
 434     def __iadd__(self, value):
 435         value = self._value_to_str(value)
 436         ret = native_bt.field_string_append(self._ptr, value)
 437         utils._handle_ret(ret, "cannot append to string field object's value")
 438         return self
 439
 440
 441 class _ContainerField(_Field):
 442     def __bool__(self):
 443         return len(self) != 0
 444
 445     def __len__(self):
 446         count = self._count()
 447         assert(count >= 0)
 448         return count
 449
 450     def __delitem__(self, index):
 451         raise NotImplementedError
 452
 453
 454 class _StructureField(_ContainerField, collections.abc.MutableMapping):
 455     _NAME = 'Structure'
 456
 457     def _count(self):
 458         return len(self.field_class)
 459
 460     def __getitem__(self, key):
 461         utils._check_str(key)
 462         field_ptr = native_bt.field_structure_borrow_member_field_by_name(self._ptr, key)
 463
 464         if field_ptr is None:
 465             raise KeyError(key)
 466
 467         return _create_field_from_ptr(field_ptr, self._owner_ptr,
 468                                       self._owner_get_ref,
 469                                       self._owner_put_ref)
 470
 471     def __setitem__(self, key, value):
 472         # raises if key is somehow invalid
 473         field = self[key]
 474
 475         # the field's property does the appropriate conversion or raises
 476         # the appropriate exception
 477         field.value = value
 478
 479     def at_index(self, index):
 480         utils._check_uint64(index)
 481
 482         if index >= len(self):
 483             raise IndexError
 484
 485         field_ptr = native_bt.field_structure_get_field_by_index(self._ptr, index)
 486         assert(field_ptr)
 487         return _create_from_ptr(field_ptr)
 488
 489     def __iter__(self):
 490         # same name iterator
 491         return iter(self.field_class)
 492
 493     def _spec_eq(self, other):
 494         try:
 495             if len(self) != len(other):
 496                 return False
 497
 498             for self_key, self_value in self.items():
 499                 if self_key not in other:
 500                     return False
 501
 502                 other_value = other[self_key]
 503
 504                 if self_value != other_value:
 505                     return False
 506
 507             return True
 508         except:
 509             return False
 510
 511     @property
 512     def _value(self):
 513         return {key: value._value for key, value in self.items()}
 514
 515     def _set_value(self, values):
 516         original_values = self._value
 517
 518         try:
 519             for key, value in values.items():
 520                 self[key].value = value
 521         except:
 522             self.value = original_values
 523             raise
 524
 525     value = property(fset=_set_value)
 526
 527     def _repr(self):
 528         items = ['{}: {}'.format(repr(k), repr(v)) for k, v in self.items()]
 529         return '{{{}}}'.format(', '.join(items))
 530
 531
 532 class _VariantField(_Field):
 533     _NAME = 'Variant'
 534
 535     @property
 536     def tag_field(self):
 537         field_ptr = native_bt.field_variant_get_tag(self._ptr)
 538
 539         if field_ptr is None:
 540             return
 541
 542         return _create_from_ptr(field_ptr)
 543
 544     @property
 545     def selected_field(self):
 546         return self.field()
 547
 548     def field(self, tag_field=None):
 549         if tag_field is None:
 550             field_ptr = native_bt.field_variant_get_current_field(self._ptr)
 551
 552             if field_ptr is None:
 553                 return
 554         else:
 555             utils._check_type(tag_field, _EnumerationField)
 556             field_ptr = native_bt.field_variant_get_field(self._ptr, tag_field._ptr)
 557             utils._handle_ptr(field_ptr, "cannot select variant field object's field")
 558
 559         return _create_from_ptr(field_ptr)
 560
 561     def _spec_eq(self, other):
 562         return _get_leaf_field(self) == other
 563
 564     def __bool__(self):
 565         return bool(self.selected_field)
 566
 567     def __str__(self):
 568         return str(self.selected_field) if self.is_set else repr(self)
 569
 570     def _repr(self):
 571         return repr(self.selected_field)
 572
 573     @property
 574     def _value(self):
 575         if self.selected_field is not None:
 576             return self.selected_field._value
 577
 578     def _set_value(self, value):
 579         self.selected_field.value = value
 580
 581     value = property(fset=_set_value)
 582
 583
 584 class _ArraySequenceField(_ContainerField, collections.abc.MutableSequence):
 585     def __getitem__(self, index):
 586         if not isinstance(index, numbers.Integral):
 587             raise TypeError("'{}' is not an integral number object: invalid index".format(index.__class__.__name__))
 588
 589         index = int(index)
 590
 591         if index < 0 or index >= len(self):
 592             raise IndexError('{} field object index is out of range'.format(self._NAME))
 593
 594         field_ptr = self._get_field_ptr_at_index(index)
 595         assert(field_ptr)
 596         return _create_from_ptr(field_ptr)
 597
 598     def __setitem__(self, index, value):
 599         # we can only set numbers and strings
 600         if not isinstance(value, (numbers.Number, _StringField, str)):
 601             raise TypeError('expecting number or string object')
 602
 603         # raises if index is somehow invalid
 604         field = self[index]
 605
 606         if not isinstance(field, (_NumericField, _StringField)):
 607             raise TypeError('can only set the value of a number or string field')
 608
 609         # the field's property does the appropriate conversion or raises
 610         # the appropriate exception
 611         field.value = value
 612
 613     def insert(self, index, value):
 614         raise NotImplementedError
 615
 616     def _spec_eq(self, other):
 617         try:
 618             if len(self) != len(other):
 619                 return False
 620
 621             for self_field, other_field in zip(self, other):
 622                 if self_field != other_field:
 623                     return False
 624
 625             return True
 626         except:
 627             return False
 628
 629     @property
 630     def _value(self):
 631         return [field._value for field in self]
 632
 633     def _repr(self):
 634         return '[{}]'.format(', '.join([repr(v) for v in self]))
 635
 636
 637 class _ArrayField(_ArraySequenceField):
 638     _NAME = 'Array'
 639
 640     def _count(self):
 641         return self.field_class.length
 642
 643     def _get_field_ptr_at_index(self, index):
 644         return native_bt.field_array_get_field(self._ptr, index)
 645
 646     def _set_value(self, values):
 647         if len(self) != len(values):
 648             raise ValueError(
 649                 'expected length of value and array field to match')
 650
 651         original_values = self._value
 652         try:
 653             for index, value in enumerate(values):
 654                 if value is not None:
 655                     self[index].value = value
 656                 else:
 657                     self[index].reset()
 658         except:
 659             self.value = original_values
 660             raise
 661
 662     value = property(fset=_set_value)
 663
 664
 665 class _SequenceField(_ArraySequenceField):
 666     _NAME = 'Sequence'
 667
 668     def _count(self):
 669         return int(self.length_field)
 670
 671     @property
 672     def length_field(self):
 673         field_ptr = native_bt.field_sequence_get_length(self._ptr)
 674         if field_ptr is None:
 675             return
 676         return _create_from_ptr(field_ptr)
 677
 678     @length_field.setter
 679     def length_field(self, length_field):
 680         utils._check_type(length_field, _IntegerField)
 681         ret = native_bt.field_sequence_set_length(self._ptr, length_field._ptr)
 682         utils._handle_ret(ret, "cannot set sequence field object's length field")
 683
 684     def _get_field_ptr_at_index(self, index):
 685         return native_bt.field_sequence_get_field(self._ptr, index)
 686
 687     def _set_value(self, values):
 688         original_length_field = self.length_field
 689         if original_length_field is not None:
 690             original_values = self._value
 691
 692         if len(values) != self.length_field:
 693             if self.length_field is not None:
 694                 length_fc = self.length_field.field_class
 695             else:
 696                 length_fc = bt2.IntegerFieldClass(size=64, is_signed=False)
 697             self.length_field = length_fc(len(values))
 698
 699         try:
 700             for index, value in enumerate(values):
 701                 if value is not None:
 702                     self[index].value = value
 703                 else:
 704                     self[index].reset()
 705         except:
 706             if original_length_field is not None:
 707                 self.length_field = original_length_field
 708                 self.value = original_values
 709             else:
 710                 self.reset()
 711             raise
 712
 713     value = property(fset=_set_value)
 714
 715
 716 _TYPE_ID_TO_OBJ = {
 717     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerField,
 718     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerField,
 719     native_bt.FIELD_CLASS_TYPE_REAL: _RealField,
 720     native_bt.FIELD_CLASS_TYPE_STRING: _StringField,
 721     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureField,
 722 }