X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=3d4797eba28a9f399cdb20058a1f0664dc0998bf;hb=b3df7a8f0a8bc192cb7f35c7bc3434b216d874c8;hp=9bf9e688ecc18b23dea35c010272026cf88b3144;hpb=18449dbf1166bb346fee4f8be333ae96ac3460f4;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index 9bf9e688..3d4797eb 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -301,18 +301,25 @@ class IntegerBase: """ #: Unknown - INTEGER_BASE_UNKNOWN = -1 + UNKNOWN = -1 #: Binary - INTEGER_BASE_BINARY = 2 + BIN = 2 #: Octal - INTEGER_BASE_OCTAL = 8 + OCT = 8 #: Decimal - INTEGER_BASE_DECIMAL = 10 + DEC = 10 #: Hexadecimal + HEX = 16 + + # keep this for backward compatibility + INTEGER_BASE_UNKNOWN = -1 + INTEGER_BASE_BINARY = 2 + INTEGER_BASE_OCTAL = 8 + INTEGER_BASE_DECIMAL = 10 INTEGER_BASE_HEXADECIMAL = 16 @@ -823,9 +830,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) @@ -839,7 +860,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) @@ -852,7 +875,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) @@ -864,7 +890,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, @@ -877,7 +907,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) @@ -903,7 +936,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, @@ -917,7 +953,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) @@ -930,9 +969,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, @@ -942,7 +988,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) @@ -955,7 +1004,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) @@ -967,9 +1018,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, @@ -979,7 +1040,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) @@ -992,7 +1056,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) @@ -1004,9 +1071,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() @@ -1015,17 +1088,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.") @@ -1061,7 +1135,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): @@ -1102,6 +1179,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: @@ -1111,10 +1194,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) @@ -1134,10 +1225,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") @@ -1155,10 +1242,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) @@ -1172,23 +1266,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") @@ -1196,10 +1290,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) @@ -1211,10 +1315,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") @@ -1231,9 +1331,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, @@ -1246,9 +1353,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) @@ -1260,9 +1375,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) @@ -1274,10 +1397,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) @@ -1289,10 +1422,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.") @@ -1306,7 +1435,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) @@ -1318,20 +1449,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: @@ -1339,9 +1474,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) @@ -1354,7 +1502,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, @@ -1366,7 +1528,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) @@ -1379,7 +1541,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) @@ -1391,21 +1559,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: @@ -1419,7 +1584,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) @@ -1445,7 +1613,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) @@ -1458,9 +1629,18 @@ class EventClass: class Event: + """ + Events are specific instances of event classes + (:class:`EventClass`), which means they may contain actual, + concrete field values. + """ + def __init__(self, event_class): """ - Create a new event of the given event class. + Creates an event linked with the :class:`EventClass` + *event_class*. + + :exc:`ValueError` is raised on error. """ if not isinstance(event_class, EventClass): @@ -1477,7 +1657,7 @@ class Event: @property def event_class(self): """ - Get the event's class. + :class:`EventClass` object to which this event is linked. """ event_class_native = nbt._bt_ctf_event_get_class(self._e) @@ -1492,8 +1672,8 @@ class Event: def clock(self): """ - Get a clock from event. Returns None if the event's class - is not registered to a stream class. + :class:`Clock` object used by this object, or ``None`` if + the event class is not registered to a stream class. """ clock_instance = nbt._bt_ctf_event_get_clock(self._e) @@ -1508,7 +1688,24 @@ class Event: def payload(self, field_name): """ - Get a field from event. + Returns the :class:`Field` object named *field_name* in this + event. + + The returned field object is created using the event class' + field declaration named *field_name*. + + The return type is one of: + + * :class:`IntegerField` + * :class:`FloatingPointField` + * :class:`EnumerationField` + * :class:`StringField` + * :class:`ArrayField` + * :class:`SequenceField` + * :class:`StructureField` + * :class:`VariantField` + + :exc:`TypeError` is raised on error. """ native_instance = nbt._bt_ctf_event_get_payload(self._e, @@ -1521,7 +1718,21 @@ class Event: def set_payload(self, field_name, value_field): """ - Set a manually created field as an event's payload. + Set the event's field named *field_name* to the manually + created :class:`Field` object *value_field*. + + *value_field*'s type must be one of: + + * :class:`IntegerField` + * :class:`FloatingPointField` + * :class:`EnumerationField` + * :class:`StringField` + * :class:`ArrayField` + * :class:`SequenceField` + * :class:`StructureField` + * :class:`VariantField` + + :exc:`ValueError` is raised on error. """ if not isinstance(value, Field): @@ -1535,9 +1746,23 @@ class Event: class StreamClass: + """ + A stream class contains the properties of specific + streams (:class:`Stream`). Any concrete stream must be linked with + a :class:`StreamClass`, usually by calling + :meth:`Writer.create_stream`. + + Some attributes are automatically set when creating a stream class. + For example, if no clock is explicitly set using the + :attr:`clock` attribute, a default clock will be created + when needed. + """ + def __init__(self, name): """ - Create a new stream class of the given name. + Creates a stream class named *name*. + + :exc:`ValueError` is raised on error. """ self._sc = nbt._bt_ctf_stream_class_create(name) @@ -1551,7 +1776,9 @@ class StreamClass: @property def name(self): """ - Get a stream class' name. + Stream class' name. + + :exc:`TypeError` is raised on error. """ name = nbt._bt_ctf_stream_class_get_name(self._sc) @@ -1564,7 +1791,11 @@ class StreamClass: @property def clock(self): """ - Get a stream class' clock. + Stream class' clock (:class:`Clock` object). + + Set this attribute to change the clock of this stream class. + + :exc:`ValueError` is raised on error. """ clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc) @@ -1579,10 +1810,6 @@ class StreamClass: @clock.setter def clock(self, clock): - """ - Assign a clock to a stream class. - """ - if not isinstance(clock, Clock): raise TypeError("Invalid clock type.") @@ -1594,7 +1821,11 @@ class StreamClass: @property def id(self): """ - Get a stream class' id. + Stream class' numeric ID. + + Set this attribute to change the ID of this stream class. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_stream_class_get_id(self._sc) @@ -1606,10 +1837,6 @@ class StreamClass: @id.setter def id(self, id): - """ - Assign an id to a stream class. - """ - ret = nbt._bt_ctf_stream_class_set_id(self._sc, id) if ret < 0: @@ -1618,7 +1845,10 @@ class StreamClass: @property def event_classes(self): """ - Generator returning the stream class' event classes. + Generates the event classes (:class:`EventClass` objects) of + this stream class. + + :exc:`TypeError` is raised on error. """ count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc) @@ -1639,10 +1869,13 @@ class StreamClass: def add_event_class(self, event_class): """ - Add an event class to a stream class. New events can be added even after a - stream has been instantiated and events have been appended. However, a stream - will not accept events of a class that has not been added to the stream - class beforehand. + Registers the :class:`EventClass` *event_class* to this stream + class. + + Once the event class is registered, it will be generated as one + of the event classes generated by :attr:`event_classes`. + + :exc:`ValueError` is raised on error. """ if not isinstance(event_class, EventClass): @@ -1657,7 +1890,14 @@ class StreamClass: @property def packet_context_type(self): """ - Get the StreamClass' packet context type (StructureFieldDeclaration) + Stream packet context declaration. + + Set this attribute to change the stream packet context + declaration (must be an instance of + :class:`StructureFieldDeclaration`). + + :exc:`ValueError` is raised on error. + """ field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc) @@ -1671,11 +1911,6 @@ class StreamClass: @packet_context_type.setter def packet_context_type(self, field_type): - """ - Set a StreamClass' packet context type. Must be of type - StructureFieldDeclaration. - """ - if not isinstance(field_type, StructureFieldDeclaration): raise TypeError("field_type argument must be of type StructureFieldDeclaration.") @@ -1687,6 +1922,24 @@ class StreamClass: class Stream: + """ + Streams are specific instances of stream classes, which means they + may contain actual, concrete events. + + :class:`Stream` objects are returned by + :meth:`Writer.create_stream`; they are not meant to be + instantiated by the user. + + Concrete :class:`Event` objects are appended to + :class:`Stream` objects using :meth:`append_event`. + + When :meth:`flush` is called, a CTF packet is created, containing + all the appended events since the last flush. Although the stream + is flushed on object destruction, it is **strongly recommended** + that the user call :meth:`flush` manually before exiting the + script, as :meth:`__del__` is not always reliable. + """ + def __init__(self): raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()") @@ -1696,28 +1949,34 @@ class Stream: @property def discarded_events(self): """ - Get a stream's discarded event count. + Number of discarded (lost) events in this stream so far. + + :exc:`ValueError` is raised on error. """ ret, count = nbt._bt_ctf_stream_get_discarded_events_count(self._s) if ret < 0: - raise ValueError("Could not get the stream's discarded events count") + raise ValueError("Could not get the stream discarded events count") return count def append_discarded_events(self, event_count): """ - Increase the current packet's discarded event count. + Appends *event_count* discarded events to this stream. """ nbt._bt_ctf_stream_append_discarded_events(self._s, event_count) def append_event(self, event): """ - Append "event" to the stream's current packet. The stream's associated clock - will be sampled during this call. The event shall not be modified after - being appended to a stream. + Appends event *event* (:class:`Event` object) to this stream. + + The stream's associated clock will be sampled during this call. + *event* **shall not** be modified after being appended to this + stream. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_stream_append_event(self._s, event._e) @@ -1728,7 +1987,13 @@ class Stream: @property def packet_context(self): """ - Get a Stream's packet context field (a StructureField). + Stream packet context field (instance of + :class:`StructureField`). + + Set this attribute to assign a stream packet context field + to this stream. + + :exc:`ValueError` is raised on error. """ native_field = nbt._bt_ctf_stream_get_packet_context(self._s) @@ -1740,10 +2005,6 @@ class Stream: @packet_context.setter def packet_context(self, field): - """ - Set a Stream's packet context field (must be a StructureField). - """ - if not isinstance(field, StructureField): raise TypeError("Argument field must be of type StructureField") @@ -1754,8 +2015,11 @@ class Stream: def flush(self): """ - The stream's current packet's events will be flushed to disk. Events - subsequently appended to the stream will be added to a new packet. + Flushes the current packet of this stream to disk. Events + subsequently appended to the stream will be added to a new + packet. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_stream_flush(self._s) @@ -1765,9 +2029,20 @@ class Stream: class Writer: + """ + This object is the CTF writer API context. It oversees its streams + and clocks, and is responsible for writing one CTF trace. + """ + def __init__(self, path): """ - Create a new writer that will produce a trace in the given path. + Creates a CTF writer, initializing a new CTF trace at path + *path*. + + *path* must be an existing directory, since a CTF trace is + made of multiple files. + + :exc:`ValueError` is raised if the creation fails. """ self._w = nbt._bt_ctf_writer_create(path) @@ -1780,7 +2055,13 @@ class Writer: def create_stream(self, stream_class): """ - Create a new stream instance and register it to the writer. + Creates and registers a new stream based on stream class + *stream_class*. + + This is the standard way of creating a :class:`Stream` object: + the user is not allowed to instantiate this class. + + Returns a new :class:`Stream` object. """ if not isinstance(stream_class, StreamClass): @@ -1793,7 +2074,10 @@ class Writer: def add_environment_field(self, name, value): """ - Add an environment field to the trace. + Sets the CTF environment variable named *name* to value *value* + (converted to a string). + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_writer_add_environment_field(self._w, str(name), @@ -1804,8 +2088,12 @@ class Writer: def add_clock(self, clock): """ - Add a clock to the trace. Clocks assigned to stream classes must be - registered to the writer. + Registers :class:`Clock` object *clock* to the writer. + + You *must* register CTF clocks assigned to stream classes + to the writer. + + :exc:`ValueError` is raised if the creation fails. """ ret = nbt._bt_ctf_writer_add_clock(self._w, clock._c) @@ -1816,14 +2104,14 @@ class Writer: @property def metadata(self): """ - Get the trace's TSDL meta-data. + Current metadata of this trace (:class:`str`). """ return nbt._bt_ctf_writer_get_metadata_string(self._w) def flush_metadata(self): """ - Flush the trace's metadata to the metadata file. + Flushes the trace's metadata to the metadata file. """ nbt._bt_ctf_writer_flush_metadata(self._w) @@ -1831,20 +2119,26 @@ class Writer: @property def byte_order(self): """ - Get the trace's byte order. Must be a constant from the ByteOrder - class. + Native byte order of this trace (one of + :class:`babeltrace.common.ByteOrder` constants). + + This is the actual byte order that is used when a field + declaration has the + :attr:`babeltrace.common.ByteOrder.BYTE_ORDER_NATIVE` + value. + + Set this attribute to change the trace's native byte order. + + Defaults to the host machine's endianness. + + :exc:`ValueError` is raised on error. """ raise NotImplementedError("Getter not implemented.") @byte_order.setter def byte_order(self, byte_order): - """ - Set the trace's byte order. Must be a constant from the ByteOrder - class. Defaults to the host machine's endianness - """ - ret = nbt._bt_ctf_writer_set_byte_order(self._w, byte_order) if ret < 0: - raise ValueError("Could not set trace's byte order.") + raise ValueError("Could not set trace byte order.")