X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=85494bd799cab76fb9a92d6a7399a55c2dd8ddf1;hb=ad9c62de278b38df2ebf30e317412b1adf67d056;hp=2751e4e2a47c95d8e8ccf3aa84c8ba0f6781e5fa;hpb=a20c2934ae82ee595069aa62db8d161ce0a2e68d;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index 2751e4e2..85494bd7 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -295,6 +295,27 @@ class Clock: raise ValueError("Invalid time value.") +class IntegerBase: + """ + Display base of an integer. + """ + + #: Unknown + INTEGER_BASE_UNKNOWN = -1 + + #: Binary + INTEGER_BASE_BINARY = 2 + + #: Octal + INTEGER_BASE_OCTAL = 8 + + #: Decimal + INTEGER_BASE_DECIMAL = 10 + + #: Hexadecimal + INTEGER_BASE_HEXADECIMAL = 16 + + class FieldDeclaration: """ Base class of all field declarations. This class is not meant to @@ -302,14 +323,8 @@ class FieldDeclaration: declaration subclasses instead. """ - class IntegerBase: - # These values are based on the bt_ctf_integer_base enum - # declared in event-types.h. - INTEGER_BASE_UNKNOWN = -1 - INTEGER_BASE_BINARY = 2 - INTEGER_BASE_OCTAL = 8 - INTEGER_BASE_DECIMAL = 10 - INTEGER_BASE_HEXADECIMAL = 16 + class IntegerBase(IntegerBase): + pass def __init__(self): if self._ft is None: @@ -384,36 +399,52 @@ class FieldDeclaration: class IntegerFieldDeclaration(FieldDeclaration): + """ + Integer field declaration. + """ + def __init__(self, size): """ - Create a new integer field declaration of the given size. + Creates an integer field declaration of size *size* bits. + + :exc:`ValueError` is raised on error. """ + self._ft = nbt._bt_ctf_field_type_integer_create(size) super().__init__() @property def size(self): """ - Get an integer's size. + Integer size in bits (integer). + + Set this attribute to change this integer's size. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_integer_get_size(self._ft) if ret < 0: - raise ValueError("Could not get Integer's size attribute.") + raise ValueError("Could not get Integer size attribute.") else: return ret @property def signed(self): """ - Get an integer's signedness attribute. + ``True`` if this integer is signed. + + Set this attribute to change this integer's signedness + (boolean). + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_integer_get_signed(self._ft) if ret < 0: - raise ValueError("Could not get Integer's signed attribute.") + raise ValueError("Could not get Integer signed attribute.") elif ret > 0: return True else: @@ -421,64 +452,66 @@ class IntegerFieldDeclaration(FieldDeclaration): @signed.setter def signed(self, signed): - """ - Set an integer's signedness attribute. - """ - ret = nbt._bt_ctf_field_type_integer_set_signed(self._ft, signed) if ret < 0: - raise ValueError("Could not set Integer's signed attribute.") + raise ValueError("Could not set Integer signed attribute.") @property def base(self): """ - Get the integer's base used to pretty-print the resulting trace. - Returns a constant from the FieldDeclaration.IntegerBase class. + Integer display base (one of :class:`IntegerBase` constants). + + Set this attribute to change this integer's display base. + + :exc:`ValueError` is raised on error. """ return nbt._bt_ctf_field_type_integer_get_base(self._ft) @base.setter def base(self, base): - """ - Set the integer's base used to pretty-print the resulting trace. - The base must be a constant of the FieldDeclarationIntegerBase class. - """ - ret = nbt._bt_ctf_field_type_integer_set_base(self._ft, base) if ret < 0: - raise ValueError("Could not set Integer's base.") + raise ValueError("Could not set Integer base.") @property def encoding(self): """ - Get the integer's encoding (one of the constants of the - CTFStringEncoding class). - Returns a constant from the CTFStringEncoding class. + Integer encoding (one of + :class:`babeltrace.common.CTFStringEncoding` constants). + + Set this attribute to change this integer's encoding. + + :exc:`ValueError` is raised on error. """ return nbt._bt_ctf_field_type_integer_get_encoding(self._ft) @encoding.setter def encoding(self, encoding): - """ - An integer encoding may be set to signal that the integer must be printed - as a text character. Must be a constant from the CTFStringEncoding class. - """ - ret = nbt._bt_ctf_field_type_integer_set_encoding(self._ft, encoding) if ret < 0: - raise ValueError("Could not set Integer's encoding.") + raise ValueError("Could not set Integer encoding.") class EnumerationFieldDeclaration(FieldDeclaration): + """ + Enumeration field declaration. A CTF enumeration maps labels to + ranges of integers. + """ + def __init__(self, integer_type): """ - Create a new enumeration field declaration with the given underlying container type. + Creates an enumeration field declaration, with *integer_type* + being the underlying :class:`IntegerFieldDeclaration` for storing + the integer. + + :exc:`ValueError` is raised on error. """ + isinst = isinstance(integer_type, IntegerFieldDeclaration) if integer_type is None or not isinst: @@ -490,7 +523,9 @@ class EnumerationFieldDeclaration(FieldDeclaration): @property def container(self): """ - Get the enumeration's underlying container type. + Underlying container (:class:`IntegerFieldDeclaration`). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_enumeration_get_container_type(self._ft) @@ -502,7 +537,12 @@ class EnumerationFieldDeclaration(FieldDeclaration): def add_mapping(self, name, range_start, range_end): """ - Add a mapping to the enumeration. The range's values are inclusive. + Adds a mapping to the enumeration field declaration, from the + label named *name* to range [*range_start*, *range_end*], where + *range_start* and *range_end* are integers included in the + range. + + :exc:`ValueError` is raised on error. """ if range_start < 0 or range_end < 0: @@ -522,7 +562,10 @@ class EnumerationFieldDeclaration(FieldDeclaration): @property def mappings(self): """ - Generator returning instances of EnumerationMapping. + Generates the mappings of this enumeration field declaration + (:class:`EnumerationMapping` objects). + + :exc:`TypeError` is raised on error. """ signed = self.container.signed @@ -544,7 +587,10 @@ class EnumerationFieldDeclaration(FieldDeclaration): def get_mapping_by_name(self, name): """ - Get a mapping by name (EnumerationMapping). + Returns the :class:`EnumerationMapping` object for the label + named *name*. + + :exc:`TypeError` is raised on error. """ index = nbt._bt_ctf_field_type_enumeration_get_mapping_index_by_name(self._ft, name) @@ -567,7 +613,10 @@ class EnumerationFieldDeclaration(FieldDeclaration): def get_mapping_by_value(self, value): """ - Get a mapping by value (EnumerationMapping). + Returns the :class:`EnumerationMapping` object for the value + *value* (integer). + + :exc:`TypeError` is raised on error. """ if value < 0: @@ -592,15 +641,44 @@ class EnumerationFieldDeclaration(FieldDeclaration): return EnumerationMapping(name, range_start, range_end) -class FloatFieldDeclaration(FieldDeclaration): +class FloatingPointFieldDeclaration(FieldDeclaration): + """ + Floating point number field declaration. + + A CTF floating point number is a made of three sections: the sign + bit, the exponent bits, and the mantissa bits. The most significant + bit of the resulting binary word is the sign bit, and is included + in the number of mantissa bits. + + For example, the + `IEEE 754 `_ + single precision floating point number is represented on a 32-bit + word using an 8-bit exponent (``e``) and a 24-bit mantissa (``m``), + the latter count including the sign bit (``s``):: + + s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm + + The IEEE 754 double precision floating point number uses an + 11-bit exponent and a 53-bit mantissa. + """ + + #: IEEE 754 single precision floating point number exponent size FLT_EXP_DIG = 8 + + #: IEEE 754 double precision floating point number exponent size DBL_EXP_DIG = 11 + + #: IEEE 754 single precision floating point number mantissa size FLT_MANT_DIG = 24 + + #: IEEE 754 double precision floating point number mantissa size DBL_MANT_DIG = 53 def __init__(self): """ - Create a new floating point field declaration. + Creates a floating point number field declaration. + + :exc:`ValueError` is raised on error. """ self._ft = nbt._bt_ctf_field_type_floating_point_create() @@ -609,7 +687,13 @@ class FloatFieldDeclaration(FieldDeclaration): @property def exponent_digits(self): """ - Get the number of exponent digits used to store the floating point field. + Floating point number exponent section size in bits (integer). + + Set this attribute to change the floating point number's + exponent section's size. You may use :attr:`FLT_EXP_DIG` or + :attr:`DBL_EXP_DIG` for IEEE 754 floating point numbers. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_floating_point_get_exponent_digits(self._ft) @@ -622,12 +706,6 @@ class FloatFieldDeclaration(FieldDeclaration): @exponent_digits.setter def exponent_digits(self, exponent_digits): - """ - Set the number of exponent digits to use to store the floating point field. - The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG which - are defined as constants of this class. - """ - ret = nbt._bt_ctf_field_type_floating_point_set_exponent_digits(self._ft, exponent_digits) @@ -637,7 +715,13 @@ class FloatFieldDeclaration(FieldDeclaration): @property def mantissa_digits(self): """ - Get the number of mantissa digits used to store the floating point field. + Floating point number mantissa section size in bits (integer). + + Set this attribute to change the floating point number's + mantissa section's size. You may use :attr:`FLT_MANT_DIG` or + :attr:`DBL_MANT_DIG` for IEEE 754 floating point numbers. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_floating_point_get_mantissa_digits(self._ft) @@ -649,12 +733,6 @@ class FloatFieldDeclaration(FieldDeclaration): @mantissa_digits.setter def mantissa_digits(self, mantissa_digits): - """ - Set the number of mantissa digits to use to store the floating point field. - The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG which - are defined as constants of this class. - """ - ret = nbt._bt_ctf_field_type_floating_point_set_mantissa_digits(self._ft, mantissa_digits) @@ -662,14 +740,21 @@ class FloatFieldDeclaration(FieldDeclaration): raise ValueError("Could not set mantissa digit count.") -class FloatingPointFieldDeclaration(FloatFieldDeclaration): +class FloatFieldDeclaration(FloatingPointFieldDeclaration): pass class StructureFieldDeclaration(FieldDeclaration): + """ + Structure field declaration, i.e. an ordered mapping from field + names to field declarations. + """ + def __init__(self): """ - Create a new structure field declaration. + Creates an empty structure field declaration. + + :exc:`ValueError` is raised on error. """ self._ft = nbt._bt_ctf_field_type_structure_create() @@ -677,7 +762,10 @@ class StructureFieldDeclaration(FieldDeclaration): def add_field(self, field_type, field_name): """ - Add a field of type "field_type" to the structure. + Appends one :class:`FieldDeclaration` *field_type* named + *field_name* to the structure's ordered map. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_structure_add_field(self._ft, @@ -690,7 +778,10 @@ class StructureFieldDeclaration(FieldDeclaration): @property def fields(self): """ - Generator returning the structure's field as tuples of (field name, field declaration). + Generates the (field name, :class:`FieldDeclaration`) pairs + of this structure. + + :exc:`TypeError` is raised on error. """ count = nbt._bt_ctf_field_type_structure_get_field_count(self._ft) @@ -716,7 +807,10 @@ class StructureFieldDeclaration(FieldDeclaration): def get_field_by_name(self, name): """ - Get a field declaration by name (FieldDeclaration). + Returns the :class:`FieldDeclaration` mapped to the field name + *name* in this structure. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_field_type_structure_get_field_type_by_name(self._ft, name) @@ -729,9 +823,23 @@ class StructureFieldDeclaration(FieldDeclaration): class VariantFieldDeclaration(FieldDeclaration): + """ + Variant field declaration. + + A CTF variant is a dynamic selection between different fields. + The value of a *tag* (a CTF enumeration) determines what is the + current selected field. All the possible fields must be added to + its field declaration before using an actual variant field. + """ + def __init__(self, enum_tag, tag_name): """ - Create a new variant field declaration. + Creates an empty variant field declaration with tag field + declaration *enum_tag* (instance of + :class:`EnumerationFieldDeclaration`) named *tag_name* + (string). + + :exc:`ValueError` is raised on error. """ isinst = isinstance(enum_tag, EnumerationFieldDeclaration) @@ -745,7 +853,9 @@ class VariantFieldDeclaration(FieldDeclaration): @property def tag_name(self): """ - Get the variant's tag name. + Variant field declaration tag name. + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_get_tag_name(self._ft) @@ -758,7 +868,10 @@ class VariantFieldDeclaration(FieldDeclaration): @property def tag_type(self): """ - Get the variant's tag type. + Variant field declaration tag field declaration + (:class:`EnumerationFieldDeclaration` object). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_get_tag_type(self._ft) @@ -770,7 +883,11 @@ class VariantFieldDeclaration(FieldDeclaration): def add_field(self, field_type, field_name): """ - Add a field of type "field_type" to the variant. + Registers the :class:`FieldDeclaration` object *field_type* + as the variant's selected type when the variant's tag's current + label is *field_name*. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_add_field(self._ft, @@ -783,7 +900,10 @@ class VariantFieldDeclaration(FieldDeclaration): @property def fields(self): """ - Generator returning the variant's field as tuples of (field name, field declaration). + Generates the (field name, :class:`FieldDeclaration`) pairs + of this variant field declaration. + + :exc:`TypeError` is raised on error. """ count = nbt._bt_ctf_field_type_variant_get_field_count(self._ft) @@ -809,7 +929,10 @@ class VariantFieldDeclaration(FieldDeclaration): def get_field_by_name(self, name): """ - Get a field declaration by name (FieldDeclaration). + Returns the :class:`FieldDeclaration` selected when the + variant's tag's current label is *name*. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_by_name(self._ft, @@ -823,7 +946,10 @@ class VariantFieldDeclaration(FieldDeclaration): def get_field_from_tag(self, tag): """ - Get a field declaration from tag (EnumerationField). + Returns the :class:`FieldDeclaration` selected by the current + label of the :class:`EnumerationField` *tag*. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_from_tag(self._ft, tag._f) @@ -836,9 +962,16 @@ class VariantFieldDeclaration(FieldDeclaration): class ArrayFieldDeclaration(FieldDeclaration): + """ + Static array field declaration. + """ + def __init__(self, element_type, length): """ - Create a new array field declaration. + Creates a static array field declaration of *length* + elements of type *element_type* (:class:`FieldDeclaration`). + + :exc:`ValueError` is raised on error. """ self._ft = nbt._bt_ctf_field_type_array_create(element_type._ft, @@ -848,7 +981,10 @@ class ArrayFieldDeclaration(FieldDeclaration): @property def element_type(self): """ - Get the array's element type. + Type of the elements of this this static array (subclass of + :class:`FieldDeclaration`). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_array_get_element_type(self._ft) @@ -861,7 +997,9 @@ class ArrayFieldDeclaration(FieldDeclaration): @property def length(self): """ - Get the array's length. + Length of this static array (integer). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_array_get_length(self._ft) @@ -873,9 +1011,19 @@ class ArrayFieldDeclaration(FieldDeclaration): class SequenceFieldDeclaration(FieldDeclaration): + """ + Sequence (dynamic array) field declaration. + """ + def __init__(self, element_type, length_field_name): """ - Create a new sequence field declaration. + Creates a sequence field declaration of + elements of type *element_type* (:class:`FieldDeclaration`). + The length of a sequence field based on this sequence field + declaration is obtained by retrieving the dynamic integer + value of the field named *length_field_name*. + + :exc:`ValueError` is raised on error. """ self._ft = nbt._bt_ctf_field_type_sequence_create(element_type._ft, @@ -885,7 +1033,10 @@ class SequenceFieldDeclaration(FieldDeclaration): @property def element_type(self): """ - Get the sequence's element type. + Type of the elements of this sequence (subclass of + :class:`FieldDeclaration`). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_sequence_get_element_type(self._ft) @@ -898,7 +1049,10 @@ class SequenceFieldDeclaration(FieldDeclaration): @property def length_field_name(self): """ - Get the sequence's length field name. + Name of the integer field defining the dynamic length of + sequence fields based on this sequence field declaration. + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_sequence_get_length_field_name(self._ft) @@ -910,9 +1064,15 @@ class SequenceFieldDeclaration(FieldDeclaration): class StringFieldDeclaration(FieldDeclaration): + """ + String (NULL-terminated array of bytes) field declaration. + """ + def __init__(self): """ - Create a new string field declaration. + Creates a string field declaration. + + :exc:`ValueError` is raised on error. """ self._ft = nbt._bt_ctf_field_type_string_create() @@ -921,17 +1081,18 @@ class StringFieldDeclaration(FieldDeclaration): @property def encoding(self): """ - Get a string declaration's encoding (a constant from the CTFStringEncoding class). + String encoding (one of + :class:`babeltrace.common.CTFStringEncoding` constants). + + Set this attribute to change this string's encoding. + + :exc:`ValueError` is raised on error. """ return nbt._bt_ctf_field_type_string_get_encoding(self._ft) @encoding.setter def encoding(self, encoding): - """ - Set a string declaration's encoding. Must be a constant from the CTFStringEncoding class. - """ - ret = nbt._bt_ctf_field_type_string_set_encoding(self._ft, encoding) if ret < 0: raise ValueError("Could not set string encoding.") @@ -967,7 +1128,10 @@ def create_field(field_type): class Field: """ - Base class, do not instantiate. + Base class of all fields. This class is not meant to be + instantiated by the user, and neither are its subclasses. Use + :meth:`Event.payload` to access specific, concrete fields of + an event. """ def __init__(self, field_type): @@ -1008,6 +1172,12 @@ class Field: @property def declaration(self): + """ + Field declaration (subclass of :class:`FieldDeclaration`). + + :exc:`TypeError` is raised on error. + """ + native_field_type = nbt._bt_ctf_field_get_type(self._f) if native_field_type is None: @@ -1017,10 +1187,18 @@ class Field: class IntegerField(Field): + """ + Integer field, based on an :class:`IntegerFieldDeclaration` object. + """ + @property def value(self): """ - Get an integer field's value. + Integer value (:class:`int`). + + Set this attribute to change the integer field's value. + + :exc:`ValueError` or :exc:`TypeError` are raised on error. """ signedness = nbt._bt_python_field_integer_get_signedness(self._f) @@ -1040,10 +1218,6 @@ class IntegerField(Field): @value.setter def value(self, value): - """ - Set an integer field's value. - """ - if not isinstance(value, int): raise TypeError("IntegerField's value must be an int") @@ -1061,10 +1235,17 @@ class IntegerField(Field): class EnumerationField(Field): + """ + Enumeration field, based on an + :class:`EnumerationFieldDeclaration` object. + """ + @property def container(self): """ - Return the enumeration's underlying container field (an integer field). + Underlying container (:class:`IntegerField`). + + :exc:`TypeError` is raised on error. """ container = IntegerField.__new__(IntegerField) @@ -1078,23 +1259,23 @@ class EnumerationField(Field): @property def value(self): """ - Get the enumeration field's mapping name. + Current label of this enumeration field (:class:`str`). + + Set this attribute to an integer (:class:`int`) to change the + enumeration field's value. + + :exc:`ValueError` is raised on error. """ value = nbt._bt_ctf_field_enumeration_get_mapping_name(self._f) if value is None: - raise ValueError("Could not get enumeration's mapping name.") + raise ValueError("Could not get enumeration mapping name.") return value @value.setter def value(self, value): - """ - Set the enumeration field's value. Must be an integer as mapping names - may be ambiguous. - """ - if not isinstance(value, int): raise TypeError("EnumerationField value must be an int") @@ -1102,10 +1283,20 @@ class EnumerationField(Field): class FloatingPointField(Field): + """ + Floating point number field, based on a + :class:`FloatingPointFieldDeclaration` object. + """ + @property def value(self): """ - Get a floating point field's value. + Floating point number value (:class:`float`). + + Set this attribute to change the floating point number field's + value. + + :exc:`ValueError` or :exc:`TypeError` are raised on error. """ ret, value = nbt._bt_ctf_field_floating_point_get_value(self._f) @@ -1117,10 +1308,6 @@ class FloatingPointField(Field): @value.setter def value(self, value): - """ - Set a floating point field's value. - """ - if not isinstance(value, int) and not isinstance(value, float): raise TypeError("Value must be either a float or an int") @@ -1137,9 +1324,16 @@ class FloatFieldingPoint(FloatingPointField): class StructureField(Field): + """ + Structure field, based on a + :class:`StructureFieldDeclaration` object. + """ + def field(self, field_name): """ - Get the structure's field corresponding to the provided field name. + Returns the structure :class:`Field` named *field_name*. + + :exc:`ValueError` is raised on error. """ native_instance = nbt._bt_ctf_field_structure_get_field(self._f, @@ -1152,9 +1346,17 @@ class StructureField(Field): class VariantField(Field): + """ + Variant field, based on a + :class:`VariantFieldDeclaration` object. + """ + def field(self, tag): """ - Return the variant's selected field. The "tag" field is the selector enum field. + Returns the :class:`Field` selected by the current label of + *tag* (:class:`EnumerationField`). + + :exc:`ValueError` is raised on error. """ native_instance = nbt._bt_ctf_field_variant_get_field(self._f, tag._f) @@ -1166,9 +1368,17 @@ class VariantField(Field): class ArrayField(Field): + """ + Static array field, based on an + :class:`ArrayFieldDeclaration` object. + """ + def field(self, index): """ - Return the array's field at position "index". + Returns the :class:`Field` at index *index* in this static + array. + + :exc:`IndexError` is raised on error. """ native_instance = nbt._bt_ctf_field_array_get_field(self._f, index) @@ -1180,10 +1390,20 @@ class ArrayField(Field): class SequenceField(Field): + """ + Sequence (dynamic array) field, based on a + :class:`SequenceFieldDeclaration` object. + """ + @property def length(self): """ - Get the sequence's length field (IntegerField). + Sequence length (:class:`IntegerField`). + + Set this attribute to change the sequence length's integer + field (integer must be unsigned). + + :exc:`ValueError` or :exc:`TypeError` are raised on error. """ native_instance = nbt._bt_ctf_field_sequence_get_length(self._f) @@ -1195,10 +1415,6 @@ class SequenceField(Field): @length.setter def length(self, length_field): - """ - Set the sequence's length field (IntegerField). - """ - if not isinstance(length_field, IntegerField): raise TypeError("Invalid length field.") @@ -1212,7 +1428,9 @@ class SequenceField(Field): def field(self, index): """ - Return the sequence's field at position "index". + Returns the :class:`Field` at index *index* in this sequence. + + :exc:`ValueError` is raised on error. """ native_instance = nbt._bt_ctf_field_sequence_get_field(self._f, index) @@ -1224,20 +1442,24 @@ class SequenceField(Field): class StringField(Field): + """ + String (NULL-terminated array of bytes) field. + """ + @property def value(self): """ - Get a string field's value. + String value (:class:`str`). + + Set this attribute to change the string's value. + + :exc:`ValueError` or :exc:`TypeError` are raised on error. """ return nbt._bt_ctf_field_string_get_value(self._f) @value.setter def value(self, value): - """ - Set a string field's value. - """ - ret = nbt._bt_ctf_field_string_set_value(self._f, str(value)) if ret < 0: @@ -1245,9 +1467,22 @@ class StringField(Field): class EventClass: + """ + An event class contains the properties of specific + events (:class:`Event`). Any concrete event must be linked with an + :class:`EventClass`. + + Some attributes are automatically set when creating an event class. + For example, if no numeric ID is explicitly set using the + :attr:`id` attribute, a default, unique ID within the stream class + containing this event class will be created when needed. + """ + def __init__(self, name): """ - Create a new event class of the given name. + Creates an event class named *name*. + + :exc:`ValueError` is raised on error. """ self._ec = nbt._bt_ctf_event_class_create(name) @@ -1260,7 +1495,21 @@ class EventClass: def add_field(self, field_type, field_name): """ - Add a field of type "field_type" to the event class. + Adds a field declaration *field_type* named *field_name* to + this event class. + + *field_type* must be one of: + + * :class:`IntegerFieldDeclaration` + * :class:`FloatingPointFieldDeclaration` + * :class:`EnumerationFieldDeclaration` + * :class:`StringFieldDeclaration` + * :class:`ArrayFieldDeclaration` + * :class:`SequenceFieldDeclaration` + * :class:`StructureFieldDeclaration` + * :class:`VariantFieldDeclaration` + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_event_class_add_field(self._ec, field_type._ft, @@ -1272,7 +1521,7 @@ class EventClass: @property def name(self): """ - Get the event class' name. + Event class' name. """ name = nbt._bt_ctf_event_class_get_name(self._ec) @@ -1285,7 +1534,13 @@ class EventClass: @property def id(self): """ - Get the event class' id. Returns a negative value if unset. + Event class' numeric ID. + + Set this attribute to assign a numeric ID to this event class. + This ID must be unique amongst all the event class IDs of a + given stream class. + + :exc:`TypeError` is raised on error. """ id = nbt._bt_ctf_event_class_get_id(self._ec) @@ -1297,21 +1552,18 @@ class EventClass: @id.setter def id(self, id): - """ - Set the event class' id. Throws a TypeError if the event class - is already registered to a stream class. - """ - ret = nbt._bt_ctf_event_class_set_id(self._ec, id) if ret < 0: - raise TypeError("Can't change an Event Class's id after it has been assigned to a stream class") + raise TypeError("Can't change an Event Class id after it has been assigned to a stream class") @property def stream_class(self): """ - Get the event class' stream class. Returns None if unset. + :class:`StreamClass` object containing this event class, + or ``None`` if not set. """ + stream_class_native = nbt._bt_ctf_event_class_get_stream_class(self._ec) if stream_class_native is None: @@ -1325,7 +1577,10 @@ class EventClass: @property def fields(self): """ - Generator returning the event class' fields as tuples of (field name, field declaration). + Generates the (field name, :class:`FieldDeclaration`) pairs of + this event class. + + :exc:`TypeError` is raised on error. """ count = nbt._bt_ctf_event_class_get_field_count(self._ec) @@ -1351,7 +1606,10 @@ class EventClass: def get_field_by_name(self, name): """ - Get a field declaration by name (FieldDeclaration). + Returns the :class:`FieldDeclaration` object named *name* in + this event class. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_event_class_get_field_by_name(self._ec, name)