foxglove-sdk 0.14.1__cp312-cp312-musllinux_1_2_i686.whl → 0.16.6__cp312-cp312-musllinux_1_2_i686.whl

foxglove/__init__.py

@@ -5,75 +5,132 @@ See :py:mod:`foxglove.schemas` and :py:mod:`foxglove.channels` for working with
 schemas.
 """
 
+from __future__ import annotations
+
 import atexit
 import logging
-from typing import List, Optional, Union
+from typing import TYPE_CHECKING
 
 from . import _foxglove_py as _foxglove
 
 # Re-export these imports
-from ._foxglove_py import Context, Schema, open_mcap
+from ._foxglove_py import (
+    ChannelDescriptor,
+    Context,
+    Schema,
+    SinkChannelFilter,
+    open_mcap,
+)
 from .channel import Channel, log
 
 # Deprecated. Use foxglove.mcap.MCAPWriter instead.
 from .mcap import MCAPWriter
-from .websocket import (
-    AssetHandler,
-    Capability,
-    ServerListener,
-    Service,
-    WebSocketServer,
-)
+
+if TYPE_CHECKING:
+    from .notebook.notebook_buffer import NotebookBuffer
 
 atexit.register(_foxglove.shutdown)
 
 
-def start_server(
-    *,
-    name: Optional[str] = None,
-    host: Optional[str] = "127.0.0.1",
-    port: Optional[int] = 8765,
-    capabilities: Optional[List[Capability]] = None,
-    server_listener: Optional[ServerListener] = None,
-    supported_encodings: Optional[List[str]] = None,
-    services: Optional[List[Service]] = None,
-    asset_handler: Optional[AssetHandler] = None,
-    context: Optional[Context] = None,
-    session_id: Optional[str] = None,
-) -> WebSocketServer:
-    """
-    Start a websocket server for live visualization.
-
-    :param name: The name of the server.
-    :param host: The host to bind to.
-    :param port: The port to bind to.
-    :param capabilities: A list of capabilities to advertise to clients.
-    :param server_listener: A Python object that implements the :py:class:`websocket.ServerListener`
-        protocol.
-    :param supported_encodings: A list of encodings to advertise to clients.
-    :param services: A list of services to advertise to clients.
-    :param asset_handler: A callback function that returns the asset for a given URI, or None if it
-        doesn't exist.
-    :param context: The context to use for logging. If None, the global context is used.
-    :param session_id: An ID which allows the client to understand if the connection is a
-        re-connection or a new server instance. If None, then an ID is generated based on the
-        current time.
-    """
-    return _foxglove.start_server(
-        name=name,
-        host=host,
-        port=port,
-        capabilities=capabilities,
-        server_listener=server_listener,
-        supported_encodings=supported_encodings,
-        services=services,
-        asset_handler=asset_handler,
-        context=context,
-        session_id=session_id,
+try:
+    from ._foxglove_py.cloud import CloudSink
+
+    # from ._foxglove_py.cloud import start_cloud_sink as _start_cloud_sink
+    from .cloud import CloudSinkListener
+    from .websocket import (
+        AssetHandler,
+        Capability,
+        ServerListener,
+        Service,
+        WebSocketServer,
     )
 
+    def start_server(
+        *,
+        name: str | None = None,
+        host: str | None = "127.0.0.1",
+        port: int | None = 8765,
+        capabilities: list[Capability] | None = None,
+        server_listener: ServerListener | None = None,
+        supported_encodings: list[str] | None = None,
+        services: list[Service] | None = None,
+        asset_handler: AssetHandler | None = None,
+        context: Context | None = None,
+        session_id: str | None = None,
+        channel_filter: SinkChannelFilter | None = None,
+        playback_time_range: tuple[int, int] | None = None,
+    ) -> WebSocketServer:
+        """
+        Start a websocket server for live visualization.
+
+        :param name: The name of the server.
+        :param host: The host to bind to.
+        :param port: The port to bind to.
+        :param capabilities: A list of capabilities to advertise to clients.
+        :param server_listener: A Python object that implements the
+            :py:class:`websocket.ServerListener` protocol.
+        :param supported_encodings: A list of encodings to advertise to clients.
+        :param services: A list of services to advertise to clients.
+        :param asset_handler: A callback function that returns the asset for a given URI, or None if
+            it doesn't exist.
+        :param context: The context to use for logging. If None, the global context is used.
+        :param session_id: An ID which allows the client to understand if the connection is a
+            re-connection or a new server instance. If None, then an ID is generated based on the
+            current time.
+        :param channel_filter: A `Callable` that determines whether a channel should be logged to.
+            Return `True` to log the channel, or `False` to skip it. By default, all channels
+            will be logged.
+        :param playback_time_range: Time range of data being played back, in absolute nanoseconds.
+            Implies `Capability.RangedPlayback` if set.
+        """
+        return _foxglove.start_server(
+            name=name,
+            host=host,
+            port=port,
+            capabilities=capabilities,
+            server_listener=server_listener,
+            supported_encodings=supported_encodings,
+            services=services,
+            asset_handler=asset_handler,
+            context=context,
+            session_id=session_id,
+            channel_filter=channel_filter,
+            playback_time_range=playback_time_range,
+        )
+
+    def start_cloud_sink(
+        *,
+        listener: CloudSinkListener | None = None,
+        supported_encodings: list[str] | None = None,
+        context: Context | None = None,
+        session_id: str | None = None,
+    ) -> CloudSink:
+        """
+        Connect to Foxglove Agent for live visualization and teleop.
+
+        Foxglove Agent must be running on the same host for this to work.
+
+        :param capabilities: A list of capabilities to advertise to the agent.
+        :param listener: A Python object that implements the
+            :py:class:`cloud.CloudSinkListener` protocol.
+        :param supported_encodings: A list of encodings to advertise to the agent.
+        :param context: The context to use for logging. If None, the global context is used.
+        :param session_id: An ID which allows the agent to understand if the connection is a
+            re-connection or a new connection instance. If None, then an ID is generated based on
+            the current time.
+        """
+        return _foxglove.start_cloud_sink(
+            listener=listener,
+            supported_encodings=supported_encodings,
+            context=context,
+            session_id=session_id,
+        )
 
-def set_log_level(level: Union[int, str] = "INFO") -> None:
+except ImportError:
+    pass
+
+
+def set_log_level(level: int | str = "INFO") -> None:
     """
     Enable SDK logging.
 
