dora-rs 0.3.12__cp37-abi3-macosx_14_5_arm64.whl

dora/__init__.py

@@ -0,0 +1,42 @@
+""" 
+# dora-rs.
+
+This is the dora python client for interacting with dora dataflow.
+You can install it via:
+```bash
+pip install dora-rs
+```.
+"""
+
+from enum import Enum
+
+from .dora import *
+from .dora import (
+    Node,
+    Ros2Context,
+    Ros2Durability,
+    Ros2Liveliness,
+    Ros2Node,
+    Ros2NodeOptions,
+    Ros2Publisher,
+    Ros2QosPolicies,
+    Ros2Subscription,
+    Ros2Topic,
+    __author__,
+    __version__,
+    start_runtime,
+)
+
+
+class DoraStatus(Enum):
+    """Dora status to indicate if operator `on_input` loop should be stopped.
+
+    Args:
+        Enum (u8): Status signaling to dora operator to
+        stop or continue the operator.
+
+    """
+
+    CONTINUE = 0
+    STOP = 1
+    STOP_ALL = 2

dora/__init__.pyi

@@ -0,0 +1,335 @@
+import typing
+
+import pyarrow
+
+import dora
+
+@typing.final
+class Enum:
+    """Generic enumeration.
+
+    Derive from this class to define new enumerations.
+    """
+
+    __members__: mappingproxy = ...
+
+@typing.final
+class Node:
+    """The custom node API lets you integrate `dora` into your application.
+    
+    It allows you to retrieve input and send output in any fashion you want.
+
+    Use with:
+
+    ```python
+    from dora import Node
+
+    node = Node()
+    ```
+    """
+
+    def __init__(self, node_id: str=None) -> None:
+        """Use the custom node API to embed `dora` into your application.
+
+        It allows you to retrieve input and send output in any fashion you want.
+
+        Use with:
+
+        ```python
+        from dora import Node
+
+        node = Node()
+        ```
+        """
+
+    def dataflow_descriptor(self) -> dict:
+        """Return the full dataflow descriptor that this node is part of.
+
+        This method returns the parsed dataflow YAML file.
+        """
+
+    def dataflow_id(self) -> str:
+        """Return the dataflow id."""
+
+    def merge_external_events(self, subscription: dora.Ros2Subscription) -> None:
+        """Merge an external event stream with dora main loop.
+
+        This currently only work with ROS2.
+        """
+
+    def next(self, timeout: float=None) -> dict:
+        """`.next()` gives you the next input that the node has received.
+
+        It blocks until the next event becomes available.
+        You can use timeout in seconds to return if no input is available.
+        It will return `None` when all senders has been dropped.
+
+        ```python
+        event = node.next()
+        ```
+
+        You can also iterate over the event stream with a loop
+
+        ```python
+        for event in node:
+        match event["type"]:
+        case "INPUT":
+        match event["id"]:
+        case "image":
+        ```
+        """
+
+    def send_output(self, output_id: str, data: pyarrow.Array, metadata: dict=None) -> None:
+        """`send_output` send data from the node.
+
+        ```python
+        Args:
+        output_id: str,
+        data: pyarrow.Array,
+        metadata: Option[Dict],
+        ```
+
+        ex:
+
+        ```python
+        node.send_output("string", b"string", {"open_telemetry_context": "7632e76"})
+        ```
+        """
+
+    def __iter__(self) -> typing.Any:
+        """Implement iter(self)."""
+
+    def __next__(self) -> typing.Any:
+        """Implement next(self)."""
+
+@typing.final
+class Ros2Context:
+    """ROS2 Context holding all messages definition for receiving and sending messages to ROS2.
+
+    By default, Ros2Context will use env `AMENT_PREFIX_PATH` to search for message definition.
+
+    AMENT_PREFIX_PATH folder structure should be the following:
+
+    - For messages: <namespace>/msg/<name>.msg
+    - For services: <namespace>/srv/<name>.srv
+
+    You can also use `ros_paths` if you don't want to use env variable.
+
+    warning::
+    dora Ros2 bridge functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    ```python
+    context = Ros2Context()
+    ```
+    """
+
+    def __init__(self, ros_paths: list[str]=None) -> None:
+        """ROS2 Context holding all messages definition for receiving and sending messages to ROS2.
+
+        By default, Ros2Context will use env `AMENT_PREFIX_PATH` to search for message definition.
+
+        AMENT_PREFIX_PATH folder structure should be the following:
+
+        - For messages: <namespace>/msg/<name>.msg
+        - For services: <namespace>/srv/<name>.srv
+
+        You can also use `ros_paths` if you don't want to use env variable.
+
+        warning::
+        dora Ros2 bridge functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+
+        ```python
+        context = Ros2Context()
+        ```
+        """
+
+    def new_node(self, name: str, namespace: str, options: dora.Ros2NodeOptions) -> dora.Ros2Node:
+        """Create a new ROS2 node.
+
+        ```python
+        ros2_node = ros2_context.new_node(
+        "turtle_teleop",
+        "/ros2_demo",
+        Ros2NodeOptions(rosout=True),
+        )
+        ```
+
+        warning::
+        dora Ros2 bridge functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+        """
+
+@typing.final
+class Ros2Durability:
+    """DDS 2.2.3.4 DURABILITY."""
+
+    def __eq__(self, value: object) -> bool:
+        """Return self==value."""
+
+    def __ge__(self, value: typing.Any) -> bool:
+        """Return self>=value."""
+
+    def __gt__(self, value: typing.Any) -> bool:
+        """Return self>value."""
+
+    def __int__(self) -> None:
+        """int(self)."""
+
+    def __le__(self, value: typing.Any) -> bool:
+        """Return self<=value."""
+
+    def __lt__(self, value: typing.Any) -> bool:
+        """Return self<value."""
+
+    def __ne__(self, value: object) -> bool:
+        """Return self!=value."""
+
+    Persistent: Ros2Durability = ...
+    Transient: Ros2Durability = ...
+    TransientLocal: Ros2Durability = ...
+    Volatile: Ros2Durability = ...
+
+@typing.final
+class Ros2Liveliness:
+    """DDS 2.2.3.11 LIVELINESS."""
+
+    def __eq__(self, value: object) -> bool:
+        """Return self==value."""
+
+    def __ge__(self, value: typing.Any) -> bool:
+        """Return self>=value."""
+
+    def __gt__(self, value: typing.Any) -> bool:
+        """Return self>value."""
+
+    def __int__(self) -> None:
+        """int(self)."""
+
+    def __le__(self, value: typing.Any) -> bool:
+        """Return self<=value."""
+
+    def __lt__(self, value: typing.Any) -> bool:
+        """Return self<value."""
+
+    def __ne__(self, value: object) -> bool:
+        """Return self!=value."""
+
+    Automatic: Ros2Liveliness = ...
+    ManualByParticipant: Ros2Liveliness = ...
+    ManualByTopic: Ros2Liveliness = ...
+
+@typing.final
+class Ros2Node:
+    """ROS2 Node.
+
+    warnings::
+    - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+    - There's a known issue about ROS2 nodes not being discoverable by ROS2
+    See: https://github.com/jhelovuo/ros2-client/issues/4
+    """
+
+    def create_publisher(self, topic: dora.Ros2Topic, qos: dora.Ros2QosPolicies=None) -> dora.Ros2Publisher:
+        """Create a ROS2 publisher.
+
+        ```python
+        pose_publisher = ros2_node.create_publisher(turtle_pose_topic)
+        ```
+        warnings:
+        - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+        """
+
+    def create_subscription(self, topic: dora.Ros2Topic, qos: dora.Ros2QosPolicies=None) -> dora.Ros2Subscription:
+        """Create a ROS2 subscription.
+
+        ```python
+        pose_reader = ros2_node.create_subscription(turtle_pose_topic)
+        ```
+
+        Warnings:
+        - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+
+        """
+
+    def create_topic(self, name: str, message_type: str, qos: dora.Ros2QosPolicies) -> dora.Ros2Topic:
+        """Create a ROS2 topic to connect to.
+
+        ```python
+        turtle_twist_topic = ros2_node.create_topic(
+        "/turtle1/cmd_vel", "geometry_msgs/Twist", topic_qos
+        )
+        ```
+        """
+
+@typing.final
+class Ros2NodeOptions:
+    """ROS2 Node Options."""
+
+    def __init__(self, rosout: bool=None) -> None:
+        """ROS2 Node Options."""
+
+@typing.final
+class Ros2Publisher:
+    """ROS2 Publisher.
+
+    Warnings:
+    - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    """
+
+    def publish(self, data: pyarrow.Array) -> None:
+        """Publish a message into ROS2 topic.
+
+        Remember that the data format should respect the structure of the ROS2 message using an arrow Structure.
+
+        ex:
+        ```python
+        gripper_command.publish(
+        pa.array(
+        [
+        {
+        "name": "gripper",
+        "cmd": np.float32(5),
+        }
+        ]
+        ),
+        )
+        ```
+        """
+
+@typing.final
+class Ros2QosPolicies:
+    """ROS2 QoS Policy."""
+
+    def __init__(self, durability: dora.Ros2Durability=None, liveliness: dora.Ros2Liveliness=None, reliable: bool=None, keep_all: bool=None, lease_duration: float=None, max_blocking_time: float=None, keep_last: int=None) -> dora.Ros2QoSPolicies:
+        """ROS2 QoS Policy."""
+
+@typing.final
+class Ros2Subscription:
+    """ROS2 Subscription.
+
+    Warnings:
+    - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    """
+
+    def next(self):...
+
+@typing.final
+class Ros2Topic:
+    """ROS2 Topic.
+
+    Warnings:
+    - dora Ros2 bridge functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    """
+
+def start_runtime() -> None:
+    """Start a runtime for Operators."""

