foxglove-sdk 0.14.2__cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl → 0.16.1__cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl

foxglove/__init__.py

@@ -9,20 +9,34 @@ 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 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
 
+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,
@@ -43,6 +57,7 @@ try:
         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.
@@ -61,6 +76,9 @@ try:
         :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,
@@ -73,6 +91,35 @@ try:
             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:
@@ -123,13 +170,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,8 +1,9 @@
 from pathlib import Path
-from typing import Any
+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
 
@@ -15,7 +16,7 @@ class BaseChannel:
         self,
         topic: str,
         message_encoding: str,
-        schema: Schema | None = None,
+        schema: "Schema" | None = None,
         metadata: dict[str, str] | None = None,
     ) -> None: ...
     def id(self) -> int:
@@ -115,6 +116,26 @@ class Context:
         """
         ...
 
+    @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,
@@ -127,12 +148,25 @@ def start_server(
     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.
@@ -156,6 +190,7 @@ def open_mcap(
     *,
     allow_overwrite: bool = False,
     context: Context | None = None,
+    channel_filter: SinkChannelFilter | None = None,
     writer_options: MCAPWriteOptions | None = None,
 ) -> MCAPWriter:
     """
@@ -163,6 +198,8 @@ def open_mcap(
 
     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.
     """
     ...
 

foxglove/_foxglove_py/cloud.pyi

@@ -0,0 +1,9 @@
+class CloudSink:
+    """
+    A cloud sink for remote visualization and teleop.
+    """
+
+    def __init__(self) -> None: ...
+    def stop(self) -> None:
+        """Gracefully disconnect from the cloud sink, waiting for shutdown to complete."""
+        ...

foxglove/_foxglove_py/mcap.pyi

@@ -82,3 +82,15 @@ class MCAPWriter:
         exiting the context manager.
         """
         ...
+
+    def write_metadata(self, name: str, metadata: dict[str, str]) -> None:
+        """
+        Write metadata to the MCAP file.
+
+        Metadata consists of key-value string pairs associated with a name.
+        If the metadata dictionary is empty, this method does nothing.
+
+        :param name: Name identifier for this metadata record
+        :param metadata: Dictionary of key-value pairs to store
+        """
+        ...

foxglove/_foxglove_py/websocket.pyi

@@ -15,7 +15,7 @@ class Capability(Enum):
     ClientPublish = ...
     """Allow clients to advertise channels to send data messages to the server."""
 
-    Connectiongraph = ...
+    ConnectionGraph = ...
     """Allow clients to subscribe and make connection graph updates"""
 
     Parameters = ...

foxglove/cloud.py

@@ -0,0 +1,61 @@
+from typing import Protocol
+
+from ._foxglove_py.websocket import (
+    ChannelView,
+    Client,
+    ClientChannel,
+)
+
+
+class CloudSinkListener(Protocol):
+    """
+    A mechanism to register callbacks for handling client message events.
+    """
+
+    def on_subscribe(self, client: Client, channel: ChannelView) -> None:
+        """
+        Called when a client subscribes to a channel.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The channel (id, topic) that the message was sent on.
+        """
+        return None
+
+    def on_unsubscribe(self, client: Client, channel: ChannelView) -> None:
+        """
+        Called when a client unsubscribes from a channel or disconnects.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The channel (id, topic) that the message was sent on.
+        """
+        return None
+
+    def on_client_advertise(self, client: Client, channel: ClientChannel) -> None:
+        """
+        Called when a client advertises a channel.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The client channel that is being advertised.
+        """
+        return None
+
+    def on_client_unadvertise(self, client: Client, client_channel_id: int) -> None:
+        """
+        Called when a client unadvertises a channel.
+
+        :param client: The client (id) that is unadvertising the channel.
+        :param client_channel_id: The client channel id that is being unadvertised.
+        """
+        return None
+
+    def on_message_data(
+        self, client: Client, client_channel_id: int, data: bytes
+    ) -> None:
+        """
+        Called when a message is received from a client.
+
+        :param client: The client (id) that sent the message.
+        :param client_channel_id: The client channel id that the message was sent on.
+        :param data: The message data.
+        """
+        return None

foxglove/notebook/foxglove_widget.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import pathlib
+from typing import TYPE_CHECKING, Any, Literal
+
+import anywidget
+import traitlets
+
+if TYPE_CHECKING:
+    from .notebook_buffer import NotebookBuffer
+
+
+class FoxgloveWidget(anywidget.AnyWidget):
+    """
+    A widget that displays a Foxglove viewer in a notebook.
+
+    :param buffer: The NotebookBuffer object that contains the data to display in the widget.
+    :param layout_storage_key: The storage key of the layout to use for the widget.
+    :param width: The width of the widget. Defaults to "full".
+    :param height: The height of the widget in pixels. Defaults to 500.
+    :param src: The source URL of the Foxglove viewer. Defaults to "https://embed.foxglove.dev/".
+    """
+
+    _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
+    width = traitlets.Union(
+        [traitlets.Int(), traitlets.Enum(values=["full"])], default_value="full"
+    ).tag(sync=True)
+    height = traitlets.Int(default_value=500).tag(sync=True)
+    src = traitlets.Unicode(default_value=None, allow_none=True).tag(sync=True)
+    _layout_params = traitlets.Dict(
+        per_key_traits={
+            "storage_key": traitlets.Unicode(),
+            "opaque_layout": traitlets.Dict(allow_none=True, default_value=None),
+            "force": traitlets.Bool(False),
+        },
+        allow_none=True,
+        default_value=None,
+    ).tag(sync=True)
+
+    def __init__(
+        self,
+        buffer: NotebookBuffer,
+        layout_storage_key: str,
+        width: int | Literal["full"] | None = None,
+        height: int | None = None,
+        src: str | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        if width is not None:
+            self.width = width
+        else:
+            self.width = "full"
+        if height is not None:
+            self.height = height
+        if src is not None:
+            self.src = src
+
+        self.select_layout(layout_storage_key, **kwargs)
+
+        # Callback to get the data to display in the widget
+        self._buffer = buffer
+        # Keep track of when the widget is ready to receive data
+        self._ready = False
+        # Pending data to be sent when the widget is ready
+        self._pending_data: list[bytes] = []
+        self.on_msg(self._handle_custom_msg)
+        self.refresh()
+
+    def select_layout(self, storage_key: str, **kwargs: Any) -> None:
+        """
+        Select a layout in the Foxglove viewer.
+        """
+        opaque_layout = kwargs.get("opaque_layout", None)
+        force_layout = kwargs.get("force_layout", False)
+
+        self._layout_params = {
+            "storage_key": storage_key,
+            "opaque_layout": opaque_layout if isinstance(opaque_layout, dict) else None,
+            "force": force_layout,
+        }
+
+    def refresh(self) -> None:
+        """
+        Refresh the widget by getting the data from the callback function and sending it
+        to the widget.
+        """
+        data = self._buffer.get_data()
+        if not self._ready:
+            self._pending_data = data
+        else:
+            self.send({"type": "update-data"}, data)
+
+    def _handle_custom_msg(self, msg: dict, buffers: list[bytes]) -> None:
+        if msg["type"] == "ready":
+            self._ready = True
+
+            if len(self._pending_data) > 0:
+                self.send({"type": "update-data"}, self._pending_data)
+                self._pending_data = []

foxglove/notebook/notebook_buffer.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import uuid
+from tempfile import TemporaryDirectory
+from typing import Any, Literal
+
+from mcap.reader import make_reader
+
+from .._foxglove_py import Context, open_mcap
+from .foxglove_widget import FoxgloveWidget
+
+
+class NotebookBuffer:
+    """
+    A data buffer to collect and manage messages 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.
+
+    :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.
+    """
+
+    def __init__(self, context: Context | None = None):
+        """
+        Initialize a new NotebookBuffer for collecting logged messages.
+        """
+        # We need to keep the temporary directory alive until the writer is closed
+        self._temp_directory = TemporaryDirectory()
+        self._context = context
+        self._files: list[str] = []
+        self._create_writer()
+
+    def show(
+        self,
+        layout_storage_key: str,
+        width: int | Literal["full"] | None = None,
+        height: int | None = None,
+        src: str | None = None,
+        **kwargs: Any,
+    ) -> FoxgloveWidget:
+        """
+        Show the Foxglove viewer. Call this method as the last step of a notebook cell
+        to display the viewer.
+        """
+        widget = FoxgloveWidget(
+            buffer=self,
+            width=width,
+            height=height,
+            src=src,
+            layout_storage_key=layout_storage_key,
+            **kwargs,
+        )
+        return widget
+
+    def clear(self) -> None:
+        """
+        Clear the buffered data.
+        """
+        self._writer.close()
+        # Delete the temporary directory and all its contents
+        self._temp_directory.cleanup()
+        # Reset files list
+        self._files = []
+        # Create a new temporary directory
+        self._temp_directory = TemporaryDirectory()
+        self._create_writer()
+
+    def get_data(self) -> list[bytes]:
+        """
+        Retrieve all collected data.
+        """
+        # close the current writer
+        self._writer.close()
+
+        if len(self._files) > 1:
+            if is_mcap_empty(self._files[-1]):
+                # If the last file is empty, remove the last file since it won't add any new data
+                # to the buffer
+                os.remove(self._files[-1])
+                self._files.pop()
+            elif is_mcap_empty(self._files[0]):
+                # If the first file is empty, remove the first file since it won't add any new data
+                # to the buffer
+                os.remove(self._files[0])
+                self._files.pop(0)
+
+        # read the content of the files
+        contents: list[bytes] = []
+        for file_name in self._files:
+            with open(file_name, "rb") as f_read:
+                contents.append(f_read.read())
+
+        self._create_writer()
+
+        return contents
+
+    def _create_writer(self) -> None:
+        random_id = uuid.uuid4().hex[:8]
+        file_name = f"{self._temp_directory.name}/log-{random_id}.mcap"
+        self._files.append(file_name)
+        self._writer = open_mcap(path=file_name, context=self._context)
+
+
+def is_mcap_empty(file_name: str) -> bool:
+    with open(file_name, "rb") as f_read:
+        iter = make_reader(f_read).iter_messages()
+        is_empty = next(iter, None) is None
+
+    return is_empty

foxglove/notebook/static/widget.js

@@ -0,0 +1 @@
+var y=EventTarget,p="https://embed.foxglove.dev/",g="foxglove.default-layout";function c(){let t,e;return{promise:new Promise((s,i)=>{t=s,e=i}),resolve:t,reject:e}}var h=class extends y{#e;#i;#h;#r=!1;#n;#t={dataSource:void 0,selectLayout:void 0,extension:[]};#a;#s=!1;constructor(e){super();let{parent:a,src:s,orgSlug:i,initialDataSource:o,initialLayout:n,initialLayoutParams:r,initialExtensions:l,colorScheme:d="auto"}=e;this.#h=i,this.#n=c();let u=s??p;try{this.#i=new URL(u)}catch{throw new Error(`[FoxgloveViewer] Invalid server URL: ${u}`)}window.addEventListener("message",this.#d),o&&this.setDataSource(o),n!=null&&r==null&&this.setLayoutData(n),r!=null&&this.selectLayout(r),l&&this.installExtensions(l),this.#e=document.createElement("iframe"),this.#e.src=u,this.#e.title="Foxglove",this.#e.allow="cross-origin-isolated",this.#e.style.width="100%",this.#e.style.height="100%",this.#e.style.border="none",this.setColorScheme(d),a.appendChild(this.#e)}setDataSource(e){this.#l({type:"set-data-source",payload:e})}selectLayout(e){this.#l({type:"select-layout",payload:e})}async getLayout(){return this.#a||(this.#a=c(),await this.#n.promise,this.#o({type:"get-layout"})),await this.#a.promise}setLayoutData(e){this.selectLayout({storageKey:g,opaqueLayout:e,force:!0})}installExtensions(e){this.#l({type:"install-extension",payload:e})}isReady(){return this.#r}destroy(){this.#s=!0,this.#e.remove(),window.removeEventListener("message",this.#d)}isDestroyed(){return this.#s}setColorScheme(e){this.#e.style.colorScheme=e==="auto"?"normal":e}#l(e){switch(e.type){case"install-extension":this.#t.extension.push(e);break;case"set-data-source":this.#t.dataSource=e;break;case"select-layout":this.#t.selectLayout=e;break}this.#r&&this.#o(e)}#o(e){if(this.#s){console.warn("[FoxgloveViewer] Unable to post command. Frame has been destroyed.");return}f(this.#e.contentWindow,"Invariant: iframe should be loaded."),this.#e.contentWindow.postMessage(e,this.#i.href)}#d=e=>{let a=new URL(e.origin);if(!(e.source!==this.#e.contentWindow||a.href!==this.#i.href)){if(this.#s){console.warn("[FoxgloveViewer] Unable to handle message. Frame has been destroyed.");return}switch(e.data.type){case"foxglove-origin-request":this.#o({type:"origin-ack"});break;case"foxglove-handshake-request":this.#r=!0,this.#n.resolve(),this.#o({type:"handshake-ack",payload:{orgSlug:this.#h,initialDataSource:this.#t.dataSource?.payload,initialLayoutParams:this.#t.selectLayout?.payload,initialExtensions:this.#t.extension.flatMap(s=>s.payload)}});break;case"foxglove-handshake-complete":this.dispatchEvent(new Event("ready"));break;case"foxglove-error":this.dispatchEvent(new CustomEvent("error",{detail:e.data.payload}));break;case"foxglove-layout-data":this.#a?(this.#a.resolve(e.data.payload),this.#a=void 0):console.warn("[FoxgloveViewer] Received layout but getLayout was not called.");break;default:console.warn("[FoxgloveViewer] Unhandled message type:",e.data);break}}}};function f(t,e="no additional info provided"){if(!t)throw new Error("Assertion Error: "+e)}function w({model:t,el:e}){let a=document.createElement("div"),s=t.get("_layout_params"),i=new h({parent:a,src:t.get("src"),orgSlug:void 0,initialLayoutParams:s?{storageKey:s.storage_key,opaqueLayout:s.opaque_layout,force:s.force}:void 0});i.addEventListener("ready",()=>{t.send({type:"ready"})}),t.on("msg:custom",(o,n)=>{if(o.type==="update-data"){let r=n.map((l,d)=>new File([l.buffer],`data-${d}.mcap`));i.setDataSource({type:"file",file:r})}}),a.style.width=t.get("width")==="full"?"100%":`${t.get("width")}px`,a.style.height=`${t.get("height")}px`,t.on("change:width",()=>{a.style.width=t.get("width")==="full"?"100%":`${t.get("width")}px`}),t.on("change:height",()=>{a.style.height=`${t.get("height")}px`}),t.on("change:_layout_params",()=>{let o=t.get("_layout_params");o&&i.selectLayout({storageKey:o.storage_key,opaqueLayout:o.opaque_layout,force:o.force})}),e.appendChild(a)}var b={render:w};export{b as default};

foxglove/tests/test_context.py

@@ -0,0 +1,10 @@
+from foxglove import Context
+
+
+def test_default_context_is_singleton() -> None:
+    assert Context.default() is Context.default()
+
+
+def test_context_is_distinct() -> None:
+    assert Context() is not Context.default()
+    assert Context() is not Context()

foxglove/tests/test_logging.py

@@ -1,4 +1,7 @@
 import logging
+import os
+import subprocess
+import sys
 
 import pytest
 from foxglove import set_log_level
@@ -14,3 +17,46 @@ def test_set_log_level_accepts_string_or_int() -> None:
 def test_set_log_level_clamps_illegal_values() -> None:
     set_log_level(-1)
     set_log_level(2**64)
+
+
+def test_logging_config_with_env() -> None:
+    # Run a script in a child process so logger can be re-initialized from env.
+    test_script = """
+import logging
+import foxglove
+
+logging.basicConfig(level=logging.DEBUG)
+
+server = foxglove.start_server(port=0)
+server.stop()
+
+print("test_init_with_env_complete")
+"""
+
+    # Default: unset
+    env = os.environ.copy()
+    env["FOXGLOVE_LOG_LEVEL"] = ""
+
+    result = subprocess.run(
+        [sys.executable, "-c", test_script],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    assert "test_init_with_env_complete" in result.stdout
+    assert "Started server" in result.stderr
+
+    # Quiet the WS server logging
+    env = os.environ.copy()
+    env["FOXGLOVE_LOG_LEVEL"] = "debug,foxglove::websocket::server=warn"
+
+    result = subprocess.run(
+        [sys.executable, "-c", test_script],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    assert "test_init_with_env_complete" in result.stdout
+    assert "Started server" not in result.stderr

foxglove/tests/test_mcap.py

@@ -2,7 +2,7 @@ from pathlib import Path
 from typing import Callable, Generator, Optional
 
 import pytest
-from foxglove import Channel, Context, open_mcap
+from foxglove import Channel, ChannelDescriptor, Context, open_mcap
 from foxglove.mcap import MCAPWriteOptions
 
 chan = Channel("test", schema={"type": "object"})
@@ -114,3 +114,86 @@ def test_write_to_different_contexts(make_tmp_mcap: Callable[[], Path]) -> None:
     contents2 = tmp_2.read_bytes()
 
     assert len(contents1) < len(contents2)
+
+
+def _verify_metadata_in_file(file_path: Path, expected_metadata: dict) -> None:
+    """Helper function to verify metadata in MCAP file matches expected."""
+    import mcap.reader
+
+    with open(file_path, "rb") as f:
+        reader = mcap.reader.make_reader(f)
+
+        found_metadata = {}
+        metadata_count = 0
+
+        for record in reader.iter_metadata():
+            metadata_count += 1
+            found_metadata[record.name] = dict(record.metadata)
+
+        # Verify count
+        assert metadata_count == len(
+            expected_metadata
+        ), f"Expected {len(expected_metadata)} metadata records, found {metadata_count}"
+
+        # Verify metadata names and content
+        assert set(found_metadata.keys()) == set(
+            expected_metadata.keys()
+        ), "Metadata names don't match"
+
+        for name, expected_kv in expected_metadata.items():
+            assert (
+                found_metadata[name] == expected_kv
+            ), f"Metadata '{name}' has wrong key-value pairs"
+
+
+def test_write_metadata(tmp_mcap: Path) -> None:
+    """Test writing metadata to MCAP file."""
+    # Define expected metadata
+    expected_metadata = {
+        "test1": {"key1": "value1", "key2": "value2"},
+        "test2": {"a": "1", "b": "2"},
+        "test3": {"x": "y", "z": "w"},
+    }
+
+    with open_mcap(tmp_mcap) as writer:
+        # This should not raise an error
+        writer.write_metadata("empty", {})
+
+        # Write basic metadata
+        writer.write_metadata("test1", expected_metadata["test1"])
+
+        # Write multiple metadata records
+        writer.write_metadata("test2", expected_metadata["test2"])
+        writer.write_metadata("test3", expected_metadata["test3"])
+
+        # Write empty metadata (should be skipped)
+        writer.write_metadata("empty_test", {})
+
+        # Log some messages
+        for ii in range(5):
+            chan.log({"foo": ii})
+
+    # Verify metadata was written correctly
+    _verify_metadata_in_file(tmp_mcap, expected_metadata)
+
+
+def test_channel_filter(make_tmp_mcap: Callable[[], Path]) -> None:
+    tmp_1 = make_tmp_mcap()
+    tmp_2 = make_tmp_mcap()
+
+    ch1 = Channel("/1", schema={"type": "object"})
+    ch2 = Channel("/2", schema={"type": "object"})
+
+    def filter(ch: ChannelDescriptor) -> bool:
+        return ch.topic.startswith("/1")
+
+    mcap1 = open_mcap(tmp_1, channel_filter=filter)
+    mcap2 = open_mcap(tmp_2, channel_filter=None)
+
+    ch1.log({})
+    ch2.log({})
+
+    mcap1.close()
+    mcap2.close()
+
+    assert tmp_1.stat().st_size < tmp_2.stat().st_size

foxglove/tests/test_server.py

@@ -17,7 +17,9 @@ def test_server_interface() -> None:
     """
     Exercise the server interface; will also be checked with mypy.
     """
-    server = start_server(port=0, session_id="test-session")
+    server = start_server(
+        port=0, session_id="test-session", channel_filter=lambda _: True
+    )
     assert isinstance(server.port, int)
     assert server.port != 0
 

foxglove/websocket.py

@@ -1,13 +1,7 @@
 from __future__ import annotations
 
-import sys
 from collections.abc import Callable
-from typing import Protocol, Union
-
-if sys.version_info >= (3, 10):
-    from typing import TypeAlias
-else:
-    from typing import Any as TypeAlias
+from typing import Protocol, TypeAlias, Union
 
 from ._foxglove_py.websocket import (
     Capability,

foxglove_sdk-0.16.1.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: foxglove-sdk
+Version: 0.16.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Requires-Dist: anywidget ; extra == 'notebook'
+Requires-Dist: mcap ; extra == 'notebook'
+Requires-Dist: traitlets ; extra == 'notebook'
+Provides-Extra: notebook
+Summary: Foxglove Python SDK
+Author-email: Foxglove <support@foxglove.dev>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: repository, https://github.com/foxglove/foxglove-sdk
+Project-URL: documentation, https://docs.foxglove.dev/
+
+# Foxglove Python SDK
+
+The official [Foxglove](https://docs.foxglove.dev/docs) SDK for Python.
+
+This package provides support for integrating with the Foxglove platform. It can be used to log
+events to local [MCAP](https://mcap.dev/) files or a local visualization server that communicates
+with the Foxglove app.
+
+## Get Started
+
+See https://foxglove.github.io/foxglove-sdk/python/
+
+## Requirements
+
+- Python 3.10+
+
+## Examples
+
+We're using uv as a Python package manager in the foxglove-sdk-examples.
+
+To test that all examples run (as the CI does) you can use `yarn run-python-sdk-examples` in the repo root.
+
+To run a specific example (e.g. write-mcap-file) with local changes:
+
+```
+cd python/foxglove-sdk-examples/write-mcap-file
+uv run --with ../../foxglove-sdk main.py [args]
+```
+
+Keep in mind that uv does two layers of caching.
+There's the .venv in your project directory, plus a global cache at ~/.cache/uv.
+
+uv tries to be smart about not rebuilding things it has already built,
+which means that if you make changes and you want them to show up,
+you also need to run `uv cache clean`.
+

foxglove_sdk-0.16.1.dist-info/RECORD

@@ -0,0 +1,33 @@
+foxglove/__init__.py,sha256=07Fz3ZZJdqsXRl0uKpIOID8ysa1HpQ741pQlvz1yA3I,8222
+foxglove/_foxglove_py.cpython-314-i386-linux-gnu.so,sha256=7wXvtX6aTr5t70xbhB6mJ02UA_ubDdCUx7CK_NtQAL8,6627112
+foxglove/_foxglove_py/__init__.pyi,sha256=lh2gtNThduHDOIO1pQ7NaGnjAPr6s_VlbdBMRKM2dns,5201
+foxglove/_foxglove_py/channels.pyi,sha256=c3WXhK5FfeCJ1aDGB-AsayIossnC8v8qFij0XWl1AEA,67327
+foxglove/_foxglove_py/cloud.pyi,sha256=9Hqj7b9S2CTiWeWOIqaAw3GSmR-cGoSL4R7fi5WI-QA,255
+foxglove/_foxglove_py/mcap.pyi,sha256=3ZLmrcomTN0bXoseDYGyAOd33I7fkzT4WkT130RlKJA,3693
+foxglove/_foxglove_py/schemas.pyi,sha256=oVF6fwYlgoZ8a1FmlLhVgCYbz-ueM52NyuuTtwhGuFc,23092
+foxglove/_foxglove_py/schemas_wkt.pyi,sha256=_nHeIdbOKMgPeL5V360-vZXCnEtyRIFzEd_JVsK49qo,2065
+foxglove/_foxglove_py/websocket.pyi,sha256=CrfkGZMqVR4xn2cV7fQHUA2T6h2WddzMOQfSaj-KWBw,8097
+foxglove/benchmarks/test_mcap_serialization.py,sha256=Ab_J2Mz8Vya5ZD8Yypp2jdfhaOCxYW7hw5fos7LyFXk,4682
+foxglove/channel.py,sha256=MRiiOm09ZNATOvVCFuvn19KB9HkVCtsDTJYiqE7LQlA,8452
+foxglove/channels/__init__.py,sha256=qTr5-HKlr4e386onX9OiYBPWUsS1n2vO23PncL0TiPY,2398
+foxglove/cloud.py,sha256=eOHV8ZCnut59uBLiw1c5MiwbIALeVwPzxo2Yb-2jbII,1942
+foxglove/mcap.py,sha256=LR9TSyRlDWuHZpXR8iglmDp-S-4BRqgmvTOiUKHwlsA,200
+foxglove/notebook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foxglove/notebook/foxglove_widget.py,sha256=mOXElZLZSIQfvzbZfMd2jtvmWA-H4Z8j7fa39Vwns34,3418
+foxglove/notebook/notebook_buffer.py,sha256=ooQIb8xcyNeuCoRm7CL0Uhnh9VPcd41YMUNYRu15FYg,3801
+foxglove/notebook/static/widget.js,sha256=gPbW5C8KwvmNJS0q1KpHVEfoEaHcesMZKtAVz_Ag3XE,3967
+foxglove/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foxglove/schemas/__init__.py,sha256=bqYBLc0HXRe-BMRP3VnF9IUB2yKYsvku3pZnulss3GY,3232
+foxglove/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foxglove/tests/test_channel.py,sha256=coIPG-P_8Uczhw2-zRo4FoanlkReiE1CKUppM9mO1oE,7146
+foxglove/tests/test_context.py,sha256=OvtvjzsRaZZHPT0RyRkwrpBip-7uLaxVPwlu2RJ12yY,256
+foxglove/tests/test_logging.py,sha256=G2Mljb9nN5BOY5qKAeYo0x_2blY1iIRh9s80k0O3vaI,1472
+foxglove/tests/test_mcap.py,sha256=F_g9WLazTt-fJaRPQIS1Fjgf-gK_bwhgswdz17tqdEE,5646
+foxglove/tests/test_parameters.py,sha256=18YsSPNnSM3VjVCh-Ag4S9mBv2G-x2zSwi5wzQClvqo,4861
+foxglove/tests/test_schemas.py,sha256=4empQg8gqS7MD63ibU3kdQgJUSsUpnNQQWQ7oAf-4xk,423
+foxglove/tests/test_server.py,sha256=PHraaIt4m27MXn1UveV6BRpzYCMFOQfjQD4d4ZHRjIY,2893
+foxglove/tests/test_time.py,sha256=By_sM5r87s9iu4Df12r6p9DJrzTeZSLys3XGUGhvUps,4661
+foxglove/websocket.py,sha256=QDYNUJ4x9P92pLvnK1kOkMDD4EVg9CeOqMLSKlJasT0,5700
+foxglove_sdk-0.16.1.dist-info/METADATA,sha256=f7b04K7IcKaEJYvatpBxegYJJm0X_v_SiNPlPtRU0G8,1716
+foxglove_sdk-0.16.1.dist-info/WHEEL,sha256=PIHWx_H737_urdRR7Zu8WjJH_pxvFim5cnS0vv-DVNQ,143
+foxglove_sdk-0.16.1.dist-info/RECORD,,

foxglove_sdk-0.16.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp314-cp314-manylinux_2_17_i686
+Tag: cp314-cp314-manylinux2014_i686

foxglove_sdk-0.14.2.dist-info/METADATA

@@ -1,29 +0,0 @@
-Metadata-Version: 2.4
-Name: foxglove-sdk
-Version: 0.14.2
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Rust
-Summary: Foxglove Python SDK
-Author-email: Foxglove <support@foxglove.dev>
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: repository, https://github.com/foxglove/foxglove-sdk
-Project-URL: documentation, https://docs.foxglove.dev/
-
-# Foxglove Python SDK
-
-The official [Foxglove](https://docs.foxglove.dev/docs) SDK for Python.
-
-This package provides support for integrating with the Foxglove platform. It can be used to log
-events to local [MCAP](https://mcap.dev/) files or a local visualization server that communicates
-with the Foxglove app.
-
-## Get Started
-
-See https://foxglove.github.io/foxglove-sdk/python/
-
-## Requirements
-
-- Python 3.9+
-

foxglove_sdk-0.14.2.dist-info/RECORD

@@ -1,26 +0,0 @@
-foxglove/__init__.py,sha256=AUUn0WLpVoZqSs60bqy6kzvjV7I2pDxJ5TCmnCNPuww,4240
-foxglove/_foxglove_py.cpython-314-i386-linux-gnu.so,sha256=CjaFgUVGKytJwNveknU-wZqeJtzT5E-8HbFskbWPV1s,6621484
-foxglove/_foxglove_py/__init__.pyi,sha256=76zIyKkXRGp6OW9R8U4daMVPX3mBM_Th5JKo-jzEykU,4296
-foxglove/_foxglove_py/channels.pyi,sha256=c3WXhK5FfeCJ1aDGB-AsayIossnC8v8qFij0XWl1AEA,67327
-foxglove/_foxglove_py/mcap.pyi,sha256=r858qyn4FZMmjD9ZbLP8eZktBNUgMYjwEEHLgMyN2Bw,3265
-foxglove/_foxglove_py/schemas.pyi,sha256=oVF6fwYlgoZ8a1FmlLhVgCYbz-ueM52NyuuTtwhGuFc,23092
-foxglove/_foxglove_py/schemas_wkt.pyi,sha256=_nHeIdbOKMgPeL5V360-vZXCnEtyRIFzEd_JVsK49qo,2065
-foxglove/_foxglove_py/websocket.pyi,sha256=quclOE3BvKcH6QZbEweQc4p_JUPYEHYC4pdQlrCjw_w,8097
-foxglove/benchmarks/test_mcap_serialization.py,sha256=Ab_J2Mz8Vya5ZD8Yypp2jdfhaOCxYW7hw5fos7LyFXk,4682
-foxglove/channel.py,sha256=MRiiOm09ZNATOvVCFuvn19KB9HkVCtsDTJYiqE7LQlA,8452
-foxglove/channels/__init__.py,sha256=qTr5-HKlr4e386onX9OiYBPWUsS1n2vO23PncL0TiPY,2398
-foxglove/mcap.py,sha256=LR9TSyRlDWuHZpXR8iglmDp-S-4BRqgmvTOiUKHwlsA,200
-foxglove/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-foxglove/schemas/__init__.py,sha256=bqYBLc0HXRe-BMRP3VnF9IUB2yKYsvku3pZnulss3GY,3232
-foxglove/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-foxglove/tests/test_channel.py,sha256=coIPG-P_8Uczhw2-zRo4FoanlkReiE1CKUppM9mO1oE,7146
-foxglove/tests/test_logging.py,sha256=r219wdtEO8f6T0LfTTbTmWrEtHD_WznMm_g4SoJ6Byc,355
-foxglove/tests/test_mcap.py,sha256=GpYbsyoSghV7RECl6QRwR1CfQ_mATujLSzrs9f-XolE,3081
-foxglove/tests/test_parameters.py,sha256=18YsSPNnSM3VjVCh-Ag4S9mBv2G-x2zSwi5wzQClvqo,4861
-foxglove/tests/test_schemas.py,sha256=4empQg8gqS7MD63ibU3kdQgJUSsUpnNQQWQ7oAf-4xk,423
-foxglove/tests/test_server.py,sha256=FGcnezEuMtublhIQilFSytqPKQDZpCmY4jJzMJhIWn8,2848
-foxglove/tests/test_time.py,sha256=By_sM5r87s9iu4Df12r6p9DJrzTeZSLys3XGUGhvUps,4661
-foxglove/websocket.py,sha256=oPcI2dttjr-RdL7z30MKEEF1cswyoDu_VetEaxAiwtQ,5812
-foxglove_sdk-0.14.2.dist-info/METADATA,sha256=NawweZpB1AfDNSjBd9YN1swgd7Nwc7hEs3_E79UWmPM,873
-foxglove_sdk-0.14.2.dist-info/WHEEL,sha256=MiSJMZ2VQZYQ1U6qYyxWoq0cYeXLCtiJVjg3_Ejsx5c,125
-foxglove_sdk-0.14.2.dist-info/RECORD,,

foxglove_sdk-0.14.2.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: maturin (1.9.4)
-Root-Is-Purelib: false
-Tag: cp314-cp314-manylinux_2_17_i686.manylinux2014_i686