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

foxglove/_foxglove_py/__init__.pyi

@@ -1,167 +1,233 @@
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-from .mcap import MCAPWriteOptions, MCAPWriter
-from .websocket import AssetHandler, Capability, Service, WebSocketServer
-
-class BaseChannel:
-    """
-    A channel for logging messages.
-    """
-
-    def __new__(
-        cls,
-        topic: str,
-        message_encoding: str,
-        schema: Optional["Schema"] = None,
-        metadata: Optional[List[Tuple[str, str]]] = None,
-    ) -> "BaseChannel": ...
-    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) -> Optional["Schema"]:
-        """
-        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) -> Optional[str]:
-        """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: Optional[int] = None,
-    ) -> None:
-        """
-        Log a message to the channel.
-
-        :param msg: The message to log.
-        :param log_time: The optional time the message was logged.
-        """
-        ...
-
-    def close(self) -> None: ...
-
-class Schema:
-    """
-    A schema for a message or service call.
-    """
-
-    name: str
-    encoding: str
-    data: bytes
-
-    def __new__(
-        cls,
-        *,
-        name: str,
-        encoding: str,
-        data: bytes,
-    ) -> "Schema": ...
-
-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 __new__(cls) -> "Context": ...
-    def _create_channel(
-        self,
-        topic: str,
-        message_encoding: str,
-        schema: Optional["Schema"] = None,
-        metadata: Optional[List[Tuple[str, str]]] = None,
-    ) -> "BaseChannel":
-        """
-        Instead of calling this method, pass a context to a channel constructor.
-        """
-        ...
-
-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: Any = 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.
-    """
-    ...
-
-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: Optional["Context"] = None,
-    writer_options: Optional[MCAPWriteOptions] = 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.
-    """
-    ...
-
-def get_channel_for_topic(topic: str) -> Optional[BaseChannel]:
-    """
-    Get a previously-registered channel.
-    """
-    ...
+from pathlib import Path
+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 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,
+    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.
+    """
+    ...
+
+def disable_logging() -> None:
+    """
+    Stop forwarding SDK logs.
+    """
+    ...
+
+def shutdown() -> None:
+    """
+    Shutdown the running websocket server.
+    """
+    ...
+
+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:
+    """
+    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) -> BaseChannel | None:
+    """
+    Get a previously-registered channel.
+    """
+    ...