X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=3d4797eba28a9f399cdb20058a1f0664dc0998bf;hb=b3df7a8f0a8bc192cb7f35c7bc3434b216d874c8;hp=f3a3f145d87f73268d1456045ec2dfc24e554392;hpb=4027ea9d5165a7fe43d6edada3c56baaa256cdb5;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index f3a3f145..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 @@ -1467,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) @@ -1482,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, @@ -1494,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) @@ -1507,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) @@ -1519,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: @@ -1547,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) @@ -1573,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) @@ -1586,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): @@ -1605,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) @@ -1620,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) @@ -1636,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, @@ -1649,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): @@ -1663,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) @@ -1679,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) @@ -1692,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) @@ -1707,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.") @@ -1722,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) @@ -1734,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: @@ -1746,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) @@ -1767,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): @@ -1785,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) @@ -1799,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.") @@ -1815,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()") @@ -1824,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) @@ -1856,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) @@ -1868,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") @@ -1882,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) @@ -1893,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) @@ -1908,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): @@ -1921,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), @@ -1932,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) @@ -1944,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) @@ -1959,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.")