@@ -117,13 +174,68 @@ def _level_names() -> dict[str, int]:
     }
 
 
+def init_notebook_buffer(context: Context | None = None) -> NotebookBuffer:
+    """
+    Create a NotebookBuffer object to manage data buffering and visualization in Jupyter notebooks.
+
+    The NotebookBuffer object will buffer all data logged to the provided context. When you are
+    ready to visualize the data, you can call the
+    :meth:`~notebook.notebook_buffer.NotebookBuffer.show` method to display an embedded Foxglove
+    visualization widget. The widget provides a fully-featured Foxglove interface directly within
+    your Jupyter notebook, allowing you to explore multi-modal robotics data including 3D scenes,
+    plots, images, and more.
+
+    :param context: The Context used to log the messages. If no Context is provided, the global
+        context will be used. Logged messages will be buffered.
+
+    :returns: A NotebookBuffer object that can be used to manage the data buffering and
+        visualization.
+
+    :raises Exception: If the notebook extra package is not installed. Install it with ``pip install
+        foxglove-sdk[notebook]``.
+
+    :note: This function is only available when the `notebook` extra package is installed. Install
+        it with ``pip install foxglove-sdk[notebook]``.
+
+    Example:
+        >>> import foxglove
+        >>>
+        >>> # Create a basic viewer using the default context
+        >>> nb_buffer = foxglove.init_notebook_buffer()
+        >>>
+        >>> # Or use a specific context
+        >>> nb_buffer = foxglove.init_notebook_buffer(context=my_ctx)
+        >>>
+        >>> # ... log data as usual ...
+        >>>
+        >>> # Display the widget in the notebook
+        >>> nb_buffer.show()
+    """
+    try:
+        from .notebook.notebook_buffer import NotebookBuffer
+
+    except ImportError:
+        raise Exception(
+            "NotebookBuffer is not installed. "
+            'Please install it with `pip install "foxglove-sdk[notebook]"`'
+        )
+
+    return NotebookBuffer(context=context)
+
+
 __all__ = [
     "Channel",
+    "ChannelDescriptor",
     "Context",
     "MCAPWriter",
     "Schema",
+    "SinkChannelFilter",
+    "CloudSink",
+    "CloudSinkListener",
+    "start_cloud_sink",
     "log",
     "open_mcap",
     "set_log_level",
     "start_server",
+    "init_notebook_buffer",
 ]

foxglove/_foxglove_py/__init__.pyi

@@ -1,21 +1,42 @@
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, BinaryIO, Callable, Protocol
 
+from foxglove.websocket import AssetHandler
+
+class McapWritable(Protocol):
+    """A writable and seekable file-like object.
+
+    This protocol defines the minimal interface required for writing MCAP data.
+    """
+
+    def write(self, data: bytes | bytearray) -> int:
+        """Write data and return the number of bytes written."""
+        ...
+
+    def seek(self, offset: int, whence: int = 0) -> int:
+        """Seek to position and return the new absolute position."""
+        ...
+
+    def flush(self) -> None:
+        """Flush any buffered data."""
+        ...
+
+from .cloud import CloudSink
 from .mcap import MCAPWriteOptions, MCAPWriter
-from .websocket import AssetHandler, Capability, Service, WebSocketServer
+from .websocket import Capability, Service, WebSocketServer
 
 class BaseChannel:
     """
     A channel for logging messages.
     """
 
