X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=f50b9d51fc25ec252cf9333fbf7a51f9e76ff9e3;hb=a1bdc25c9f9b67530ae3b1f611cc505897f93363;hp=7c6627e0d8ca8b9b880f073ca0e5806a38ffe9c5;hpb=a777c99fcdc93fc81ba340e20d84fbf4ca5d793a;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index 7c6627e0..f50b9d51 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -745,9 +745,16 @@ class FloatFieldDeclaration(FloatingPointFieldDeclaration): 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() @@ -755,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, @@ -768,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) @@ -794,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) @@ -807,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) @@ -823,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) @@ -836,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) @@ -848,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, @@ -861,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) @@ -887,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, @@ -901,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) @@ -914,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, @@ -926,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) @@ -939,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) @@ -951,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, @@ -963,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) @@ -976,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) @@ -988,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() @@ -999,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.") @@ -1045,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): @@ -1086,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: @@ -1095,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) @@ -1118,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") @@ -1139,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) @@ -1156,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") @@ -1180,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) @@ -1195,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") @@ -1215,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, @@ -1230,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) @@ -1244,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)