X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=f50b9d51fc25ec252cf9333fbf7a51f9e76ff9e3;hb=a1bdc25c9f9b67530ae3b1f611cc505897f93363;hp=e860655497345d37b95979df52ca6d6704415df6;hpb=fe9f5df14673e19b55f0f4462ec2c99f6b96451f;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index e8606554..f50b9d51 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -399,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: @@ -436,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: @@ -505,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) @@ -517,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: @@ -537,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 @@ -559,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) @@ -582,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: @@ -607,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() @@ -624,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) @@ -637,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) @@ -652,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) @@ -664,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) @@ -677,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() @@ -692,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, @@ -705,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) @@ -731,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) @@ -744,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) @@ -760,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) @@ -773,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) @@ -785,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, @@ -798,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) @@ -824,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, @@ -838,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) @@ -851,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, @@ -863,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) @@ -876,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) @@ -888,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, @@ -900,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) @@ -913,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) @@ -925,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() @@ -936,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.") @@ -982,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): @@ -1023,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: @@ -1032,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) @@ -1055,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") @@ -1076,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) @@ -1093,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") @@ -1117,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) @@ -1132,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") @@ -1152,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, @@ -1167,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) @@ -1181,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)