Tests: Multi-trace stream intersection test

[babeltrace.git] / bindings / python / writer.py

diff --git a/bindings/python/writer.py b/bindings/python/writer.py
index 5be99c218bb326c82e55f503eaf6ab74122d89b0..dc65b2438d7c60976fe54a24cf80fcb5ac12f182 100644 (file)
--- 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
 
 
@@ -2022,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)
@@ -2037,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):
@@ -2050,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),
@@ -2061,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)
@@ -2073,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)
@@ -2088,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.")