Merge pull request #127 from willstott101/feature/sample_timestamp

Document SampleInfo

Author: thijsmie

cyclonedds/internal.py

@@ -242,6 +242,22 @@ def __init__(self, reference: int) -> None:
 
 @dataclass
 class SampleInfo:
+    """
+    Contains information about the associated data value
+
+    Attributes
+    ----------
+    sample_state:
+        Possible values: :class:`SampleState<cyclonedds.core.SampleState>`
+    view_state:
+        Possible values: :class:`ViewState<cyclonedds.core.ViewState>`
+    instance_state:
+        Possible values: :class:`InstanceState<cyclonedds.core.InstanceState>`
+    source_timestamp:
+        The time (in unix nanoseconds) that the associated sample was written.
+    instance_handle:
+        Handle to the data instance (if this is a keyed topic)
+    """
     sample_state: int
     view_state: int
     instance_state: int

cyclonedds/sub.py

@@ -82,6 +82,8 @@ def _notify_readers(self, subsriber: dds_c_t.entity) -> dds_c_t.returnv:
 
 class DataReader(Entity, Generic[_T]):
     """Subscribe to a topic and read/take the data published to it.
+
+    All returned samples are annotated with the :class:`sample.sample_info<cyclonedds.internal.SampleInfo>` attribute.
     """
 
     def __init__(
@@ -90,8 +92,7 @@ def __init__(
             topic: Topic[_T],
             qos: Optional[Qos] = None,
             listener: Optional[Listener] = None):
-        """Initialize the DataReader
-
+        """
         Parameters
         ----------
         subscriber_or_participant: cyclonedds.sub.Subscriber, cyclonedds.domain.DomainParticipant
@@ -309,7 +310,7 @@ def take_one(self, condition=None, timeout: int = None) -> _T:
         return sample
 
     async def read_aiter(self, condition=None, timeout: int = None) -> AsyncGenerator[_T, None]:
-        """Shortcut method to asycn iterate reading samples. Iteration will stop once the timeout you supply expires.
+        """Shortcut method to async iterate reading samples. Iteration will stop once the timeout you supply expires.
         Every time a sample is received the timeout is reset.
 
         Raises
@@ -335,7 +336,7 @@ async def read_aiter(self, condition=None, timeout: int = None) -> AsyncGenerato
                     break
 
     async def take_aiter(self, condition=None, timeout: int = None) -> AsyncGenerator[_T, None]:
-        """Shortcut method to asycn iterate taking samples. Iteration will stop once the timeout you supply expires.
+        """Shortcut method to async iterate taking samples. Iteration will stop once the timeout you supply expires.
         Every time a sample is received the timeout is reset.
 
         Raises

docs/source/cyclonedds.internal.rst

@@ -8,6 +8,8 @@ As the name suggests, the functionality in this module is meant for internal pac
    :members:
    :undoc-members:
 
+.. autoclass:: cyclonedds.internal.SampleInfo()
+
 .. autofunction:: cyclonedds.internal.load_cyclonedds
 
 .. autodecorator:: cyclonedds.internal.c_call