dora/cuda.py

@@ -0,0 +1,94 @@
+"""TODO: Add docstring."""
+
+import pyarrow as pa
+
+# Make sure to install torch with cuda
+import torch
+from numba.cuda import to_device
+
+# Make sure to install numba with cuda
+from numba.cuda.cudadrv.devicearray import DeviceNDArray
+from numba.cuda.cudadrv.devices import get_context
+from numba.cuda.cudadrv.driver import IpcHandle
+
+
+import json
+
+from contextlib import contextmanager
+from typing import ContextManager
+
+
+def torch_to_ipc_buffer(tensor: torch.TensorType) -> tuple[pa.array, dict]:
+    """Convert a Pytorch tensor into a pyarrow buffer containing the IPC handle
+    and its metadata.
+
+    Example Use:
+    ```python
+    torch_tensor = torch.tensor(random_data, dtype=torch.int64, device="cuda")
+    ipc_buffer, metadata = torch_to_ipc_buffer(torch_tensor)
+    node.send_output("latency", ipc_buffer, metadata)
+    ```
+    """
+    device_arr = to_device(tensor)
+    ipch = get_context().get_ipc_handle(device_arr.gpu_data)
+    _, handle, size, source_info, offset = ipch.__reduce__()[1]
+    metadata = {
+        "shape": device_arr.shape,
+        "strides": device_arr.strides,
+        "dtype": device_arr.dtype.str,
+        "size": size,
+        "offset": offset,
+        "source_info": json.dumps(source_info),
+    }
+    return pa.array(handle, pa.int8()), metadata
+
+
+def ipc_buffer_to_ipc_handle(handle_buffer: pa.array, metadata: dict) -> IpcHandle:
+    """Convert a buffer containing a serialized handler into cuda IPC Handle.
+
+    example use:
+    ```python
+    from dora.cuda import ipc_buffer_to_ipc_handle, open_ipc_handle
+
+    event = node.next()
+
+    ipc_handle = ipc_buffer_to_ipc_handle(event["value"], event["metadata"])
+    with open_ipc_handle(ipc_handle, event["metadata"]) as tensor:
+        pass
+    ```
+    """
+    handle = handle_buffer.to_pylist()
+    return IpcHandle._rebuild(
+        handle,
+        metadata["size"],
+        json.loads(metadata["source_info"]),
+        metadata["offset"],
+    )
+
+
+@contextmanager
+def open_ipc_handle(
+    ipc_handle: IpcHandle, metadata: dict
+) -> ContextManager[torch.TensorType]:
+    """Open a CUDA IPC handle and return a Pytorch tensor.
+
+    example use:
+    ```python
+    from dora.cuda import ipc_buffer_to_ipc_handle, open_ipc_handle
+
+    event = node.next()
+
+    ipc_handle = ipc_buffer_to_ipc_handle(event["value"], event["metadata"])
+    with open_ipc_handle(ipc_handle, event["metadata"]) as tensor:
+        pass
+    ```
+    """
+    shape = metadata["shape"]
+    strides = metadata["strides"]
+    dtype = metadata["dtype"]
+    try:
+        buffer = ipc_handle.open(get_context())
+        device_arr = DeviceNDArray(shape, strides, dtype, gpu_data=buffer)
+        yield torch.as_tensor(device_arr, device="cuda")
+    finally:
+        ipc_handle.close()

