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 from bt2 import value as bt2_value
  28 import bt2
  29
  30
  31 def _create_field_class_from_ptr_and_get_ref_template(type_map, ptr):
  32     typeid = native_bt.field_class_get_type(ptr)
  33     return type_map[typeid]._create_from_ptr_and_get_ref(ptr)
  34
  35
  36 def _create_field_class_from_ptr_and_get_ref(ptr):
  37     return _create_field_class_from_ptr_and_get_ref_template(
  38         _FIELD_CLASS_TYPE_TO_OBJ, ptr
  39     )
  40
  41
  42 def _create_field_class_from_const_ptr_and_get_ref(ptr):
  43     return _create_field_class_from_ptr_and_get_ref_template(
  44         _FIELD_CLASS_TYPE_TO_CONST_OBJ, ptr
  45     )
  46
  47
  48 class IntegerDisplayBase:
  49     BINARY = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
  50     OCTAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
  51     DECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
  52     HEXADECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
  53
  54
  55 class _FieldClassConst(object._SharedObject):
  56     _get_ref = staticmethod(native_bt.field_class_get_ref)
  57     _put_ref = staticmethod(native_bt.field_class_put_ref)
  58     _borrow_user_attributes_ptr = staticmethod(
  59         native_bt.field_class_borrow_user_attributes_const
  60     )
  61     _create_value_from_ptr_and_get_ref = staticmethod(
  62         bt2_value._create_from_const_ptr_and_get_ref
  63     )
  64
  65     def _check_create_status(self, ptr):
  66         if ptr is None:
  67             raise bt2._MemoryError(
  68                 'cannot create {} field class object'.format(self._NAME.lower())
  69             )
  70
  71     @property
  72     def user_attributes(self):
  73         ptr = self._borrow_user_attributes_ptr(self._ptr)
  74         assert ptr is not None
  75         return self._create_value_from_ptr_and_get_ref(ptr)
  76
  77
  78 class _FieldClass(_FieldClassConst):
  79     _borrow_user_attributes_ptr = staticmethod(
  80         native_bt.field_class_borrow_user_attributes
  81     )
  82     _create_value_from_ptr_and_get_ref = staticmethod(
  83         bt2_value._create_from_ptr_and_get_ref
  84     )
  85
  86     def _user_attributes(self, user_attributes):
  87         value = bt2_value.create_value(user_attributes)
  88         utils._check_type(value, bt2_value.MapValue)
  89         native_bt.field_class_set_user_attributes(self._ptr, value._ptr)
  90
  91     _user_attributes = property(fset=_user_attributes)
  92
  93
  94 class _BoolFieldClassConst(_FieldClassConst):
  95     _NAME = 'Const boolean'
  96
  97
  98 class _BoolFieldClass(_BoolFieldClassConst, _FieldClass):
  99     _NAME = 'Boolean'
 100
 101
 102 class _BitArrayFieldClassConst(_FieldClassConst):
 103     _NAME = 'Const bit array'
 104
 105     @property
 106     def length(self):
 107         length = native_bt.field_class_bit_array_get_length(self._ptr)
 108         assert length >= 1
 109         return length
 110
 111
 112 class _BitArrayFieldClass(_BitArrayFieldClassConst, _FieldClass):
 113     _NAME = 'Bit array'
 114
 115
 116 class _IntegerFieldClassConst(_FieldClassConst):
 117     @property
 118     def field_value_range(self):
 119         size = native_bt.field_class_integer_get_field_value_range(self._ptr)
 120         assert size >= 1
 121         return size
 122
 123     @property
 124     def preferred_display_base(self):
 125         base = native_bt.field_class_integer_get_preferred_display_base(self._ptr)
 126         assert base >= 0
 127         return base
 128
 129
 130 class _IntegerFieldClass(_FieldClass, _IntegerFieldClassConst):
 131     def _field_value_range(self, size):
 132         if size < 1 or size > 64:
 133             raise ValueError("Value is outside valid range [1, 64] ({})".format(size))
 134         native_bt.field_class_integer_set_field_value_range(self._ptr, size)
 135
 136     _field_value_range = property(fset=_field_value_range)
 137
 138     def _preferred_display_base(self, base):
 139         utils._check_uint64(base)
 140
 141         if base not in (
 142             IntegerDisplayBase.BINARY,
 143             IntegerDisplayBase.OCTAL,
 144             IntegerDisplayBase.DECIMAL,
 145             IntegerDisplayBase.HEXADECIMAL,
 146         ):
 147             raise ValueError("Display base is not a valid IntegerDisplayBase value")
 148
 149         native_bt.field_class_integer_set_preferred_display_base(self._ptr, base)
 150
 151     _preferred_display_base = property(fset=_preferred_display_base)
 152
 153
 154 class _UnsignedIntegerFieldClassConst(_IntegerFieldClassConst, _FieldClassConst):
 155     _NAME = 'Const unsigned integer'
 156
 157
 158 class _UnsignedIntegerFieldClass(
 159     _UnsignedIntegerFieldClassConst, _IntegerFieldClass, _FieldClass
 160 ):
 161     _NAME = 'Unsigned integer'
 162
 163
 164 class _SignedIntegerFieldClassConst(_IntegerFieldClassConst, _FieldClassConst):
 165     _NAME = 'Const signed integer'
 166
 167
 168 class _SignedIntegerFieldClass(
 169     _SignedIntegerFieldClassConst, _IntegerFieldClass, _FieldClass
 170 ):
 171     _NAME = 'Signed integer'
 172
 173
 174 class _RealFieldClassConst(_FieldClassConst):
 175     pass
 176
 177
 178 class _SinglePrecisionRealFieldClassConst(_RealFieldClassConst):
 179     _NAME = 'Const single-precision real'
 180
 181
 182 class _DoublePrecisionRealFieldClassConst(_RealFieldClassConst):
 183     _NAME = 'Const double-precision real'
 184
 185
 186 class _RealFieldClass(_FieldClass, _RealFieldClassConst):
 187     pass
 188
 189
 190 class _SinglePrecisionRealFieldClass(_RealFieldClass):
 191     _NAME = 'Single-precision real'
 192
 193
 194 class _DoublePrecisionRealFieldClass(_RealFieldClass):
 195     _NAME = 'Double-precision real'
 196
 197
 198 # an enumeration field class mapping does not have a reference count, so
 199 # we copy the properties here to avoid eventual memory access errors.
 200 class _EnumerationFieldClassMapping:
 201     def __init__(self, mapping_ptr):
 202         base_mapping_ptr = self._as_enumeration_field_class_mapping_ptr(mapping_ptr)
 203         self._label = native_bt.field_class_enumeration_mapping_get_label(
 204             base_mapping_ptr
 205         )
 206         assert self._label is not None
 207         ranges_ptr = self._mapping_borrow_ranges_ptr(mapping_ptr)
 208         assert ranges_ptr is not None
 209         self._ranges = self._range_set_pycls._create_from_ptr_and_get_ref(ranges_ptr)
 210
 211     @property
 212     def label(self):
 213         return self._label
 214
 215     @property
 216     def ranges(self):
 217         return self._ranges
 218
 219
 220 class _UnsignedEnumerationFieldClassMappingConst(_EnumerationFieldClassMapping):
 221     _range_set_pycls = bt2_integer_range_set._UnsignedIntegerRangeSetConst
 222     _as_enumeration_field_class_mapping_ptr = staticmethod(
 223         native_bt.field_class_enumeration_unsigned_mapping_as_mapping_const
 224     )
 225     _mapping_borrow_ranges_ptr = staticmethod(
 226         native_bt.field_class_enumeration_unsigned_mapping_borrow_ranges_const
 227     )
 228
 229
 230 class _SignedEnumerationFieldClassMappingConst(_EnumerationFieldClassMapping):
 231     _range_set_pycls = bt2_integer_range_set._SignedIntegerRangeSetConst
 232     _as_enumeration_field_class_mapping_ptr = staticmethod(
 233         native_bt.field_class_enumeration_signed_mapping_as_mapping_const
 234     )
 235     _mapping_borrow_ranges_ptr = staticmethod(
 236         native_bt.field_class_enumeration_signed_mapping_borrow_ranges_const
 237     )
 238
 239
 240 class _EnumerationFieldClassConst(_IntegerFieldClassConst, collections.abc.Mapping):
 241     def __len__(self):
 242         count = native_bt.field_class_enumeration_get_mapping_count(self._ptr)
 243         assert count >= 0
 244         return count
 245
 246     def mappings_for_value(self, value):
 247         self._check_int_type(value)
 248
 249         status, labels = self._get_mapping_labels_for_value(self._ptr, value)
 250         utils._handle_func_status(
 251             status, 'cannot get mapping labels for value {}'.format(value)
 252         )
 253         return [self[label] for label in labels]
 254
 255     def __iter__(self):
 256         for idx in range(len(self)):
 257             mapping_ptr = self._borrow_mapping_ptr_by_index(self._ptr, idx)
 258             yield self._mapping_pycls(mapping_ptr).label
 259
 260     def __getitem__(self, label):
 261         utils._check_str(label)
 262         mapping_ptr = self._borrow_mapping_ptr_by_label(self._ptr, label)
 263
 264         if mapping_ptr is None:
 265             raise KeyError(label)
 266
 267         return self._mapping_pycls(mapping_ptr)
 268
 269
 270 class _EnumerationFieldClass(_EnumerationFieldClassConst, _IntegerFieldClass):
 271     def add_mapping(self, label, ranges):
 272         utils._check_str(label)
 273         utils._check_type(ranges, self._range_set_pycls)
 274
 275         if label in self:
 276             raise ValueError("duplicate mapping label '{}'".format(label))
 277
 278         status = self._add_mapping(self._ptr, label, ranges._ptr)
 279         utils._handle_func_status(
 280             status, 'cannot add mapping to enumeration field class object'
 281         )
 282
 283     def __iadd__(self, mappings):
 284         for label, ranges in mappings:
 285             self.add_mapping(label, ranges)
 286
 287         return self
 288
 289
 290 class _UnsignedEnumerationFieldClassConst(
 291     _EnumerationFieldClassConst, _UnsignedIntegerFieldClassConst
 292 ):
 293     _NAME = 'Const unsigned enumeration'
 294     _borrow_mapping_ptr_by_label = staticmethod(
 295         native_bt.field_class_enumeration_unsigned_borrow_mapping_by_label_const
 296     )
 297     _borrow_mapping_ptr_by_index = staticmethod(
 298         native_bt.field_class_enumeration_unsigned_borrow_mapping_by_index_const
 299     )
 300     _mapping_pycls = property(lambda _: _UnsignedEnumerationFieldClassMappingConst)
 301     _get_mapping_labels_for_value = staticmethod(
 302         native_bt.field_class_enumeration_unsigned_get_mapping_labels_for_value
 303     )
 304     _check_int_type = staticmethod(utils._check_uint64)
 305
 306
 307 class _UnsignedEnumerationFieldClass(
 308     _UnsignedEnumerationFieldClassConst,
 309     _EnumerationFieldClass,
 310     _UnsignedIntegerFieldClass,
 311 ):
 312     _NAME = 'Unsigned enumeration'
 313     _range_set_pycls = bt2_integer_range_set.UnsignedIntegerRangeSet
 314     _add_mapping = staticmethod(native_bt.field_class_enumeration_unsigned_add_mapping)
 315
 316
 317 class _SignedEnumerationFieldClassConst(
 318     _EnumerationFieldClassConst, _SignedIntegerFieldClassConst
 319 ):
 320     _NAME = 'Const signed enumeration'
 321     _borrow_mapping_ptr_by_label = staticmethod(
 322         native_bt.field_class_enumeration_signed_borrow_mapping_by_label_const
 323     )
 324     _borrow_mapping_ptr_by_index = staticmethod(
 325         native_bt.field_class_enumeration_signed_borrow_mapping_by_index_const
 326     )
 327     _mapping_pycls = property(lambda _: _SignedEnumerationFieldClassMappingConst)
 328     _get_mapping_labels_for_value = staticmethod(
 329         native_bt.field_class_enumeration_signed_get_mapping_labels_for_value
 330     )
 331     _check_int_type = staticmethod(utils._check_int64)
 332
 333
 334 class _SignedEnumerationFieldClass(
 335     _SignedEnumerationFieldClassConst, _EnumerationFieldClass, _SignedIntegerFieldClass
 336 ):
 337     _NAME = 'Signed enumeration'
 338     _range_set_pycls = bt2_integer_range_set.SignedIntegerRangeSet
 339     _add_mapping = staticmethod(native_bt.field_class_enumeration_signed_add_mapping)
 340
 341
 342 class _StringFieldClassConst(_FieldClassConst):
 343     _NAME = 'Const string'
 344
 345
 346 class _StringFieldClass(_StringFieldClassConst, _FieldClass):
 347     _NAME = 'String'
 348
 349
 350 class _StructureFieldClassMemberConst:
 351     _create_field_class_from_ptr_and_get_ref = staticmethod(
 352         _create_field_class_from_const_ptr_and_get_ref
 353     )
 354     _borrow_field_class_ptr = staticmethod(
 355         native_bt.field_class_structure_member_borrow_field_class_const
 356     )
 357     _borrow_user_attributes_ptr = staticmethod(
 358         native_bt.field_class_structure_member_borrow_user_attributes_const
 359     )
 360     _create_value_from_ptr_and_get_ref = staticmethod(
 361         bt2_value._create_from_const_ptr_and_get_ref
 362     )
 363
 364     def __init__(self, owning_struct_fc, member_ptr):
 365         # this field class owns the member; keeping it here maintains
 366         # the member alive as members are not shared objects
 367         self._owning_struct_fc = owning_struct_fc
 368         self._ptr = member_ptr
 369
 370     @property
 371     def name(self):
 372         name = native_bt.field_class_structure_member_get_name(self._ptr)
 373         assert name is not None
 374         return name
 375
 376     @property
 377     def field_class(self):
 378         fc_ptr = self._borrow_field_class_ptr(self._ptr)
 379         assert fc_ptr is not None
 380         return self._create_field_class_from_ptr_and_get_ref(fc_ptr)
 381
 382     @property
 383     def user_attributes(self):
 384         ptr = self._borrow_user_attributes_ptr(self._ptr)
 385         assert ptr is not None
 386         return self._create_value_from_ptr_and_get_ref(ptr)
 387
 388
 389 class _StructureFieldClassMember(_StructureFieldClassMemberConst):
 390     _borrow_field_class_ptr = staticmethod(
 391         native_bt.field_class_structure_member_borrow_field_class
 392     )
 393     _borrow_user_attributes_ptr = staticmethod(
 394         native_bt.field_class_structure_member_borrow_user_attributes
 395     )
 396     _create_field_class_from_ptr_and_get_ref = staticmethod(
 397         _create_field_class_from_ptr_and_get_ref
 398     )
 399     _create_value_from_ptr_and_get_ref = staticmethod(
 400         bt2_value._create_from_ptr_and_get_ref
 401     )
 402
 403     def _user_attributes(self, user_attributes):
 404         value = bt2_value.create_value(user_attributes)
 405         utils._check_type(value, bt2_value.MapValue)
 406         native_bt.field_class_structure_member_set_user_attributes(
 407             self._ptr, value._ptr
 408         )
 409
 410     _user_attributes = property(fset=_user_attributes)
 411
 412
 413 class _StructureFieldClassConst(_FieldClassConst, collections.abc.Mapping):
 414     _NAME = 'Const structure'
 415     _borrow_member_ptr_by_index = staticmethod(
 416         native_bt.field_class_structure_borrow_member_by_index_const
 417     )
 418     _borrow_member_ptr_by_name = staticmethod(
 419         native_bt.field_class_structure_borrow_member_by_name_const
 420     )
 421     _structure_member_field_class_pycls = property(
 422         lambda _: _StructureFieldClassMemberConst
 423     )
 424
 425     def __len__(self):
 426         count = native_bt.field_class_structure_get_member_count(self._ptr)
 427         assert count >= 0
 428         return count
 429
 430     def __getitem__(self, key):
 431         if not isinstance(key, str):
 432             raise TypeError(
 433                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 434             )
 435
 436         member_ptr = self._borrow_member_ptr_by_name(self._ptr, key)
 437
 438         if member_ptr is None:
 439             raise KeyError(key)
 440
 441         return self._structure_member_field_class_pycls(self, member_ptr)
 442
 443     def __iter__(self):
 444         for idx in range(len(self)):
 445             member_ptr = self._borrow_member_ptr_by_index(self._ptr, idx)
 446             assert member_ptr is not None
 447             yield native_bt.field_class_structure_member_get_name(member_ptr)
 448
 449     def member_at_index(self, index):
 450         utils._check_uint64(index)
 451
 452         if index >= len(self):
 453             raise IndexError
 454
 455         member_ptr = self._borrow_member_ptr_by_index(self._ptr, index)
 456         assert member_ptr is not None
 457         return self._structure_member_field_class_pycls(self, member_ptr)
 458
 459
 460 class _StructureFieldClass(_StructureFieldClassConst, _FieldClass):
 461     _NAME = 'Structure'
 462     _borrow_member_by_index = staticmethod(
 463         native_bt.field_class_structure_borrow_member_by_index
 464     )
 465     _borrow_member_ptr_by_name = staticmethod(
 466         native_bt.field_class_structure_borrow_member_by_name
 467     )
 468     _structure_member_field_class_pycls = property(lambda _: _StructureFieldClassMember)
 469
 470     def append_member(self, name, field_class, user_attributes=None):
 471         utils._check_str(name)
 472         utils._check_type(field_class, _FieldClass)
 473
 474         if name in self:
 475             raise ValueError("duplicate member name '{}'".format(name))
 476
 477         user_attributes_value = None
 478
 479         if user_attributes is not None:
 480             # check now that user attributes are valid
 481             user_attributes_value = bt2.create_value(user_attributes)
 482
 483         status = native_bt.field_class_structure_append_member(
 484             self._ptr, name, field_class._ptr
 485         )
 486         utils._handle_func_status(
 487             status, 'cannot append member to structure field class object'
 488         )
 489
 490         if user_attributes is not None:
 491             self[name]._user_attributes = user_attributes_value
 492
 493     def __iadd__(self, members):
 494         for name, field_class in members:
 495             self.append_member(name, field_class)
 496
 497         return self
 498
 499
 500 class _OptionFieldClassConst(_FieldClassConst):
 501     _NAME = 'Const option'
 502     _create_field_class_from_ptr_and_get_ref = staticmethod(
 503         _create_field_class_from_const_ptr_and_get_ref
 504     )
 505     _borrow_field_class_ptr = staticmethod(
 506         native_bt.field_class_option_borrow_field_class_const
 507     )
 508
 509     @property
 510     def field_class(self):
 511         elem_fc_ptr = self._borrow_field_class_ptr(self._ptr)
 512         return self._create_field_class_from_ptr_and_get_ref(elem_fc_ptr)
 513
 514
 515 class _OptionWithSelectorFieldClassConst(_OptionFieldClassConst):
 516     _NAME = 'Const option (with selector)'
 517
 518     @property
 519     def selector_field_path(self):
 520         ptr = native_bt.field_class_option_with_selector_borrow_selector_field_path_const(
 521             self._ptr
 522         )
 523         if ptr is None:
 524             return
 525
 526         return bt2_field_path._FieldPathConst._create_from_ptr_and_get_ref(ptr)
 527
 528
 529 class _OptionWithBoolSelectorFieldClassConst(_OptionWithSelectorFieldClassConst):
 530     _NAME = 'Const option (with boolean selector)'
 531
 532     @property
 533     def selector_is_reversed(self):
 534         return bool(
 535             native_bt.field_class_option_with_selector_bool_selector_is_reversed(
 536                 self._ptr
 537             )
 538         )
 539
 540
 541 class _OptionWithIntegerSelectorFieldClassConst(_OptionWithSelectorFieldClassConst):
 542     _NAME = 'Const option (with integer selector)'
 543
 544     @property
 545     def ranges(self):
 546         range_set_ptr = self._borrow_selector_ranges_ptr(self._ptr)
 547         assert range_set_ptr is not None
 548         return self._range_set_pycls._create_from_ptr_and_get_ref(range_set_ptr)
 549
 550
 551 class _OptionWithUnsignedIntegerSelectorFieldClassConst(
 552     _OptionWithIntegerSelectorFieldClassConst
 553 ):
 554     _NAME = 'Const option (with unsigned integer selector)'
 555     _range_set_pycls = bt2_integer_range_set._UnsignedIntegerRangeSetConst
 556     _borrow_selector_ranges_ptr = staticmethod(
 557         native_bt.field_class_option_with_selector_integer_unsigned_borrow_selector_ranges_const
 558     )
 559
 560
 561 class _OptionWithSignedIntegerSelectorFieldClassConst(
 562     _OptionWithIntegerSelectorFieldClassConst
 563 ):
 564     _NAME = 'Const option (with signed integer selector)'
 565     _range_set_pycls = bt2_integer_range_set._SignedIntegerRangeSetConst
 566     _borrow_selector_ranges_ptr = staticmethod(
 567         native_bt.field_class_option_with_selector_integer_signed_borrow_selector_ranges_const
 568     )
 569
 570
 571 class _OptionFieldClass(_OptionFieldClassConst, _FieldClass):
 572     _NAME = 'Option'
 573     _borrow_field_class_ptr = staticmethod(
 574         native_bt.field_class_option_borrow_field_class
 575     )
 576     _create_field_class_from_ptr_and_get_ref = staticmethod(
 577         _create_field_class_from_ptr_and_get_ref
 578     )
 579
 580
 581 class _OptionWithSelectorFieldClass(
 582     _OptionWithSelectorFieldClassConst, _OptionFieldClass
 583 ):
 584     _NAME = 'Option (with selector)'
 585
 586
 587 class _OptionWithBoolSelectorFieldClass(
 588     _OptionWithBoolSelectorFieldClassConst, _OptionWithSelectorFieldClass
 589 ):
 590     _NAME = 'Option (with boolean selector)'
 591
 592     def _selector_is_reversed(self, selector_is_reversed):
 593         utils._check_bool(selector_is_reversed)
 594         native_bt.field_class_option_with_selector_bool_set_selector_is_reversed(
 595             self._ptr, selector_is_reversed
 596         )
 597
 598     _selector_is_reversed = property(fset=_selector_is_reversed)
 599
 600
 601 class _OptionWithIntegerSelectorFieldClass(
 602     _OptionWithIntegerSelectorFieldClassConst, _OptionWithSelectorFieldClass
 603 ):
 604     _NAME = 'Option (with integer selector)'
 605
 606
 607 class _OptionWithUnsignedIntegerSelectorFieldClass(
 608     _OptionWithUnsignedIntegerSelectorFieldClassConst,
 609     _OptionWithIntegerSelectorFieldClass,
 610 ):
 611     _NAME = 'Option (with unsigned integer selector)'
 612
 613
 614 class _OptionWithSignedIntegerSelectorFieldClass(
 615     _OptionWithSignedIntegerSelectorFieldClassConst,
 616     _OptionWithIntegerSelectorFieldClass,
 617 ):
 618     _NAME = 'Option (with signed integer selector)'
 619
 620
 621 class _VariantFieldClassOptionConst:
 622     _create_field_class_from_ptr_and_get_ref = staticmethod(
 623         _create_field_class_from_const_ptr_and_get_ref
 624     )
 625     _borrow_field_class_ptr = staticmethod(
 626         native_bt.field_class_variant_option_borrow_field_class_const
 627     )
 628     _borrow_user_attributes_ptr = staticmethod(
 629         native_bt.field_class_variant_option_borrow_user_attributes_const
 630     )
 631     _create_value_from_ptr_and_get_ref = staticmethod(
 632         bt2_value._create_from_const_ptr_and_get_ref
 633     )
 634
 635     def __init__(self, owning_var_fc, option_ptr):
 636         # this field class owns the option; keeping it here maintains
 637         # the option alive as options are not shared objects
 638         self._owning_var_fc = owning_var_fc
 639         self._ptr = option_ptr
 640
 641     @property
 642     def name(self):
 643         name = native_bt.field_class_variant_option_get_name(self._ptr)
 644         assert name is not None
 645         return name
 646
 647     @property
 648     def field_class(self):
 649         fc_ptr = self._borrow_field_class_ptr(self._ptr)
 650         assert fc_ptr is not None
 651         return self._create_field_class_from_ptr_and_get_ref(fc_ptr)
 652
 653     @property
 654     def user_attributes(self):
 655         ptr = self._borrow_user_attributes_ptr(self._ptr)
 656         assert ptr is not None
 657         return self._create_value_from_ptr_and_get_ref(ptr)
 658
 659
 660 class _VariantFieldClassOption(_VariantFieldClassOptionConst):
 661     _create_field_class_from_ptr_and_get_ref = staticmethod(
 662         _create_field_class_from_ptr_and_get_ref
 663     )
 664     _borrow_field_class_ptr = staticmethod(
 665         native_bt.field_class_variant_option_borrow_field_class
 666     )
 667     _borrow_user_attributes_ptr = staticmethod(
 668         native_bt.field_class_variant_option_borrow_user_attributes
 669     )
 670     _create_value_from_ptr_and_get_ref = staticmethod(
 671         bt2_value._create_from_ptr_and_get_ref
 672     )
 673
 674     def _user_attributes(self, user_attributes):
 675         value = bt2_value.create_value(user_attributes)
 676         utils._check_type(value, bt2_value.MapValue)
 677         native_bt.field_class_variant_option_set_user_attributes(self._ptr, value._ptr)
 678
 679     _user_attributes = property(fset=_user_attributes)
 680
 681
 682 class _VariantFieldClassWithIntegerSelectorOptionConst(_VariantFieldClassOptionConst):
 683     def __init__(self, owning_var_fc, spec_opt_ptr):
 684         self._spec_ptr = spec_opt_ptr
 685         super().__init__(owning_var_fc, self._as_option_ptr(spec_opt_ptr))
 686
 687     @property
 688     def ranges(self):
 689         range_set_ptr = self._borrow_ranges_ptr(self._spec_ptr)
 690         assert range_set_ptr is not None
 691         return self._range_set_pycls._create_from_ptr_and_get_ref(range_set_ptr)
 692
 693
 694 class _VariantFieldClassWithIntegerSelectorOption(
 695     _VariantFieldClassWithIntegerSelectorOptionConst, _VariantFieldClassOption
 696 ):
 697     pass
 698
 699
 700 class _VariantFieldClassWithSignedIntegerSelectorOptionConst(
 701     _VariantFieldClassWithIntegerSelectorOptionConst
 702 ):
 703     _as_option_ptr = staticmethod(
 704         native_bt.field_class_variant_with_selector_integer_signed_option_as_option_const
 705     )
 706     _borrow_ranges_ptr = staticmethod(
 707         native_bt.field_class_variant_with_selector_integer_signed_option_borrow_ranges_const
 708     )
 709     _range_set_pycls = bt2_integer_range_set._SignedIntegerRangeSetConst
 710
 711
 712 class _VariantFieldClassWithSignedIntegerSelectorOption(
 713     _VariantFieldClassWithSignedIntegerSelectorOptionConst,
 714     _VariantFieldClassWithIntegerSelectorOption,
 715 ):
 716     pass
 717
 718
 719 class _VariantFieldClassWithUnsignedIntegerSelectorOptionConst(
 720     _VariantFieldClassWithIntegerSelectorOptionConst
 721 ):
 722     _as_option_ptr = staticmethod(
 723         native_bt.field_class_variant_with_selector_integer_unsigned_option_as_option_const
 724     )
 725     _borrow_ranges_ptr = staticmethod(
 726         native_bt.field_class_variant_with_selector_integer_unsigned_option_borrow_ranges_const
 727     )
 728     _range_set_pycls = bt2_integer_range_set._UnsignedIntegerRangeSetConst
 729
 730
 731 class _VariantFieldClassWithUnsignedIntegerSelectorOption(
 732     _VariantFieldClassWithUnsignedIntegerSelectorOptionConst,
 733     _VariantFieldClassWithIntegerSelectorOption,
 734 ):
 735     pass
 736
 737
 738 class _VariantFieldClassConst(_FieldClassConst, collections.abc.Mapping):
 739     _NAME = 'Const variant'
 740     _borrow_option_ptr_by_name = staticmethod(
 741         native_bt.field_class_variant_borrow_option_by_name_const
 742     )
 743     _borrow_option_ptr_by_index = staticmethod(
 744         native_bt.field_class_variant_borrow_option_by_index_const
 745     )
 746     _variant_option_pycls = _VariantFieldClassOptionConst
 747
 748     @staticmethod
 749     def _as_option_ptr(opt_ptr):
 750         return opt_ptr
 751
 752     def _create_option_from_ptr(self, opt_ptr):
 753         return self._variant_option_pycls(self, opt_ptr)
 754
 755     def __len__(self):
 756         count = native_bt.field_class_variant_get_option_count(self._ptr)
 757         assert count >= 0
 758         return count
 759
 760     def __getitem__(self, key):
 761         if not isinstance(key, str):
 762             raise TypeError(
 763                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 764             )
 765
 766         opt_ptr = self._borrow_option_ptr_by_name(self._ptr, key)
 767
 768         if opt_ptr is None:
 769             raise KeyError(key)
 770
 771         return self._create_option_from_ptr(opt_ptr)
 772
 773     def __iter__(self):
 774         for idx in range(len(self)):
 775             opt_ptr = self._borrow_option_ptr_by_index(self._ptr, idx)
 776             assert opt_ptr is not None
 777             base_opt_ptr = self._as_option_ptr(opt_ptr)
 778             yield native_bt.field_class_variant_option_get_name(base_opt_ptr)
 779
 780     def option_at_index(self, index):
 781         utils._check_uint64(index)
 782
 783         if index >= len(self):
 784             raise IndexError
 785
 786         opt_ptr = self._borrow_option_ptr_by_index(self._ptr, index)
 787         assert opt_ptr is not None
 788         return self._create_option_from_ptr(opt_ptr)
 789
 790
 791 class _VariantFieldClass(_VariantFieldClassConst, _FieldClass, collections.abc.Mapping):
 792     _NAME = 'Variant'
 793     _borrow_option_ptr_by_name = staticmethod(
 794         native_bt.field_class_variant_borrow_option_by_name
 795     )
 796     _borrow_option_ptr_by_index = staticmethod(
 797         native_bt.field_class_variant_borrow_option_by_index
 798     )
 799     _variant_option_pycls = _VariantFieldClassOption
 800
 801
 802 class _VariantFieldClassWithoutSelectorConst(_VariantFieldClassConst):
 803     _NAME = 'Const variant (without selector)'
 804
 805
 806 class _VariantFieldClassWithoutSelector(
 807     _VariantFieldClassWithoutSelectorConst, _VariantFieldClass
 808 ):
 809     _NAME = 'Variant (without selector)'
 810
 811     def append_option(self, name, field_class, user_attributes=None):
 812         utils._check_str(name)
 813         utils._check_type(field_class, _FieldClass)
 814
 815         if name in self:
 816             raise ValueError("duplicate option name '{}'".format(name))
 817
 818         user_attributes_value = None
 819
 820         if user_attributes is not None:
 821             # check now that user attributes are valid
 822             user_attributes_value = bt2.create_value(user_attributes)
 823
 824         status = native_bt.field_class_variant_without_selector_append_option(
 825             self._ptr, name, field_class._ptr
 826         )
 827         utils._handle_func_status(
 828             status, 'cannot append option to variant field class object'
 829         )
 830
 831         if user_attributes is not None:
 832             self[name]._user_attributes = user_attributes_value
 833
 834     def __iadd__(self, options):
 835         for name, field_class in options:
 836             self.append_option(name, field_class)
 837
 838         return self
 839
 840
 841 class _VariantFieldClassWithIntegerSelectorConst(_VariantFieldClassConst):
 842     _NAME = 'Const variant (with selector)'
 843
 844     @property
 845     def selector_field_path(self):
 846         ptr = native_bt.field_class_variant_with_selector_borrow_selector_field_path_const(
 847             self._ptr
 848         )
 849
 850         if ptr is None:
 851             return
 852
 853         return bt2_field_path._FieldPathConst._create_from_ptr_and_get_ref(ptr)
 854
 855
 856 class _VariantFieldClassWithIntegerSelector(
 857     _VariantFieldClassWithIntegerSelectorConst, _VariantFieldClass
 858 ):
 859     _NAME = 'Variant (with selector)'
 860
 861     def append_option(self, name, field_class, ranges, user_attributes=None):
 862         utils._check_str(name)
 863         utils._check_type(field_class, _FieldClass)
 864         utils._check_type(ranges, self._variant_option_pycls._range_set_pycls)
 865
 866         if name in self:
 867             raise ValueError("duplicate option name '{}'".format(name))
 868
 869         if len(ranges) == 0:
 870             raise ValueError('range set is empty')
 871
 872         user_attributes_value = None
 873
 874         if user_attributes is not None:
 875             # check now that user attributes are valid
 876             user_attributes_value = bt2.create_value(user_attributes)
 877
 878         # TODO: check overlaps (precondition of self._append_option())
 879
 880         status = self._append_option(self._ptr, name, field_class._ptr, ranges._ptr)
 881         utils._handle_func_status(
 882             status, 'cannot append option to variant field class object'
 883         )
 884
 885         if user_attributes is not None:
 886             self[name]._user_attributes = user_attributes_value
 887
 888     def __iadd__(self, options):
 889         for name, field_class, ranges in options:
 890             self.append_option(name, field_class, ranges)
 891
 892         return self
 893
 894
 895 class _VariantFieldClassWithUnsignedIntegerSelectorConst(
 896     _VariantFieldClassWithIntegerSelectorConst
 897 ):
 898     _NAME = 'Const variant (with unsigned integer selector)'
 899     _borrow_option_ptr_by_name = staticmethod(
 900         native_bt.field_class_variant_with_selector_integer_unsigned_borrow_option_by_name_const
 901     )
 902     _borrow_option_ptr_by_index = staticmethod(
 903         native_bt.field_class_variant_with_selector_integer_unsigned_borrow_option_by_index_const
 904     )
 905     _variant_option_pycls = _VariantFieldClassWithUnsignedIntegerSelectorOptionConst
 906     _as_option_ptr = staticmethod(_variant_option_pycls._as_option_ptr)
 907
 908
 909 class _VariantFieldClassWithUnsignedIntegerSelector(
 910     _VariantFieldClassWithUnsignedIntegerSelectorConst,
 911     _VariantFieldClassWithIntegerSelector,
 912 ):
 913     _NAME = 'Variant (with unsigned integer selector)'
 914     _variant_option_pycls = _VariantFieldClassWithUnsignedIntegerSelectorOption
 915     _as_option_ptr = staticmethod(_variant_option_pycls._as_option_ptr)
 916     _append_option = staticmethod(
 917         native_bt.field_class_variant_with_selector_integer_unsigned_append_option
 918     )
 919
 920
 921 class _VariantFieldClassWithSignedIntegerSelectorConst(
 922     _VariantFieldClassWithIntegerSelectorConst
 923 ):
 924     _NAME = 'Const variant (with signed integer selector)'
 925     _borrow_option_ptr_by_name = staticmethod(
 926         native_bt.field_class_variant_with_selector_integer_signed_borrow_option_by_name_const
 927     )
 928     _borrow_option_ptr_by_index = staticmethod(
 929         native_bt.field_class_variant_with_selector_integer_signed_borrow_option_by_index_const
 930     )
 931     _variant_option_pycls = _VariantFieldClassWithSignedIntegerSelectorOptionConst
 932     _as_option_ptr = staticmethod(_variant_option_pycls._as_option_ptr)
 933
 934
 935 class _VariantFieldClassWithSignedIntegerSelector(
 936     _VariantFieldClassWithSignedIntegerSelectorConst,
 937     _VariantFieldClassWithIntegerSelector,
 938 ):
 939     _NAME = 'Variant (with signed integer selector)'
 940     _variant_option_pycls = _VariantFieldClassWithSignedIntegerSelectorOption
 941     _as_option_ptr = staticmethod(_variant_option_pycls._as_option_ptr)
 942     _append_option = staticmethod(
 943         native_bt.field_class_variant_with_selector_integer_signed_append_option
 944     )
 945
 946
 947 class _ArrayFieldClassConst(_FieldClassConst):
 948     _create_field_class_from_ptr_and_get_ref = staticmethod(
 949         _create_field_class_from_const_ptr_and_get_ref
 950     )
 951     _borrow_element_field_class = staticmethod(
 952         native_bt.field_class_array_borrow_element_field_class_const
 953     )
 954
 955     @property
 956     def element_field_class(self):
 957         elem_fc_ptr = self._borrow_element_field_class(self._ptr)
 958         return self._create_field_class_from_ptr_and_get_ref(elem_fc_ptr)
 959
 960
 961 class _ArrayFieldClass(_ArrayFieldClassConst, _FieldClass):
 962     _create_field_class_from_ptr_and_get_ref = staticmethod(
 963         _create_field_class_from_ptr_and_get_ref
 964     )
 965     _borrow_element_field_class = staticmethod(
 966         native_bt.field_class_array_borrow_element_field_class
 967     )
 968
 969
 970 class _StaticArrayFieldClassConst(_ArrayFieldClassConst):
 971     _NAME = 'Const static array'
 972
 973     @property
 974     def length(self):
 975         return native_bt.field_class_array_static_get_length(self._ptr)
 976
 977
 978 class _StaticArrayFieldClass(_StaticArrayFieldClassConst, _ArrayFieldClass):
 979     _NAME = 'Static array'
 980
 981
 982 class _DynamicArrayFieldClassConst(_ArrayFieldClassConst):
 983     _NAME = 'Const dynamic array'
 984
 985     @property
 986     def length_field_path(self):
 987         ptr = native_bt.field_class_array_dynamic_borrow_length_field_path_const(
 988             self._ptr
 989         )
 990         if ptr is None:
 991             return
 992
 993         return bt2_field_path._FieldPathConst._create_from_ptr_and_get_ref(ptr)
 994
 995
 996 class _DynamicArrayFieldClass(_DynamicArrayFieldClassConst, _ArrayFieldClass):
 997     _NAME = 'Dynamic array'
 998
 999
