src/bindings/python/bt2/bt2/field_class.py

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