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)
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,
@property
def name(self):
"""
- Get the event class' name.
+ Event class' name.
"""
name = nbt._bt_ctf_event_class_get_name(self._ec)
@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)
@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:
@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)
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)
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):
@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)
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)
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,
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):
projects / babeltrace.git / blobdiff