-    def __new__(
-        cls,
+    def __init__(
+        self,
         topic: str,
         message_encoding: str,
-        schema: Optional["Schema"] = None,
-        metadata: Optional[Dict[str, str]] = None,
-    ) -> "BaseChannel": ...
+        schema: "Schema" | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> None: ...
     def id(self) -> int:
         """The unique ID of the channel"""
         ...
@@ -29,7 +50,7 @@ class BaseChannel:
         """The message encoding for the channel"""
         ...
 
-    def metadata(self) -> Dict[str, str]:
+    def metadata(self) -> dict[str, str]:
         """
         Returns a copy of the channel's metadata.
 
@@ -38,7 +59,7 @@ class BaseChannel:
         """
         ...
 
-    def schema(self) -> Optional["Schema"]:
+    def schema(self) -> "Schema" | None:
         """
         Returns a copy of the channel's schema.
 
@@ -47,7 +68,7 @@ class BaseChannel:
         """
         ...
 
-    def schema_name(self) -> Optional[str]:
+    def schema_name(self) -> str | None:
         """The name of the schema for the channel"""
         ...
 
@@ -58,8 +79,8 @@ class BaseChannel:
     def log(
         self,
         msg: bytes,
-        log_time: Optional[int] = None,
-        sink_id: Optional[int] = None,
+        log_time: int | None = None,
+        sink_id: int | None = None,
     ) -> None:
         """
         Log a message to the channel.
@@ -82,13 +103,13 @@ class Schema:
     encoding: str
     data: bytes
 
-    def __new__(
-        cls,
+    def __init__(
+        self,
         *,
         name: str,
         encoding: str,
         data: bytes,
-    ) -> "Schema": ...
+    ) -> None: ...
 
 class Context:
     """
@@ -100,37 +121,71 @@ class Context:
     channel constructor and to :py:func:`open_mcap` or :py:func:`start_server`.
     """
 
-    def __new__(cls) -> "Context": ...
+    def __init__(self) -> None: ...
     def _create_channel(
         self,
         topic: str,
         message_encoding: str,
-        schema: Optional["Schema"] = None,
-        metadata: Optional[List[Tuple[str, str]]] = None,
+        schema: Schema | None = None,
+        metadata: list[tuple[str, str]] | None = None,
     ) -> "BaseChannel":
         """
         Instead of calling this method, pass a context to a channel constructor.
         """
         ...
 
+    @staticmethod
+    def default() -> "Context":
+        """
+        Returns the default context.
+        """
+        ...
+
+class ChannelDescriptor:
+    """
+    Information about a channel
+    """
+
+    id: int
+    topic: str
+    message_encoding: str
+    metadata: dict[str, str]
+    schema: "Schema" | None
+
+SinkChannelFilter = Callable[[ChannelDescriptor], bool]
+
 def start_server(
     *,
-    name: Optional[str] = None,
-    host: Optional[str] = "127.0.0.1",
-    port: Optional[int] = 8765,
-    capabilities: Optional[List[Capability]] = None,
+    name: str | None = None,
+    host: str | None = "127.0.0.1",
+    port: int | None = 8765,
+    capabilities: list[Capability] | None = None,
     server_listener: Any = None,
-    supported_encodings: Optional[List[str]] = None,
-    services: Optional[List["Service"]] = None,
-    asset_handler: Optional["AssetHandler"] = None,
-    context: Optional["Context"] = None,
-    session_id: Optional[str] = None,
+    supported_encodings: list[str] | None = None,
+    services: list[Service] | None = None,
+    asset_handler: AssetHandler | None = None,
+    context: Context | None = None,
+    session_id: str | None = None,
+    channel_filter: SinkChannelFilter | None = None,
+    playback_time_range: tuple[int, int] | None = None,
 ) -> WebSocketServer:
     """
     Start a websocket server for live visualization.
     """
     ...
 
+def start_cloud_sink(
+    *,
+    listener: Any = None,
+    supported_encodings: list[str] | None = None,
+    context: Context | None = None,
+    session_id: str | None = None,
+) -> CloudSink:
+    """
+    Connect to Foxglove Agent for remote visualization and teleop.
+    """
+    ...
+
 def enable_logging(level: int) -> None:
     """
     Forward SDK logs to python's logging facility.
@@ -150,21 +205,28 @@ def shutdown() -> None:
     ...
 
 def open_mcap(
-    path: str | Path,
+    path: str | Path | BinaryIO | McapWritable,
     *,
     allow_overwrite: bool = False,
-    context: Optional["Context"] = None,
-    writer_options: Optional[MCAPWriteOptions] = None,
+    context: Context | None = None,
+    channel_filter: SinkChannelFilter | None = None,
+    writer_options: MCAPWriteOptions | None = None,
 ) -> MCAPWriter:
     """
-    Creates a new MCAP file for recording.
+    Open an MCAP writer for recording.
+
+    If a path is provided, the file will be created and must not already exist (unless
+    allow_overwrite is True). If a file-like object is provided, it must support write(),
+    seek(), and flush() methods; the allow_overwrite parameter is ignored.
 
     If a context is provided, the MCAP file will be associated with that context. Otherwise, the
     global context will be used.
+
+    You must close the writer with close() or the with statement to ensure the file is correctly finished.
     """
     ...
 
-def get_channel_for_topic(topic: str) -> Optional[BaseChannel]:
+def get_channel_for_topic(topic: str) -> BaseChannel | None:
     """
     Get a previously-registered channel.
     """