src/bindings/python/bt2/bt2/field.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 from bt2 import field_class as bt2_field_class
   7 import collections.abc
   8 import functools
   9 import numbers
  10 import math
  11
  12
  13 def _create_field_from_ptr_template(
  14     object_map, ptr, owner_ptr, owner_get_ref, owner_put_ref
  15 ):
  16     field_class_ptr = native_bt.field_borrow_class_const(ptr)
  17     typeid = native_bt.field_class_get_type(field_class_ptr)
  18     field = object_map[typeid]._create_from_ptr_and_get_ref(
  19         ptr, owner_ptr, owner_get_ref, owner_put_ref
  20     )
  21     return field
  22
  23
  24 def _create_field_from_ptr(ptr, owner_ptr, owner_get_ref, owner_put_ref):
  25     return _create_field_from_ptr_template(
  26         _TYPE_ID_TO_OBJ, ptr, owner_ptr, owner_get_ref, owner_put_ref
  27     )
  28
  29
  30 def _create_field_from_const_ptr(ptr, owner_ptr, owner_get_ref, owner_put_ref):
  31     return _create_field_from_ptr_template(
  32         _TYPE_ID_TO_CONST_OBJ, ptr, owner_ptr, owner_get_ref, owner_put_ref
  33     )
  34
  35
  36 # Get the "effective" field of `field`.  If `field` is a variant, return
  37 # the currently selected field.  If `field` is an option, return the
  38 # content field.  If `field` is of any other type, return `field`
  39 # directly.
  40
  41
  42 def _get_leaf_field(field):
  43     if isinstance(field, _VariantFieldConst):
  44         return _get_leaf_field(field.selected_option)
  45
  46     if isinstance(field, _OptionFieldConst):
  47         return _get_leaf_field(field.field)
  48
  49     return field
  50
  51
  52 class _FieldConst(object._UniqueObject):
  53     _create_field_from_ptr = staticmethod(_create_field_from_const_ptr)
  54     _create_field_class_from_ptr_and_get_ref = staticmethod(
  55         bt2_field_class._create_field_class_from_const_ptr_and_get_ref
  56     )
  57     _borrow_class_ptr = staticmethod(native_bt.field_borrow_class_const)
  58
  59     def __eq__(self, other):
  60         other = _get_leaf_field(other)
  61         return self._spec_eq(other)
  62
  63     @property
  64     def cls(self):
  65         field_class_ptr = self._borrow_class_ptr(self._ptr)
  66         assert field_class_ptr is not None
  67         return self._create_field_class_from_ptr_and_get_ref(field_class_ptr)
  68
  69     def _repr(self):
  70         raise NotImplementedError
  71
  72     def __repr__(self):
  73         return self._repr()
  74
  75
  76 class _Field(_FieldConst):
  77     _create_field_from_ptr = staticmethod(_create_field_from_ptr)
  78     _create_field_class_from_ptr_and_get_ref = staticmethod(
  79         bt2_field_class._create_field_class_from_ptr_and_get_ref
  80     )
  81     _borrow_class_ptr = staticmethod(native_bt.field_borrow_class)
  82
  83
  84 class _BitArrayFieldConst(_FieldConst):
  85     _NAME = "Const bit array"
  86
  87     @property
  88     def value_as_integer(self):
  89         return native_bt.field_bit_array_get_value_as_integer(self._ptr)
  90
  91     def _spec_eq(self, other):
  92         if type(other) is not type(self):
  93             return False
  94
  95         return self.value_as_integer == other.value_as_integer
  96
  97     def _repr(self):
  98         return repr(self.value_as_integer)
  99
 100     def __str__(self):
 101         return str(self.value_as_integer)
 102
 103     def __len__(self):
 104         return self.cls.length
 105
 106
 107 class _BitArrayField(_BitArrayFieldConst, _Field):
 108     _NAME = "Bit array"
 109
 110     def _value_as_integer(self, value):
 111         utils._check_uint64(value)
 112         native_bt.field_bit_array_set_value_as_integer(self._ptr, value)
 113
 114     value_as_integer = property(
 115         fget=_BitArrayFieldConst.value_as_integer.fget, fset=_value_as_integer
 116     )
 117
 118
 119 @functools.total_ordering
 120 class _NumericFieldConst(_FieldConst):
 121     @staticmethod
 122     def _extract_value(other):
 123         if isinstance(other, _BoolFieldConst) or isinstance(other, bool):
 124             return bool(other)
 125
 126         if isinstance(other, numbers.Integral):
 127             return int(other)
 128
 129         if isinstance(other, numbers.Real):
 130             return float(other)
 131
 132         if isinstance(other, numbers.Complex):
 133             return complex(other)
 134
 135         raise TypeError(
 136             "'{}' object is not a number object".format(other.__class__.__name__)
 137         )
 138
 139     def __int__(self):
 140         return int(self._value)
 141
 142     def __float__(self):
 143         return float(self._value)
 144
 145     def _repr(self):
 146         return repr(self._value)
 147
 148     def __lt__(self, other):
 149         if not isinstance(other, numbers.Number):
 150             raise TypeError(
 151                 "unorderable types: {}() < {}()".format(
 152                     self.__class__.__name__, other.__class__.__name__
 153                 )
 154             )
 155
 156         return self._value < self._extract_value(other)
 157
 158     def _spec_eq(self, other):
 159         try:
 160             return self._value == self._extract_value(other)
 161         except Exception:
 162             return False
 163
 164     def __hash__(self):
 165         return hash(self._value)
 166
 167     def __rmod__(self, other):
 168         return self._extract_value(other) % self._value
 169
 170     def __mod__(self, other):
 171         return self._value % self._extract_value(other)
 172
 173     def __rfloordiv__(self, other):
 174         return self._extract_value(other) // self._value
 175
 176     def __floordiv__(self, other):
 177         return self._value // self._extract_value(other)
 178
 179     def __round__(self, ndigits=None):
 180         if ndigits is None:
 181             return round(self._value)
 182         else:
 183             return round(self._value, ndigits)
 184
 185     def __ceil__(self):
 186         return math.ceil(self._value)
 187
 188     def __floor__(self):
 189         return math.floor(self._value)
 190
 191     def __trunc__(self):
 192         return int(self._value)
 193
 194     def __abs__(self):
 195         return abs(self._value)
 196
 197     def __add__(self, other):
 198         return self._value + self._extract_value(other)
 199
 200     def __radd__(self, other):
 201         return self.__add__(other)
 202
 203     def __neg__(self):
 204         return -self._value
 205
 206     def __pos__(self):
 207         return +self._value
 208
 209     def __mul__(self, other):
 210         return self._value * self._extract_value(other)
 211
 212     def __rmul__(self, other):
 213         return self.__mul__(other)
 214
 215     def __truediv__(self, other):
 216         return self._value / self._extract_value(other)
 217
 218     def __rtruediv__(self, other):
 219         return self._extract_value(other) / self._value
 220
 221     def __pow__(self, exponent):
 222         return self._value ** self._extract_value(exponent)
 223
 224     def __rpow__(self, base):
 225         return self._extract_value(base) ** self._value
 226
 227
 228 class _NumericField(_NumericFieldConst, _Field):
 229     def __hash__(self):
 230         # Non const field are not hashable as their value may be modified
 231         # without changing the underlying Python object.
 232         raise TypeError("unhashable type: '{}'".format(self._NAME))
 233
 234
 235 class _IntegralFieldConst(_NumericFieldConst, numbers.Integral):
 236     def __lshift__(self, other):
 237         return self._value << self._extract_value(other)
 238
 239     def __rlshift__(self, other):
 240         return self._extract_value(other) << self._value
 241
 242     def __rshift__(self, other):
 243         return self._value >> self._extract_value(other)
 244
 245     def __rrshift__(self, other):
 246         return self._extract_value(other) >> self._value
 247
 248     def __and__(self, other):
 249         return self._value & self._extract_value(other)
 250
 251     def __rand__(self, other):
 252         return self._extract_value(other) & self._value
 253
 254     def __xor__(self, other):
 255         return self._value ^ self._extract_value(other)
 256
 257     def __rxor__(self, other):
 258         return self._extract_value(other) ^ self._value
 259
 260     def __or__(self, other):
 261         return self._value | self._extract_value(other)
 262
 263     def __ror__(self, other):
 264         return self._extract_value(other) | self._value
 265
 266     def __invert__(self):
 267         return ~self._value
 268
 269
 270 class _IntegralField(_IntegralFieldConst, _NumericField):
 271     pass
 272
 273
 274 class _BoolFieldConst(_IntegralFieldConst, _FieldConst):
 275     _NAME = "Const boolean"
 276
 277     def __bool__(self):
 278         return self._value
 279
 280     @classmethod
 281     def _value_to_bool(cls, value):
 282         if isinstance(value, _BoolFieldConst):
 283             value = value._value
 284
 285         if not isinstance(value, bool):
 286             raise TypeError(
 287                 "'{}' object is not a 'bool', '_BoolFieldConst', or '_BoolField' object".format(
 288                     value.__class__
 289                 )
 290             )
 291
 292         return value
 293
 294     @property
 295     def _value(self):
 296         return bool(native_bt.field_bool_get_value(self._ptr))
 297
 298
 299 class _BoolField(_BoolFieldConst, _IntegralField, _Field):
 300     _NAME = "Boolean"
 301
 302     def _set_value(self, value):
 303         value = self._value_to_bool(value)
 304         native_bt.field_bool_set_value(self._ptr, value)
 305
 306     value = property(fset=_set_value)
 307
 308
 309 class _IntegerFieldConst(_IntegralFieldConst, _FieldConst):
 310     pass
 311
 312
 313 class _IntegerField(_IntegerFieldConst, _IntegralField, _Field):
 314     def _check_range(self, value):
 315         if not (value >= self._lower_bound and value <= self._upper_bound):
 316             raise ValueError(
 317                 "Value {} is outside valid range [{}, {}]".format(
 318                     value, self._lower_bound, self._upper_bound
 319                 )
 320             )
 321
 322
 323 class _UnsignedIntegerFieldConst(_IntegerFieldConst, _FieldConst):
 324     _NAME = "Const unsigned integer"
 325
 326     @classmethod
 327     def _value_to_int(cls, value):
 328         if not isinstance(value, numbers.Integral):
 329             raise TypeError("expecting an integral number object")
 330
 331         return int(value)
 332
 333     @property
 334     def _value(self):
 335         return native_bt.field_integer_unsigned_get_value(self._ptr)
 336
 337
 338 class _UnsignedIntegerField(_UnsignedIntegerFieldConst, _IntegerField, _Field):
 339     _NAME = "Unsigned integer"
 340
 341     def _set_value(self, value):
 342         value = self._value_to_int(value)
 343
 344         self._check_range(value)
 345
 346         native_bt.field_integer_unsigned_set_value(self._ptr, value)
 347
 348     value = property(fset=_set_value)
 349
 350     @property
 351     def _lower_bound(self):
 352         return 0
 353
 354     @property
 355     def _upper_bound(self):
 356         return (2**self.cls.field_value_range) - 1
 357
 358
 359 class _SignedIntegerFieldConst(_IntegerFieldConst, _FieldConst):
 360     _NAME = "Const signed integer"
 361
 362     @classmethod
 363     def _value_to_int(cls, value):
 364         if not isinstance(value, numbers.Integral):
 365             raise TypeError("expecting an integral number object")
 366
 367         return int(value)
 368
 369     @property
 370     def _value(self):
 371         return native_bt.field_integer_signed_get_value(self._ptr)
 372
 373
 374 class _SignedIntegerField(_SignedIntegerFieldConst, _IntegerField, _Field):
 375     _NAME = "Signed integer"
 376
 377     def _set_value(self, value):
 378         value = self._value_to_int(value)
 379
 380         self._check_range(value)
 381
 382         native_bt.field_integer_signed_set_value(self._ptr, value)
 383
 384     value = property(fset=_set_value)
 385
 386     @property
 387     def _lower_bound(self):
 388         return -1 * (2 ** (self.cls.field_value_range - 1))
 389
 390     @property
 391     def _upper_bound(self):
 392         return (2 ** (self.cls.field_value_range - 1)) - 1
 393
 394
 395 class _RealFieldConst(_NumericFieldConst, numbers.Real):
 396     _NAME = "Const real"
 397
 398     @classmethod
 399     def _value_to_float(cls, value):
 400         if not isinstance(value, numbers.Real):
 401             raise TypeError("expecting a real number object")
 402
 403         return float(value)
 404
 405
 406 class _SinglePrecisionRealFieldConst(_RealFieldConst):
 407     _NAME = "Const single-precision real"
 408
 409     @property
 410     def _value(self):
 411         return native_bt.field_real_single_precision_get_value(self._ptr)
 412
 413
 414 class _DoublePrecisionRealFieldConst(_RealFieldConst):
 415     _NAME = "Const double-precision real"
 416
 417     @property
 418     def _value(self):
 419         return native_bt.field_real_double_precision_get_value(self._ptr)
 420
 421
 422 class _RealField(_RealFieldConst, _NumericField):
 423     _NAME = "Real"
 424
 425
 426 class _SinglePrecisionRealField(_SinglePrecisionRealFieldConst, _RealField):
 427     _NAME = "Single-precision real"
 428
 429     def _set_value(self, value):
 430         value = self._value_to_float(value)
 431         native_bt.field_real_single_precision_set_value(self._ptr, value)
 432
 433     value = property(fset=_set_value)
 434
 435
 436 class _DoublePrecisionRealField(_DoublePrecisionRealFieldConst, _RealField):
 437     _NAME = "Double-precision real"
 438
 439     def _set_value(self, value):
 440         value = self._value_to_float(value)
 441         native_bt.field_real_double_precision_set_value(self._ptr, value)
 442
 443     value = property(fset=_set_value)
 444
 445
 446 class _EnumerationFieldConst(_IntegerFieldConst):
 447     def _repr(self):
 448         return "{} ({})".format(self._value, ", ".join(self.labels))
 449
 450     @property
 451     def labels(self):
 452         status, labels = self._get_mapping_labels(self._ptr)
 453         utils._handle_func_status(status, "cannot get label for enumeration field")
 454
 455         assert labels is not None
 456         return labels
 457
 458
 459 class _EnumerationField(_EnumerationFieldConst, _IntegerField):
 460     pass
 461
 462
 463 class _UnsignedEnumerationFieldConst(
 464     _EnumerationFieldConst, _UnsignedIntegerFieldConst
 465 ):
 466     _NAME = "Const unsigned Enumeration"
 467     _get_mapping_labels = staticmethod(
 468         native_bt.field_enumeration_unsigned_get_mapping_labels
 469     )
 470
 471
 472 class _UnsignedEnumerationField(
 473     _UnsignedEnumerationFieldConst, _EnumerationField, _UnsignedIntegerField
 474 ):
 475     _NAME = "Unsigned enumeration"
 476
 477
 478 class _SignedEnumerationFieldConst(_EnumerationFieldConst, _SignedIntegerFieldConst):
 479     _NAME = "Const signed Enumeration"
 480     _get_mapping_labels = staticmethod(
 481         native_bt.field_enumeration_signed_get_mapping_labels
 482     )
 483
 484
 485 class _SignedEnumerationField(
 486     _SignedEnumerationFieldConst, _EnumerationField, _SignedIntegerField
 487 ):
 488     _NAME = "Signed enumeration"
 489
 490
 491 @functools.total_ordering
 492 class _StringFieldConst(_FieldConst):
 493     _NAME = "Const string"
 494
 495     @classmethod
 496     def _value_to_str(cls, value):
 497         if isinstance(value, _StringFieldConst):
 498             value = value._value
 499
 500         if not isinstance(value, str):
 501             raise TypeError("expecting a 'str' object")
 502
 503         return value
 504
 505     @property
 506     def _value(self):
 507         return native_bt.field_string_get_value(self._ptr)
 508
 509     def _spec_eq(self, other):
 510         try:
 511             return self._value == self._value_to_str(other)
 512         except Exception:
 513             return False
 514
 515     def __lt__(self, other):
 516         return self._value < self._value_to_str(other)
 517
 518     def __bool__(self):
 519         return bool(self._value)
 520
 521     def __hash__(self):
 522         return hash(self._value)
 523
 524     def _repr(self):
 525         return repr(self._value)
 526
 527     def __str__(self):
 528         return str(self._value)
 529
 530     def __getitem__(self, index):
 531         return self._value[index]
 532
 533     def __len__(self):
 534         return native_bt.field_string_get_length(self._ptr)
 535
 536
 537 class _StringField(_StringFieldConst, _Field):
 538     _NAME = "String"
 539
 540     def _set_value(self, value):
 541         value = self._value_to_str(value)
 542         native_bt.field_string_set_value(self._ptr, value)
 543
 544     value = property(fset=_set_value)
 545
 546     def __iadd__(self, value):
 547         value = self._value_to_str(value)
 548         status = native_bt.field_string_append(self._ptr, value)
 549         utils._handle_func_status(
 550             status, "cannot append to string field object's value"
 551         )
 552         return self
 553
 554     def __hash__(self):
 555         # Non const field are not hashable as their value may be modified
 556         # without changing the underlying Python object.
 557         raise TypeError("unhashable type: '{}'".format(self._NAME))
 558
 559
 560 class _ContainerFieldConst(_FieldConst):
 561     def __bool__(self):
 562         return len(self) != 0
 563
 564     def _count(self):
 565         return len(self.cls)
 566
 567     def __len__(self):
 568         count = self._count()
 569         assert count >= 0
 570         return count
 571
 572     def __delitem__(self, index):
 573         raise NotImplementedError
 574
 575     def __setitem__(self, index, value):
 576         raise TypeError(
 577             "'{}' object does not support item assignment".format(self.__class__)
 578         )
 579
 580
 581 class _ContainerField(_ContainerFieldConst, _Field):
 582     pass
 583
 584
 585 class _StructureFieldConst(_ContainerFieldConst, collections.abc.Mapping):
 586     _NAME = "Const structure"
 587     _borrow_member_field_ptr_by_index = staticmethod(
 588         native_bt.field_structure_borrow_member_field_by_index_const
 589     )
 590     _borrow_member_field_ptr_by_name = staticmethod(
 591         native_bt.field_structure_borrow_member_field_by_name_const
 592     )
 593
 594     def _count(self):
 595         return len(self.cls)
 596
 597     def __iter__(self):
 598         # same name iterator
 599         return iter(self.cls)
 600
 601     def _spec_eq(self, other):
 602         if not isinstance(other, collections.abc.Mapping):
 603             return False
 604
 605         if len(self) != len(other):
 606             # early mismatch
 607             return False
 608
 609         for self_key in self:
 610             if self_key not in other:
 611                 return False
 612
 613             if self[self_key] != other[self_key]:
 614                 return False
 615
 616         return True
 617
 618     def _repr(self):
 619         items = ["{}: {}".format(repr(k), repr(v)) for k, v in self.items()]
 620         return "{{{}}}".format(", ".join(items))
 621
 622     def __getitem__(self, key):
 623         utils._check_str(key)
 624         field_ptr = self._borrow_member_field_ptr_by_name(self._ptr, key)
 625
 626         if field_ptr is None:
 627             raise KeyError(key)
 628
 629         return self._create_field_from_ptr(
 630             field_ptr, self._owner_ptr, self._owner_get_ref, self._owner_put_ref
 631         )
 632
 633     def member_at_index(self, index):
 634         utils._check_uint64(index)
 635
 636         if index >= len(self):
 637             raise IndexError
 638         field_ptr = self._borrow_member_field_ptr_by_index(self._ptr, index)
 639         assert field_ptr is not None
 640         return self._create_field_from_ptr(
 641             field_ptr, self._owner_ptr, self._owner_get_ref, self._owner_put_ref
 642         )
 643
 644
 645 class _StructureField(
 646     _StructureFieldConst, _ContainerField, collections.abc.MutableMapping
 647 ):
 648     _NAME = "Structure"
 649     _borrow_member_field_ptr_by_index = staticmethod(
 650         native_bt.field_structure_borrow_member_field_by_index
 651     )
 652     _borrow_member_field_ptr_by_name = staticmethod(
 653         native_bt.field_structure_borrow_member_field_by_name
 654     )
 655
 656     def __setitem__(self, key, value):
 657         # raises if key is somehow invalid
 658         field = self[key]
 659
 660         # the field's property does the appropriate conversion or raises
 661         # the appropriate exception
 662         field.value = value
 663
 664     def _set_value(self, values):
 665         try:
 666             for key, value in values.items():
 667                 self[key].value = value
 668         except Exception:
 669             raise
 670
 671     value = property(fset=_set_value)
 672
 673
 674 class _OptionFieldConst(_FieldConst):
 675     _NAME = "Const option"
 676     _borrow_field_ptr = staticmethod(native_bt.field_option_borrow_field_const)
 677
 678     @property
 679     def field(self):
 680         field_ptr = self._borrow_field_ptr(self._ptr)
 681
 682         if field_ptr is None:
 683             return
 684
 685         return self._create_field_from_ptr(
 686             field_ptr, self._owner_ptr, self._owner_get_ref, self._owner_put_ref
 687         )
 688
 689     @property
 690     def has_field(self):
 691         return self.field is not None
 692
 693     def _spec_eq(self, other):
 694         return _get_leaf_field(self) == other
 695
 696     def __bool__(self):
 697         return self.has_field
 698
 699     def __str__(self):
 700         return str(self.field)
 701
 702     def _repr(self):
 703         return repr(self.field)
 704
 705
 706 class _OptionField(_OptionFieldConst, _Field):
 707     _NAME = "Option"
 708     _borrow_field_ptr = staticmethod(native_bt.field_option_borrow_field)
 709
 710     def _has_field(self, value):
 711         utils._check_bool(value)
 712         native_bt.field_option_set_has_field(self._ptr, value)
 713
 714     has_field = property(fget=_OptionFieldConst.has_field.fget, fset=_has_field)
 715
 716     def _set_value(self, value):
 717         self.has_field = True
 718         field = self.field
 719         assert field is not None
 720         field.value = value
 721
 722     value = property(fset=_set_value)
 723
 724
 725 class _VariantFieldConst(_ContainerFieldConst, _FieldConst):
 726     _NAME = "Const variant"
 727     _borrow_selected_option_field_ptr = staticmethod(
 728         native_bt.field_variant_borrow_selected_option_field_const
 729     )
 730
 731     def _count(self):
 732         return len(self.cls)
 733
 734     @property
 735     def selected_option_index(self):
 736         return native_bt.field_variant_get_selected_option_index(self._ptr)
 737
 738     @property
 739     def selected_option(self):
 740         # TODO: Is there a way to check if the variant field has a selected_option,
 741         # so we can raise an exception instead of hitting a pre-condition check?
 742         # If there is something, that check should be added to selected_option_index too.
 743         field_ptr = self._borrow_selected_option_field_ptr(self._ptr)
 744
 745         return self._create_field_from_ptr(
 746             field_ptr, self._owner_ptr, self._owner_get_ref, self._owner_put_ref
 747         )
 748
 749     def _spec_eq(self, other):
 750         return _get_leaf_field(self) == other
 751
 752     def __bool__(self):
 753         raise NotImplementedError
 754
 755     def __str__(self):
 756         return str(self.selected_option)
 757
 758     def _repr(self):
 759         return repr(self.selected_option)
 760
 761
 762 class _VariantField(_VariantFieldConst, _ContainerField, _Field):
 763     _NAME = "Variant"
 764     _borrow_selected_option_field_ptr = staticmethod(
 765         native_bt.field_variant_borrow_selected_option_field
 766     )
 767
 768     def _selected_option_index(self, index):
 769         if index < 0 or index >= len(self):
 770             raise IndexError("{} field object index is out of range".format(self._NAME))
 771
 772         native_bt.field_variant_select_option_by_index(self._ptr, index)
 773
 774     selected_option_index = property(
 775         fget=_VariantFieldConst.selected_option_index.fget, fset=_selected_option_index
 776     )
 777
 778     def _set_value(self, value):
 779         self.selected_option.value = value
 780
 781     value = property(fset=_set_value)
 782
 783
 784 class _ArrayFieldConst(_ContainerFieldConst, _FieldConst, collections.abc.Sequence):
 785     _borrow_element_field_ptr_by_index = staticmethod(
 786         native_bt.field_array_borrow_element_field_by_index_const
 787     )
 788
 789     def _get_length(self):
 790         return native_bt.field_array_get_length(self._ptr)
 791
 792     length = property(fget=_get_length)
 793
 794     def __getitem__(self, index):
 795         if not isinstance(index, numbers.Integral):
 796             raise TypeError(
 797                 "'{}' is not an integral number object: invalid index".format(
 798                     index.__class__.__name__
 799                 )
 800             )
 801
 802         index = int(index)
 803
 804         if index < 0 or index >= len(self):
 805             raise IndexError("{} field object index is out of range".format(self._NAME))
 806
 807         field_ptr = self._borrow_element_field_ptr_by_index(self._ptr, index)
 808         assert field_ptr
 809         return self._create_field_from_ptr(
 810             field_ptr, self._owner_ptr, self._owner_get_ref, self._owner_put_ref
 811         )
 812
 813     def insert(self, index, value):
 814         raise NotImplementedError
 815
 816     def _spec_eq(self, other):
 817         if not isinstance(other, collections.abc.Sequence):
 818             return False
 819
 820         if len(self) != len(other):
 821             # early mismatch
 822             return False
 823
 824         for self_elem, other_elem in zip(self, other):
 825             if self_elem != other_elem:
 826                 return False
 827
 828         return True
 829
 830     def _repr(self):
 831         return "[{}]".format(", ".join([repr(v) for v in self]))
 832
 833
 834 class _ArrayField(
 835     _ArrayFieldConst, _ContainerField, _Field, collections.abc.MutableSequence
 836 ):
 837     _borrow_element_field_ptr_by_index = staticmethod(
 838         native_bt.field_array_borrow_element_field_by_index
 839     )
 840
 841     def __setitem__(self, index, value):
 842         # raises if index is somehow invalid
 843         field = self[index]
 844
 845         if not isinstance(field, (_NumericField, _StringField)):
 846             raise TypeError("can only set the value of a number or string field")
 847
 848         # the field's property does the appropriate conversion or raises
 849         # the appropriate exception
 850         field.value = value
 851
 852
 853 class _StaticArrayFieldConst(_ArrayFieldConst, _FieldConst):
 854     _NAME = "Const static array"
 855
 856     def _count(self):
 857         return native_bt.field_array_get_length(self._ptr)
 858
 859
 860 class _StaticArrayField(_StaticArrayFieldConst, _ArrayField, _Field):
 861     _NAME = "Static array"
 862
 863     def _set_value(self, values):
 864         if len(self) != len(values):
 865             raise ValueError(
 866                 "expected length of value ({}) and array field ({}) to match".format(
 867                     len(values), len(self)
 868                 )
 869             )
 870
 871         for index, value in enumerate(values):
 872             if value is not None:
 873                 self[index].value = value
 874
 875     value = property(fset=_set_value)
 876
 877
 878 class _DynamicArrayFieldConst(_ArrayFieldConst, _FieldConst):
 879     _NAME = "Const dynamic array"
 880
 881     def _count(self):
 882         return self.length
 883
 884
 885 class _DynamicArrayField(_DynamicArrayFieldConst, _ArrayField, _Field):
 886     _NAME = "Dynamic array"
 887
 888     def _set_length(self, length):
 889         utils._check_uint64(length)
 890         status = native_bt.field_array_dynamic_set_length(self._ptr, length)
 891         utils._handle_func_status(status, "cannot set dynamic array length")
 892
 893     length = property(fget=_ArrayField._get_length, fset=_set_length)
 894
 895     def _set_value(self, values):
 896         if len(values) != self.length:
 897             self.length = len(values)
 898
 899         for index, value in enumerate(values):
 900             if value is not None:
 901                 self[index].value = value
 902
 903     value = property(fset=_set_value)
 904
 905
 906 _TYPE_ID_TO_CONST_OBJ = {
 907     native_bt.FIELD_CLASS_TYPE_BOOL: _BoolFieldConst,
 908     native_bt.FIELD_CLASS_TYPE_BIT_ARRAY: _BitArrayFieldConst,
 909     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldConst,
 910     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldConst,
 911     native_bt.FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL: _SinglePrecisionRealFieldConst,
 912     native_bt.FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL: _DoublePrecisionRealFieldConst,
 913     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldConst,
 914     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldConst,
 915     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldConst,
 916     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldConst,
 917     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldConst,
 918     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD: _DynamicArrayFieldConst,
 919     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD: _DynamicArrayFieldConst,
 920     native_bt.FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD: _OptionFieldConst,
 921     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD: _OptionFieldConst,
 922     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD: _OptionFieldConst,
 923     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD: _OptionFieldConst,
 924     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD: _VariantFieldConst,
 925     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD: _VariantFieldConst,
 926     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD: _VariantFieldConst,
 927 }
 928
 929 _TYPE_ID_TO_OBJ = {
 930     native_bt.FIELD_CLASS_TYPE_BOOL: _BoolField,
 931     native_bt.FIELD_CLASS_TYPE_BIT_ARRAY: _BitArrayField,
 932     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerField,
 933     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerField,
 934     native_bt.FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL: _SinglePrecisionRealField,
 935     native_bt.FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL: _DoublePrecisionRealField,
 936     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationField,
 937     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationField,
 938     native_bt.FIELD_CLASS_TYPE_STRING: _StringField,
 939     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureField,
 940     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayField,
 941     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD: _DynamicArrayField,
 942     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD: _DynamicArrayField,
 943     native_bt.FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD: _OptionField,
 944     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD: _OptionField,
 945     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD: _OptionField,
 946     native_bt.FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD: _OptionField,
 947     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD: _VariantField,
 948     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD: _VariantField,
 949     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD: _VariantField,
 950 }