foxglove-sdk 0.1.2__cp311-cp311-macosx_10_12_x86_64.whl → 0.15.3__cp311-cp311-macosx_10_12_x86_64.whl

foxglove/__init__.py

@@ -1,63 +1,241 @@
+"""
+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
-from typing import Union
-from google.protobuf.message import Message
+import logging
+from typing import TYPE_CHECKING
+
+from . import _foxglove_py as _foxglove
+
+# Re-export these imports
 from ._foxglove_py import (
-    record_file,
-    enable_log_forwarding,
-    disable_log_forwarding,
-    start_server,
-    shutdown,
+    ChannelDescriptor,
+    Context,
+    Schema,
+    SinkChannelFilter,
+    open_mcap,
 )
-from .encoding import Encoder, ProtobufEncoder, JsonEncoder
-from .channel import Channel
+from .channel import Channel, log
 
-import logging
+# Deprecated. Use foxglove.mcap.MCAPWriter instead.
+from .mcap import MCAPWriter
 
-logging.basicConfig(
-    level=logging.DEBUG, format="%(asctime)s [%(levelname)s] %(message)s"
-)
+if TYPE_CHECKING:
+    from .notebook.notebook_buffer import NotebookBuffer
 
-atexit.register(shutdown)
+atexit.register(_foxglove.shutdown)
 
 
-def log_level_from_int(level: int) -> str:
-    log_levels = {10: "debug", 20: "info", 30: "warn", 40: "error"}
-    return log_levels.get(level, "unknown")
+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 verbose_on(level: Union[int, str] = "debug") -> None:
-    if isinstance(level, int):
-        assert level in [
-            logging.DEBUG,
-            logging.INFO,
-            logging.WARN,
-            logging.ERROR,
-        ], ValueError("Invalid log level")
-        level = log_level_from_int(level)
-    else:
-        assert level in ["debug", "info", "warn", "error"], ValueError(
-            "Invalid log level"
+    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,
+    ) -> 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.
+        """
+        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,
+        )
+
+    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()
         )
-    logging.debug(f"SDK logging enabled ({level.upper()})")
-    enable_log_forwarding(level)
+        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.
 
-def verbose_off() -> None:
-    logging.debug("SDK logging disabled")
-    disable_log_forwarding()
+    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.
 
-def log(topic: str, proto_msg: Message) -> None: ...
+    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",
-    "start_server",
-    "record_file",
-    "Encoder",
-    "ProtobufEncoder",
-    "JsonEncoder",
-    "verbose_on",
-    "verbose_off",
+    "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

@@ -0,0 +1,210 @@
+from pathlib import Path
+from typing import Any, Callable
+
+from foxglove.websocket import AssetHandler
+
+from .cloud import CloudSink
+from .mcap import MCAPWriteOptions, MCAPWriter
+from .websocket import Capability, Service, WebSocketServer
+
+class BaseChannel:
+    """
+    A channel for logging messages.
+    """
+
+    def __init__(
+        self,
+        topic: str,
+        message_encoding: str,
+        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,
+        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:
+    """
+    A schema for a message or service call.
+    """
+
+    name: str
+    encoding: str
+    data: bytes
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        encoding: str,
+        data: bytes,
+    ) -> 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: 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: 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,
+) -> 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.
+    """
+    ...
+
+def disable_logging() -> None:
+    """
+    Stop forwarding SDK logs.
+    """
+    ...
+
+def shutdown() -> None:
+    """
+    Shutdown the running websocket server.
+    """
+    ...
+
+def open_mcap(
+    path: str | Path,
+    *,
+    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.
+
+    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) -> BaseChannel | None:
+    """
+    Get a previously-registered channel.
+    """
+    ...