X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=dc65b2438d7c60976fe54a24cf80fcb5ac12f182;hb=5df9e303fa9d81b3a6d989612c7a98039ec76fd1;hp=d862cd82a4f809c173800379410b4ae9cc9c15cd;hpb=4ac159aa28ef36821c55290056fcab6254bb8d41;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index d862cd82..dc65b243 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -158,6 +158,9 @@ class Clock: def precision(self, precision): ret = nbt._bt_ctf_clock_set_precision(self._c, precision) + if ret < 0: + raise ValueError("Invalid precision value.") + @property def offset_seconds(self): """ @@ -168,9 +171,9 @@ class Clock: :exc:`ValueError` is raised on error. """ - offset_s = nbt._bt_ctf_clock_get_offset_s(self._c) + ret, offset_s = nbt._bt_ctf_clock_get_offset_s(self._c) - if offset_s == _MAX_UINT64: + if ret < 0: raise ValueError("Invalid clock instance") return offset_s @@ -193,9 +196,9 @@ class Clock: :exc:`ValueError` is raised on error. """ - offset = nbt._bt_ctf_clock_get_offset(self._c) + ret, offset = nbt._bt_ctf_clock_get_offset(self._c) - if offset == _MAX_UINT64: + if ret < 0: raise ValueError("Invalid clock instance") return offset @@ -280,9 +283,9 @@ class Clock: :exc:`ValueError` is raised on error. """ - time = nbt._bt_ctf_clock_get_time(self._c) + ret, time = nbt._bt_ctf_clock_get_time(self._c) - if time == _MAX_UINT64: + if ret < 0: raise ValueError("Invalid clock instance") return time @@ -301,18 +304,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 @@ -1442,20 +1452,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: @@ -1463,9 +1477,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) @@ -1478,7 +1505,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, @@ -1490,7 +1531,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) @@ -1503,7 +1544,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) @@ -1515,21 +1562,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: @@ -1543,7 +1587,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) @@ -1569,7 +1616,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) @@ -1582,9 +1632,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): @@ -1601,7 +1660,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) @@ -1616,8 +1675,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) @@ -1632,7 +1691,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, @@ -1645,7 +1721,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): @@ -1659,9 +1749,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) @@ -1675,7 +1779,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) @@ -1688,7 +1794,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) @@ -1703,10 +1813,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.") @@ -1718,7 +1824,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) @@ -1730,10 +1840,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: @@ -1742,7 +1848,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) @@ -1763,10 +1872,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): @@ -1781,7 +1893,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) @@ -1795,11 +1914,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.") @@ -1811,6 +1925,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()") @@ -1820,28 +1952,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) @@ -1852,7 +1990,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) @@ -1864,10 +2008,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") @@ -1878,8 +2018,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) @@ -1889,9 +2032,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) @@ -1904,7 +2058,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): @@ -1917,7 +2077,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), @@ -1928,8 +2091,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) @@ -1940,14 +2107,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) @@ -1955,20 +2122,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.")