src/bindings/python/bt2/bt2/field_class.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 collections.abc
  25 from bt2 import field_path as bt2_field_path
  26 from bt2 import integer_range_set as bt2_integer_range_set
  27 import bt2
  28
  29
  30 def _create_field_class_from_ptr_and_get_ref(ptr):
  31     typeid = native_bt.field_class_get_type(ptr)
  32     return _FIELD_CLASS_TYPE_TO_OBJ[typeid]._create_from_ptr_and_get_ref(ptr)
  33
  34
  35 class IntegerDisplayBase:
  36     BINARY = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
  37     OCTAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
  38     DECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
  39     HEXADECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
  40
  41
  42 class _FieldClass(object._SharedObject):
  43     _get_ref = staticmethod(native_bt.field_class_get_ref)
  44     _put_ref = staticmethod(native_bt.field_class_put_ref)
  45
  46     def _check_create_status(self, ptr):
  47         if ptr is None:
  48             raise bt2._MemoryError(
  49                 'cannot create {} field class object'.format(self._NAME.lower())
  50             )
  51
  52
  53 class _IntegerFieldClass(_FieldClass):
  54     @property
  55     def field_value_range(self):
  56         size = native_bt.field_class_integer_get_field_value_range(self._ptr)
  57         assert size >= 1
  58         return size
  59
  60     def _field_value_range(self, size):
  61         if size < 1 or size > 64:
  62             raise ValueError("Value is outside valid range [1, 64] ({})".format(size))
  63         native_bt.field_class_integer_set_field_value_range(self._ptr, size)
  64
  65     _field_value_range = property(fset=_field_value_range)
  66
  67     @property
  68     def preferred_display_base(self):
  69         base = native_bt.field_class_integer_get_preferred_display_base(self._ptr)
  70         assert base >= 0
  71         return base
  72
  73     def _preferred_display_base(self, base):
  74         utils._check_uint64(base)
  75
  76         if base not in (
  77             IntegerDisplayBase.BINARY,
  78             IntegerDisplayBase.OCTAL,
  79             IntegerDisplayBase.DECIMAL,
  80             IntegerDisplayBase.HEXADECIMAL,
  81         ):
  82             raise ValueError("Display base is not a valid IntegerDisplayBase value")
  83
  84         native_bt.field_class_integer_set_preferred_display_base(self._ptr, base)
  85
  86     _preferred_display_base = property(fset=_preferred_display_base)
  87
  88
  89 class _UnsignedIntegerFieldClass(_IntegerFieldClass):
  90     _NAME = 'Unsigned integer'
  91
  92
  93 class _SignedIntegerFieldClass(_IntegerFieldClass):
  94     _NAME = 'Signed integer'
  95
  96
  97 class _RealFieldClass(_FieldClass):
  98     _NAME = 'Real'
  99
 100     @property
 101     def is_single_precision(self):
 102         return native_bt.field_class_real_is_single_precision(self._ptr)
 103
 104     def _is_single_precision(self, is_single_precision):
 105         utils._check_bool(is_single_precision)
 106         native_bt.field_class_real_set_is_single_precision(
 107             self._ptr, is_single_precision
 108         )
 109
 110     _is_single_precision = property(fset=_is_single_precision)
 111
 112
 113 # an enumeration field class mapping does not have a reference count, so
 114 # we copy the properties here to avoid eventual memory access errors.
 115 class _EnumerationFieldClassMapping:
 116     def __init__(self, mapping_ptr):
 117         base_mapping_ptr = self._as_enumeration_field_class_mapping_ptr(mapping_ptr)
 118         self._label = native_bt.field_class_enumeration_mapping_get_label(
 119             base_mapping_ptr
 120         )
 121         assert self._label is not None
 122         ranges_ptr = self._mapping_borrow_ranges_ptr(mapping_ptr)
 123         assert ranges_ptr is not None
 124         self._ranges = self._ranges_type._create_from_ptr_and_get_ref(ranges_ptr)
 125
 126     @property
 127     def label(self):
 128         return self._label
 129
 130     @property
 131     def ranges(self):
 132         return self._ranges
 133
 134
 135 class _UnsignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 136     _ranges_type = bt2_integer_range_set.UnsignedIntegerRangeSet
 137     _as_enumeration_field_class_mapping_ptr = staticmethod(
 138         native_bt.field_class_enumeration_unsigned_mapping_as_mapping_const
 139     )
 140     _mapping_borrow_ranges_ptr = staticmethod(
 141         native_bt.field_class_enumeration_unsigned_mapping_borrow_ranges_const
 142     )
 143
 144
 145 class _SignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 146     _ranges_type = bt2_integer_range_set.SignedIntegerRangeSet
 147     _as_enumeration_field_class_mapping_ptr = staticmethod(
 148         native_bt.field_class_enumeration_signed_mapping_as_mapping_const
 149     )
 150     _mapping_borrow_ranges_ptr = staticmethod(
 151         native_bt.field_class_enumeration_signed_mapping_borrow_ranges_const
 152     )
 153
 154
 155 class _EnumerationFieldClass(_IntegerFieldClass, collections.abc.Mapping):
 156     def __len__(self):
 157         count = native_bt.field_class_enumeration_get_mapping_count(self._ptr)
 158         assert count >= 0
 159         return count
 160
 161     def add_mapping(self, label, ranges):
 162         utils._check_str(label)
 163         utils._check_type(ranges, self._range_set_type)
 164
 165         if label in self:
 166             raise ValueError("duplicate mapping label '{}'".format(label))
 167
 168         status = self._add_mapping(self._ptr, label, ranges._ptr)
 169         utils._handle_func_status(
 170             status, 'cannot add mapping to enumeration field class object'
 171         )
 172
 173     def mappings_for_value(self, value):
 174         status, labels = self._get_mapping_labels_for_value(self._ptr, value)
 175         utils._handle_func_status(
 176             status, 'cannot get mapping labels for value {}'.format(value)
 177         )
 178         return [self[label] for label in labels]
 179
 180     def __iter__(self):
 181         for idx in range(len(self)):
 182             mapping = self._get_mapping_by_index(self._ptr, idx)
 183             yield mapping.label
 184
 185     def __getitem__(self, label):
 186         utils._check_str(label)
 187         mapping = self._get_mapping_by_label(self._ptr, label)
 188
 189         if mapping is None:
 190             raise KeyError(label)
 191
 192         return mapping
 193
 194     def __iadd__(self, mappings):
 195         for label, ranges in mappings:
 196             self.add_mapping(label, ranges)
 197
 198         return self
 199
 200
 201 class _UnsignedEnumerationFieldClass(
 202     _EnumerationFieldClass, _UnsignedIntegerFieldClass
 203 ):
 204     _NAME = 'Unsigned enumeration'
 205     _range_set_type = bt2_integer_range_set.UnsignedIntegerRangeSet
 206     _add_mapping = staticmethod(native_bt.field_class_enumeration_unsigned_add_mapping)
 207
 208     @staticmethod
 209     def _get_mapping_by_index(enum_ptr, index):
 210         mapping_ptr = native_bt.field_class_enumeration_unsigned_borrow_mapping_by_index_const(
 211             enum_ptr, index
 212         )
 213         assert mapping_ptr is not None
 214         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 215
 216     @staticmethod
 217     def _get_mapping_by_label(enum_ptr, label):
 218         mapping_ptr = native_bt.field_class_enumeration_unsigned_borrow_mapping_by_label_const(
 219             enum_ptr, label
 220         )
 221
 222         if mapping_ptr is None:
 223             return
 224
 225         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 226
 227     @staticmethod
 228     def _get_mapping_labels_for_value(enum_ptr, value):
 229         utils._check_uint64(value)
 230         return native_bt.field_class_enumeration_unsigned_get_mapping_labels_for_value(
 231             enum_ptr, value
 232         )
 233
 234
 235 class _SignedEnumerationFieldClass(_EnumerationFieldClass, _SignedIntegerFieldClass):
 236     _NAME = 'Signed enumeration'
 237     _range_set_type = bt2_integer_range_set.SignedIntegerRangeSet
 238     _add_mapping = staticmethod(native_bt.field_class_enumeration_signed_add_mapping)
 239
 240     @staticmethod
 241     def _get_mapping_by_index(enum_ptr, index):
 242         mapping_ptr = native_bt.field_class_enumeration_signed_borrow_mapping_by_index_const(
 243             enum_ptr, index
 244         )
 245         assert mapping_ptr is not None
 246         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 247
 248     @staticmethod
 249     def _get_mapping_by_label(enum_ptr, label):
 250         mapping_ptr = native_bt.field_class_enumeration_signed_borrow_mapping_by_label_const(
 251             enum_ptr, label
 252         )
 253
 254         if mapping_ptr is None:
 255             return
 256
 257         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 258
 259     @staticmethod
 260     def _get_mapping_labels_for_value(enum_ptr, value):
 261         utils._check_int64(value)
 262         return native_bt.field_class_enumeration_signed_get_mapping_labels_for_value(
 263             enum_ptr, value
 264         )
 265
 266
 267 class _StringFieldClass(_FieldClass):
 268     _NAME = 'String'
 269
 270
 271 class _StructureFieldClassMember:
 272     def __init__(self, name, field_class):
 273         self._name = name
 274         self._field_class = field_class
 275
 276     @property
 277     def name(self):
 278         return self._name
 279
 280     @property
 281     def field_class(self):
 282         return self._field_class
 283
 284
 285 class _StructureFieldClass(_FieldClass, collections.abc.Mapping):
 286     _NAME = 'Structure'
 287
 288     def append_member(self, name, field_class):
 289         utils._check_str(name)
 290         utils._check_type(field_class, _FieldClass)
 291
 292         if name in self:
 293             raise ValueError("duplicate member name '{}'".format(name))
 294
 295         status = native_bt.field_class_structure_append_member(
 296             self._ptr, name, field_class._ptr
 297         )
 298         utils._handle_func_status(
 299             status, 'cannot append member to structure field class object'
 300         )
 301
 302     def __len__(self):
 303         count = native_bt.field_class_structure_get_member_count(self._ptr)
 304         assert count >= 0
 305         return count
 306
 307     @staticmethod
 308     def _create_member_from_ptr(member_ptr):
 309         name = native_bt.field_class_structure_member_get_name(member_ptr)
 310         assert name is not None
 311         fc_ptr = native_bt.field_class_structure_member_borrow_field_class_const(
 312             member_ptr
 313         )
 314         assert fc_ptr is not None
 315         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 316         return _StructureFieldClassMember(name, fc)
 317
 318     def __getitem__(self, key):
 319         if not isinstance(key, str):
 320             raise TypeError(
 321                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 322             )
 323
 324         member_ptr = native_bt.field_class_structure_borrow_member_by_name_const(
 325             self._ptr, key
 326         )
 327
 328         if member_ptr is None:
 329             raise KeyError(key)
 330
 331         return self._create_member_from_ptr(member_ptr)
 332
 333     def __iter__(self):
 334         for idx in range(len(self)):
 335             member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(
 336                 self._ptr, idx
 337             )
 338             assert member_ptr is not None
 339             yield native_bt.field_class_structure_member_get_name(member_ptr)
 340
 341     def __iadd__(self, members):
 342         for name, field_class in members:
 343             self.append_member(name, field_class)
 344
 345         return self
 346
 347     def member_at_index(self, index):
 348         utils._check_uint64(index)
 349
 350         if index >= len(self):
 351             raise IndexError
 352
 353         member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(
 354             self._ptr, index
 355         )
 356         assert member_ptr is not None
 357         return self._create_member_from_ptr(member_ptr)
 358
 359
 360 class _VariantFieldClassOption:
 361     def __init__(self, name, field_class):
 362         self._name = name
 363         self._field_class = field_class
 364
 365     @property
 366     def name(self):
 367         return self._name
 368
 369     @property
 370     def field_class(self):
 371         return self._field_class
 372
 373
 374 class _VariantFieldClassWithSelectorOption(_VariantFieldClassOption):
 375     def __init__(self, name, field_class, ranges):
 376         super().__init__(name, field_class)
 377         self._ranges = ranges
 378
 379     @property
 380     def ranges(self):
 381         return self._ranges
 382
 383
 384 class _VariantFieldClass(_FieldClass, collections.abc.Mapping):
 385     _NAME = 'Variant'
 386     _borrow_option_by_name_ptr = staticmethod(
 387         native_bt.field_class_variant_borrow_option_by_name_const
 388     )
 389     _borrow_member_by_index_ptr = staticmethod(
 390         native_bt.field_class_variant_borrow_option_by_index_const
 391     )
 392
 393     @staticmethod
 394     def _as_option_ptr(opt_ptr):
 395         return opt_ptr
 396
 397     def _create_option_from_ptr(self, opt_ptr):
 398         name = native_bt.field_class_variant_option_get_name(opt_ptr)
 399         assert name is not None
 400         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(opt_ptr)
 401         assert fc_ptr is not None
 402         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 403         return _VariantFieldClassOption(name, fc)
 404
 405     def __len__(self):
 406         count = native_bt.field_class_variant_get_option_count(self._ptr)
 407         assert count >= 0
 408         return count
 409
 410     def __getitem__(self, key):
 411         if not isinstance(key, str):
 412             raise TypeError(
 413                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 414             )
 415
 416         opt_ptr = self._borrow_option_by_name_ptr(self._ptr, key)
 417
 418         if opt_ptr is None:
 419             raise KeyError(key)
 420
 421         return self._create_option_from_ptr(opt_ptr)
 422
 423     def __iter__(self):
 424         for idx in range(len(self)):
 425             opt_ptr = self._borrow_member_by_index_ptr(self._ptr, idx)
 426             assert opt_ptr is not None
 427             base_opt_ptr = self._as_option_ptr(opt_ptr)
 428             yield native_bt.field_class_variant_option_get_name(base_opt_ptr)
 429
 430     def option_at_index(self, index):
 431         utils._check_uint64(index)
 432
 433         if index >= len(self):
 434             raise IndexError
 435
 436         opt_ptr = self._borrow_member_by_index_ptr(self._ptr, index)
 437         assert opt_ptr is not None
 438         return self._create_option_from_ptr(opt_ptr)
 439
 440
 441 class _VariantFieldClassWithoutSelector(_VariantFieldClass):
 442     _NAME = 'Variant (without selector)'
 443
 444     def append_option(self, name, field_class):
 445         utils._check_str(name)
 446         utils._check_type(field_class, _FieldClass)
 447
 448         if name in self:
 449             raise ValueError("duplicate option name '{}'".format(name))
 450
 451         status = native_bt.field_class_variant_without_selector_append_option(
 452             self._ptr, name, field_class._ptr
 453         )
 454         utils._handle_func_status(
 455             status, 'cannot append option to variant field class object'
 456         )
 457
 458     def __iadd__(self, options):
 459         for name, field_class in options:
 460             self.append_option(name, field_class)
 461
 462         return self
 463
 464
 465 class _VariantFieldClassWithSelector(_VariantFieldClass):
 466     _NAME = 'Variant (with selector)'
 467
 468     def _create_option_from_ptr(self, opt_ptr):
 469         base_opt_ptr = self._as_option_ptr(opt_ptr)
 470         name = native_bt.field_class_variant_option_get_name(base_opt_ptr)
 471         assert name is not None
 472         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(
 473             base_opt_ptr
 474         )
 475         assert fc_ptr is not None
 476         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 477         range_set_ptr = self._option_borrow_ranges_ptr(opt_ptr)
 478         assert range_set_ptr is not None
 479         range_set = self._range_set_type._create_from_ptr_and_get_ref(range_set_ptr)
 480         return _VariantFieldClassWithSelectorOption(name, fc, range_set)
 481
 482     @property
 483     def selector_field_path(self):
 484         ptr = native_bt.field_class_variant_with_selector_borrow_selector_field_path_const(
 485             self._ptr
 486         )
 487
 488         if ptr is None:
 489             return
 490
 491         return bt2_field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 492
 493     def append_option(self, name, field_class, ranges):
 494         utils._check_str(name)
 495         utils._check_type(field_class, _FieldClass)
 496         utils._check_type(ranges, self._range_set_type)
 497
 498         if name in self:
 499             raise ValueError("duplicate option name '{}'".format(name))
 500
 501         if len(ranges) == 0:
 502             raise ValueError('range set is empty')
 503
 504         # TODO: check overlaps (precondition of self._append_option())
 505
 506         status = self._append_option(self._ptr, name, field_class._ptr, ranges._ptr)
 507         utils._handle_func_status(
 508             status, 'cannot append option to variant field class object'
 509         )
 510
 511     def __iadd__(self, options):
 512         for name, field_class, ranges in options:
 513             self.append_option(name, field_class, ranges)
 514
 515         return self
 516
 517
 518 class _VariantFieldClassWithUnsignedSelector(_VariantFieldClassWithSelector):
 519     _NAME = 'Variant (with unsigned selector)'
 520     _borrow_option_by_name_ptr = staticmethod(
 521         native_bt.field_class_variant_with_selector_unsigned_borrow_option_by_name_const
 522     )
 523     _borrow_member_by_index_ptr = staticmethod(
 524         native_bt.field_class_variant_with_selector_unsigned_borrow_option_by_index_const
 525     )
 526     _as_option_ptr = staticmethod(
 527         native_bt.field_class_variant_with_selector_unsigned_option_as_option_const
 528     )
 529     _append_option = staticmethod(
 530         native_bt.field_class_variant_with_selector_unsigned_append_option
 531     )
 532     _option_borrow_ranges_ptr = staticmethod(
 533         native_bt.field_class_variant_with_selector_unsigned_option_borrow_ranges_const
 534     )
 535     _range_set_type = bt2_integer_range_set.UnsignedIntegerRangeSet
 536
 537
 538 class _VariantFieldClassWithSignedSelector(_VariantFieldClassWithSelector):
 539     _NAME = 'Variant (with signed selector)'
 540     _borrow_option_by_name_ptr = staticmethod(
 541         native_bt.field_class_variant_with_selector_signed_borrow_option_by_name_const
 542     )
 543     _borrow_member_by_index_ptr = staticmethod(
 544         native_bt.field_class_variant_with_selector_signed_borrow_option_by_index_const
 545     )
 546     _as_option_ptr = staticmethod(
 547         native_bt.field_class_variant_with_selector_signed_option_as_option_const
 548     )
 549     _append_option = staticmethod(
 550         native_bt.field_class_variant_with_selector_signed_append_option
 551     )
 552     _option_borrow_ranges_ptr = staticmethod(
 553         native_bt.field_class_variant_with_selector_signed_option_borrow_ranges_const
 554     )
 555     _range_set_type = bt2_integer_range_set.SignedIntegerRangeSet
 556
 557
 558 class _ArrayFieldClass(_FieldClass):
 559     @property
 560     def element_field_class(self):
 561         elem_fc_ptr = native_bt.field_class_array_borrow_element_field_class_const(
 562             self._ptr
 563         )
 564         return _create_field_class_from_ptr_and_get_ref(elem_fc_ptr)
 565
 566
 567 class _StaticArrayFieldClass(_ArrayFieldClass):
 568     @property
 569     def length(self):
 570         return native_bt.field_class_array_static_get_length(self._ptr)
 571
 572
 573 class _DynamicArrayFieldClass(_ArrayFieldClass):
 574     @property
 575     def length_field_path(self):
 576         ptr = native_bt.field_class_array_dynamic_borrow_length_field_path_const(
 577             self._ptr
 578         )
 579         if ptr is None:
 580             return
 581
 582         return bt2_field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 583
 584
 585 _FIELD_CLASS_TYPE_TO_OBJ = {
 586     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldClass,
 587     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldClass,
 588     native_bt.FIELD_CLASS_TYPE_REAL: _RealFieldClass,
 589     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldClass,
 590     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldClass,
 591     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldClass,
 592     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldClass,
 593     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldClass,
 594     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY: _DynamicArrayFieldClass,
 595     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR: _VariantFieldClassWithoutSelector,
 596     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_SELECTOR: _VariantFieldClassWithUnsignedSelector,
 597     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_SELECTOR: _VariantFieldClassWithSignedSelector,
 598 }