dora_rs-0.3.12.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: dora-rs
+Version: 0.3.12
+Requires-Dist: pyarrow
+Summary: `dora` goal is to be a low latency, composable, and distributed data flow.
+License: MIT
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Source Code, https://github.com/dora-rs/dora/
+
+This crate corresponds to the Node API for Dora.
+
+## Building
+
+To build the Python module for development:
+
+```bash
+uv venv --seed -p 3.11
+uv pip install -e .
+```
+
+## Type hinting
+
+Type hinting requires to run a second step
+
+```bash
+python generate_stubs.py dora dora/__init__.pyi
+maturin develop
+```
+

dora_rs-0.3.12.dist-info/RECORD

@@ -0,0 +1,7 @@
+dora/__init__.py,sha256=mogA09uYFBIwnBnnMfeQtD52ZJbVbWmWo1h70GZj2aU,709
+dora/__init__.pyi,sha256=-jnLcWmFIi8ygYv44-VeYmq4e4I9a5zBHdz5q2Kae-E,9148
+dora/cuda.py,sha256=tsp76SLAeR1gOXoQTTMv4oVHFoSzkXeevEQG41U9xFU,2736
+dora/dora.abi3.so,sha256=NQxlWApQUyX8Vcsnp-b9e94OvIJRqbFeqkUOWOAcn8w,42400832
+dora_rs-0.3.12.dist-info/METADATA,sha256=2Qkm4dNw_2tbfmDk1fxY8l73P33gVA2VtxVZWPTPtjU,625
+dora_rs-0.3.12.dist-info/WHEEL,sha256=_L8nY6bR6hMZmGooZOPKShAbqQfdn4XB7b1iH-rupRI,102
+dora_rs-0.3.12.dist-info/RECORD,,

dora_rs-0.3.12.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.0)
+Root-Is-Purelib: false
+Tag: cp37-abi3-macosx_14_5_arm64