foxglove-sdk 0.8.1__cp312-cp312-win32.whl → 0.16.3__cp312-cp312-win32.whl

foxglove/__init__.py

@@ -1,124 +1,245 @@
-"""
-This module provides interfaces for logging messages to Foxglove.
-
-See :py:mod:`foxglove.schemas` and :py:mod:`foxglove.channels` for working with well-known Foxglove
-schemas.
-"""
-
-import atexit
-import logging
-from typing import List, Optional, Union
-
-from . import _foxglove_py as _foxglove
-
-# Re-export these imports
-from ._foxglove_py import Context, Schema, 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,
-)
-
-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,
-) -> 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.
-    """
-    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,
-    )
-
-
-def set_log_level(level: Union[int, str] = "INFO") -> None:
-    """
-    Enable SDK logging.
-
-    This function will call logging.basicConfig() for convenience in scripts, but in general you
-    should configure logging yourself before calling this function:
-    https://docs.python.org/3/library/logging.html
-
-    :param level: The logging level to set. This accepts the same values as `logging.setLevel` and
-        defaults to "INFO". The SDK will not log at levels "CRITICAL" or higher.
-    """
-    # This will raise a ValueError for invalid levels if the user has not already configured
-    logging.basicConfig(level=level, format="%(asctime)s [%(levelname)s] %(message)s")
-
-    if isinstance(level, str):
-        level_map = (
-            logging.getLevelNamesMapping()
-            if hasattr(logging, "getLevelNamesMapping")
-            else _level_names()
-        )
-        try:
-            level = level_map[level]
-        except KeyError:
-            raise ValueError(f"Unknown log level: {level}")
-    else:
-        level = max(0, min(2**32 - 1, level))
-
-    _foxglove.enable_logging(level)
-
-
-def _level_names() -> dict[str, int]:
-    # Fallback for Python <3.11; no support for custom levels
-    return {
-        "CRITICAL": logging.CRITICAL,
-        "FATAL": logging.FATAL,
-        "ERROR": logging.ERROR,
-        "WARN": logging.WARNING,
-        "WARNING": logging.WARNING,
-        "INFO": logging.INFO,
-        "DEBUG": logging.DEBUG,
-        "NOTSET": logging.NOTSET,
-    }
-
-
-__all__ = [
-    "Channel",
-    "Context",
-    "MCAPWriter",
-    "Schema",
-    "log",
-    "open_mcap",
-    "set_log_level",
-    "start_server",
-]
+"""
+This module provides interfaces for logging messages to Foxglove.
+
+See :py:mod:`foxglove.schemas` and :py:mod:`foxglove.channels` for working with well-known Foxglove
+schemas.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+from typing import TYPE_CHECKING
+
+from . import _foxglove_py as _foxglove
+
+# Re-export these imports
+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
+
+if TYPE_CHECKING:
+    from .notebook.notebook_buffer import NotebookBuffer
+
+atexit.register(_foxglove.shutdown)
+
+
+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,
+        )
+
+except ImportError:
+    pass
+
+
+def set_log_level(level: int | str = "INFO") -> None:
+    """
+    Enable SDK logging.
+
+    This function will call logging.basicConfig() for convenience in scripts, but in general you
+    should configure logging yourself before calling this function:
+    https://docs.python.org/3/library/logging.html
+
+    :param level: The logging level to set. This accepts the same values as `logging.setLevel` and
+        defaults to "INFO". The SDK will not log at levels "CRITICAL" or higher.
+    """
+    # This will raise a ValueError for invalid levels if the user has not already configured
+    logging.basicConfig(level=level, format="%(asctime)s [%(levelname)s] %(message)s")
+
+    if isinstance(level, str):
+        level_map = (
+            logging.getLevelNamesMapping()
+            if hasattr(logging, "getLevelNamesMapping")
+            else _level_names()
+        )
+        try:
+            level = level_map[level]
+        except KeyError:
+            raise ValueError(f"Unknown log level: {level}")
+    else:
+        level = max(0, min(2**32 - 1, level))
+
+    _foxglove.enable_logging(level)
+
+
+def _level_names() -> dict[str, int]:
+    # Fallback for Python <3.11; no support for custom levels
+    return {
+        "CRITICAL": logging.CRITICAL,
+        "FATAL": logging.FATAL,
+        "ERROR": logging.ERROR,
+        "WARN": logging.WARNING,
+        "WARNING": logging.WARNING,
+        "INFO": logging.INFO,
+        "DEBUG": logging.DEBUG,
+        "NOTSET": logging.NOTSET,
+    }
+
+
+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",
+]