X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=67b653b4ea595de4a7519f3e907af14d93a3bec8;hb=5fd17f7375186eeba668a7717f6fd062999e3683;hp=d862cd82a4f809c173800379410b4ae9cc9c15cd;hpb=4ac159aa28ef36821c55290056fcab6254bb8d41;p=babeltrace.git diff --git a/bindings/python/writer.py b/bindings/python/writer.py index d862cd82..67b653b4 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -1442,20 +1442,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 +1467,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 +1495,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 +1521,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 +1534,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 +1552,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 +1577,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 +1606,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 +1622,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 +1650,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 +1665,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 +1681,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 +1711,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 +1739,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 +1769,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 +1784,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 +1803,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 +1814,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 +1830,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 +1838,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 +1862,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 +1883,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 +1904,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.")