foxglove-sdk 0.5.0__cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl → 0.16.3__cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl

foxglove/__init__.py

@@ -5,68 +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 (
-    MCAPWriter,
+    ChannelDescriptor,
+    Context,
     Schema,
+    SinkChannelFilter,
     open_mcap,
 )
 from .channel import Channel, log
-from .websocket import (
-    AssetHandler,
-    Capability,
-    ServerListener,
-    Service,
-    WebSocketServer,
-)
+
+# Deprecated. Use foxglove.mcap.MCAPWriter instead.
+from .mcap import MCAPWriter
+
+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,
-) -> 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.
-    """
-    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,
+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.
 
@@ -110,12 +174,72 @@ 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:`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.
+
+    Args:
+        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:
+        NotebookBuffer: 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,53 +1,97 @@
 from pathlib import Path
-from typing import Any, List, Optional, Tuple
+from typing import Any, BinaryIO, Callable, Protocol
 
-from .websocket import AssetHandler, Capability, Service, WebSocketServer
+from foxglove.websocket import AssetHandler
 
-class MCAPWriter:
-    """
-    A writer for logging messages to an MCAP file.
-
-    Obtain an instance by calling :py:func:`open_mcap`.
-
-    This class may be used as a context manager, in which case the writer will
-    be closed when you exit the context.
+class McapWritable(Protocol):
+    """A writable and seekable file-like object.
 
-    If the writer is not closed by the time it is garbage collected, it will be
-    closed automatically, and any errors will be logged.
+    This protocol defines the minimal interface required for writing MCAP data.
     """
 
-    def __new__(cls) -> "MCAPWriter": ...
-    def __enter__(self) -> "MCAPWriter": ...
-    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None: ...
-    def close(self) -> None:
-        """
-        Close the writer explicitly.
+    def write(self, data: bytes | bytearray) -> int:
+        """Write data and return the number of bytes written."""
+        ...
 
-        You may call this to explicitly close the writer. Note that the writer
-        will be automatically closed when it is garbage-collected, or when
-        exiting the context manager.
-        """
+    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 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[List[Tuple[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"""
+        ...
+
+    def topic(self) -> str:
+        """The topic name of the channel"""
+        ...
+
+    @property
+    def message_encoding(self) -> str:
+        """The message encoding for the channel"""
+        ...
+
+    def metadata(self) -> dict[str, str]:
+        """
+        Returns a copy of the channel's metadata.
+
+        Note that changes made to the returned dictionary will not be applied to
+        the channel's metadata.
+        """
+        ...
+
+    def schema(self) -> "Schema" | None:
+        """
+        Returns a copy of the channel's schema.
+
+        Note that changes made to the returned object will not be applied to
+        the channel's schema.
+        """
+        ...
+
+    def schema_name(self) -> str | None:
+        """The name of the schema for the channel"""
+        ...
+
+    def has_sinks(self) -> bool:
+        """Returns true if at least one sink is subscribed to this channel"""
+        ...
+
     def log(
         self,
         msg: bytes,
-        publish_time: Optional[int] = None,
-        log_time: Optional[int] = None,
-        sequence: Optional[int] = None,
-    ) -> None: ...
+        log_time: int | None = None,
+        sink_id: int | None = None,
+    ) -> None:
+        """
+        Log a message to the channel.
+
+        :param msg: The message to log.
+        :param log_time: The optional time the message was logged.
+        :param sink_id: The sink ID to log the message to. If not provided, the message will be
+            sent to all sinks.
+        """
+        ...
+
     def close(self) -> None: ...
 
 class Schema:
@@ -59,30 +103,89 @@ class Schema:
     encoding: str
     data: bytes
 
-    def __new__(
-        cls,
+    def __init__(
+        self,
         *,
         name: str,
         encoding: str,
         data: bytes,
-    ) -> "Schema": ...
+    ) -> None: ...
+
+class Context:
+    """
+    A context for logging messages.
+
+    A context is the binding between channels and sinks. By default, the SDK will use a single
+    global context for logging, but you can create multiple contexts in order to log to different
+    topics to different sinks or servers. To do so, associate the context by passing it to the
+    channel constructor and to :py:func:`open_mcap` or :py:func:`start_server`.
+    """
+
+    def __init__(self) -> None: ...
+    def _create_channel(
+        self,
+        topic: str,
+        message_encoding: str,
+        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,
+    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.
@@ -101,17 +204,29 @@ def shutdown() -> None:
     """
     ...
 
-def open_mcap(path: str | Path, allow_overwrite: bool = False) -> MCAPWriter:
+def open_mcap(
+    path: str | Path | BinaryIO | McapWritable,
+    *,
+    allow_overwrite: bool = False,
+    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.
 
-    :param path: The path to the MCAP file. This file will be created and must not already exist.
-    :param allow_overwrite: Set this flag in order to overwrite an existing file at this path.
-    :rtype: :py:class:`MCAPWriter`
+    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) -> BaseChannel:
+def get_channel_for_topic(topic: str) -> BaseChannel | None:
     """
     Get a previously-registered channel.
     """