X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=85494bd799cab76fb9a92d6a7399a55c2dd8ddf1;hb=ad9c62de278b38df2ebf30e317412b1adf67d056;hp=06664808f0d4088f6c36129424ecccc309981bbc;hpb=5f6ba8b24a2cdfd573b72584fc28d0506fb11ce8;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index 06664808..85494bd7 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -1368,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) @@ -1382,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) @@ -1397,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.") @@ -1414,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) @@ -1426,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: @@ -1447,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) @@ -1462,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, @@ -1474,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) @@ -1487,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) @@ -1499,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: @@ -1527,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) @@ -1553,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)