1000 _FIELD_CLASS_TYPE_TO_CONST_OBJ = {
1001     native_bt.FIELD_CLASS_TYPE_BOOL: _BoolFieldClassConst,
1002     native_bt.FIELD_CLASS_TYPE_BIT_ARRAY: _BitArrayFieldClassConst,
1003     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldClassConst,
1004     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldClassConst,
1005     native_bt.FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL: _SinglePrecisionRealFieldClassConst,
1006     native_bt.FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL: _DoublePrecisionRealFieldClassConst,
1007     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldClassConst,
1008     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldClassConst,
1009     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldClassConst,
1010     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldClassConst,
1011     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldClassConst,
1012     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY: _DynamicArrayFieldClassConst,
1013     native_bt.FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR: _OptionFieldClassConst,
1014     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR: _OptionWithBoolSelectorFieldClassConst,
1015     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR: _OptionWithUnsignedIntegerSelectorFieldClassConst,
1016     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR: _OptionWithSignedIntegerSelectorFieldClassConst,
1017     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR: _VariantFieldClassWithoutSelectorConst,
1018     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR: _VariantFieldClassWithUnsignedIntegerSelectorConst,
1019     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR: _VariantFieldClassWithSignedIntegerSelectorConst,
1020 }
1021
1022 _FIELD_CLASS_TYPE_TO_OBJ = {
1023     native_bt.FIELD_CLASS_TYPE_BOOL: _BoolFieldClass,
1024     native_bt.FIELD_CLASS_TYPE_BIT_ARRAY: _BitArrayFieldClass,
1025     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldClass,
1026     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldClass,
1027     native_bt.FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL: _SinglePrecisionRealFieldClass,
1028     native_bt.FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL: _DoublePrecisionRealFieldClass,
1029     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldClass,
1030     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldClass,
1031     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldClass,
1032     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldClass,
1033     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldClass,
1034     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY: _DynamicArrayFieldClass,
1035     native_bt.FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR: _OptionFieldClass,
1036     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR: _OptionWithBoolSelectorFieldClass,
1037     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR: _OptionWithUnsignedIntegerSelectorFieldClass,
1038     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR: _OptionWithSignedIntegerSelectorFieldClass,
1039     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR: _VariantFieldClassWithoutSelector,
1040     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR: _VariantFieldClassWithUnsignedIntegerSelector,
1041     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR: _VariantFieldClassWithSignedIntegerSelector,
1042 }