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)
@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)
@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)
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,
@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)
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,
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)
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,
@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)
@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)
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,
@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)
@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)
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()
@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.")
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):
@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:
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)
@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")
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)
@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")
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)
@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")
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,
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)
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)
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)
@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.")
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)
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:
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):
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)
@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)
@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)
@clock.setter
def clock(self, clock):
- """
- Assign a clock to a stream class.
- """
-
if not isinstance(clock, Clock):
raise TypeError("Invalid clock type.")
@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)
@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:
@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)
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):
@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)
@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.")
projects / babeltrace.git / blobdiff