foxglove-sdk 0.16.3__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

foxglove/tests/test_server.py

@@ -0,0 +1,141 @@
+import time
+import typing
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from foxglove import (
+    Capability,
+    Channel,
+    Context,
+    ServerListener,
+    Service,
+    start_server,
+)
+from foxglove.websocket import PlaybackState, PlaybackStatus, ServiceSchema, StatusLevel
+
+
+def test_server_interface() -> None:
+    """
+    Exercise the server interface; will also be checked with mypy.
+    """
+    server = start_server(
+        port=0, session_id="test-session", channel_filter=lambda _: True
+    )
+    assert isinstance(server.port, int)
+    assert server.port != 0
+
+    raw_url = server.app_url()
+    assert raw_url is not None
+    url = urlparse(raw_url)
+    assert url.scheme == "https"
+    assert url.netloc == "app.foxglove.dev"
+    assert parse_qs(url.query) == {
+        "ds": ["foxglove-websocket"],
+        "ds.url": [f"ws://127.0.0.1:{server.port}"],
+    }
+
+    raw_url = server.app_url(layout_id="lay_123", open_in_desktop=True)
+    assert raw_url is not None
+    url = urlparse(raw_url)
+    assert url.scheme == "https"
+    assert url.netloc == "app.foxglove.dev"
+    assert parse_qs(url.query) == {
+        "ds": ["foxglove-websocket"],
+        "ds.url": [f"ws://127.0.0.1:{server.port}"],
+        "layoutId": ["lay_123"],
+        "openIn": ["desktop"],
+    }
+
+    server.publish_status("test message", StatusLevel.Info, "some-id")
+    server.broadcast_time(time.time_ns())
+    server.broadcast_playback_state(
+        PlaybackState(
+            status=PlaybackStatus.Paused,
+            playback_speed=1.0,
+            current_time=time.time_ns(),
+            did_seek=False,
+            request_id=None,
+        )
+    )
+    server.remove_status(["some-id"])
+    server.clear_session("new-session")
+    server.stop()
+
+
+def test_server_listener_provides_default_implementation() -> None:
+    class DefaultServerListener(ServerListener):
+        pass
+
+    listener = DefaultServerListener()
+
+    listener.on_parameters_subscribe(["test"])
+    listener.on_parameters_unsubscribe(["test"])
+
+
+def test_services_interface() -> None:
+    test_svc = Service(
+        name="test",
+        schema=ServiceSchema(name="test-schema"),
+        handler=lambda *_: b"{}",
+    )
+    test2_svc = Service(
+        name="test2",
+        schema=ServiceSchema(name="test-schema"),
+        handler=lambda *_: b"{}",
+    )
+    server = start_server(
+        port=0,
+        capabilities=[Capability.Services],
+        supported_encodings=["json"],
+        services=[test_svc],
+    )
+
+    # Add a new service.
+    server.add_services([test2_svc])
+
+    # Can't add a service with the same name.
+    with pytest.raises(RuntimeError):
+        server.add_services([test_svc])
+
+    # Remove services.
+    server.remove_services(["test", "test2"])
+
+    # Re-add a service.
+    server.add_services([test_svc])
+
+    server.stop()
+
+
+def test_context_can_be_attached_to_server() -> None:
+    ctx1 = Context()
+    ctx2 = Context()
+
+    server1 = start_server(port=0, context=ctx1)
+    server2 = start_server(port=0, context=ctx2)
+
+    ch1 = Channel("/1", context=ctx1)
+    ch2 = Channel("/2", context=ctx2)
+    ch1.log("test")
+    ch2.log("test")
+
+    server1.stop()
+    server2.stop()
+
+
+@typing.no_type_check
+def test_server_with_invalid_playback_time_range() -> None:
+    with pytest.raises(TypeError):
+        # Tuple of a single element
+        start_server(port=0, playback_time_range=(123,))
+
+    with pytest.raises(TypeError):
+        # Tuple with invalid types
+        start_server(port=0, playback_time_range=("not-a-time", None))
+
+    with pytest.raises(TypeError):
+        # Not a tuple
+        start_server(port=0, playback_time_range=23443)
+
+    with pytest.raises(TypeError):
+        # Tuple with too many elements
+        start_server(port=0, playback_time_range=(123, 456, 789))

foxglove/tests/test_time.py

@@ -0,0 +1,137 @@
+import datetime
+
+import pytest
+from foxglove.schemas import Duration, Timestamp
+
+
+def test_duration_normalization() -> None:
+    assert Duration(sec=0, nsec=1_111_222_333) == Duration(sec=1, nsec=111_222_333)
+    assert Duration(sec=0, nsec=2**32 - 1) == Duration(sec=4, nsec=294_967_295)
+    assert Duration(sec=-2, nsec=1_000_000_001) == Duration(sec=-1, nsec=1)
+    assert Duration(sec=-(2**31), nsec=1_000_000_001) == Duration(
+        sec=-(2**31) + 1, nsec=1
+    )
+
+    # argument conversions
+    d = Duration(sec=-(2**31))
+    assert d.sec == -(2**31)
+    assert d.nsec == 0
+
+    d = Duration(sec=0, nsec=2**32 - 1)
+    assert d.sec == 4
+    assert d.nsec == 294_967_295
+
+    d = Duration(sec=2**31 - 1, nsec=999_999_999)
+    assert d.sec == 2**31 - 1
+    assert d.nsec == 999_999_999
+
+    with pytest.raises(OverflowError):
+        Duration(sec=-(2**31) - 1)
+    with pytest.raises(OverflowError):
+        Duration(sec=2**31)
+    with pytest.raises(OverflowError):
+        Duration(sec=0, nsec=-1)
+    with pytest.raises(OverflowError):
+        Duration(sec=0, nsec=2**32)
+
+    # overflow past upper bound
+    with pytest.raises(OverflowError):
+        Duration(sec=2**31 - 1, nsec=1_000_000_000)
+
+    # we don't handle this corner case, where seconds is beyond the lower
+    # bound, but nanoseconds overflow to bring the duration within range.
+    with pytest.raises(OverflowError):
+        Duration(sec=-(2**31) - 1, nsec=1_000_000_000)
+
+
+def test_duration_from_secs() -> None:
+    assert Duration.from_secs(1.123) == Duration(sec=1, nsec=123_000_000)
+    assert Duration.from_secs(-0.123) == Duration(sec=-1, nsec=877_000_000)
+    assert Duration.from_secs(-1.123) == Duration(sec=-2, nsec=877_000_000)
+
+    with pytest.raises(OverflowError):
+        Duration.from_secs(-1e42)
+
+    with pytest.raises(OverflowError):
+        Duration.from_secs(1e42)
+
+
+def test_duration_from_timedelta() -> None:
+    td = datetime.timedelta(seconds=1, milliseconds=123)
+    assert Duration.from_timedelta(td) == Duration(sec=1, nsec=123_000_000)
+
+    # no loss of precision
+    td = datetime.timedelta(days=9876, microseconds=123_456)
+    assert Duration.from_timedelta(td) == Duration(sec=853_286_400, nsec=123_456_000)
+
+    # timedeltas are normalized
+    td = datetime.timedelta(seconds=8 * 24 * 3600, milliseconds=99_111)
+    assert Duration.from_timedelta(td) == Duration(sec=691_299, nsec=111_000_000)
+
+    with pytest.raises(OverflowError):
+        Duration.from_timedelta(datetime.timedelta.min)
+
+    with pytest.raises(OverflowError):
+        Duration.from_timedelta(datetime.timedelta.max)
+
+
+def test_timestamp_normalization() -> None:
+    assert Timestamp(sec=0, nsec=1_111_222_333) == Timestamp(sec=1, nsec=111_222_333)
+    assert Timestamp(sec=0, nsec=2**32 - 1) == Timestamp(sec=4, nsec=294_967_295)
+
+    # argument conversions
+    t = Timestamp(sec=0)
+    assert t.sec == 0
+    assert t.nsec == 0
+
+    t = Timestamp(sec=0, nsec=2**32 - 1)
+    assert t.sec == 4
+    assert t.nsec == 294_967_295
+
+    t = Timestamp(sec=2**32 - 1, nsec=999_999_999)
+    assert t.sec == 2**32 - 1
+    assert t.nsec == 999_999_999
+
+    with pytest.raises(OverflowError):
+        Timestamp(sec=-1)
+    with pytest.raises(OverflowError):
+        Timestamp(sec=2**32)
+    with pytest.raises(OverflowError):
+        Timestamp(sec=0, nsec=-1)
+    with pytest.raises(OverflowError):
+        Timestamp(sec=0, nsec=2**32)
+
+    # overflow past upper bound
+    with pytest.raises(OverflowError):
+        Timestamp(sec=2**32 - 1, nsec=1_000_000_000)
+
+
+def test_timestamp_from_epoch_secs() -> None:
+    assert Timestamp.from_epoch_secs(1.123) == Timestamp(sec=1, nsec=123_000_000)
+
+    with pytest.raises(OverflowError):
+        Timestamp.from_epoch_secs(-1.0)
+
+    with pytest.raises(OverflowError):
+        Timestamp.from_epoch_secs(1e42)
+
+
+def test_timestamp_from_datetime() -> None:
+    utc = datetime.timezone.utc
+    dt = datetime.datetime(1970, 1, 1, tzinfo=utc)
+    assert Timestamp.from_datetime(dt) == Timestamp(sec=0)
+
+    # no loss of precision
+    dt = datetime.datetime(2025, 1, 1, microsecond=42, tzinfo=utc)
+    assert Timestamp.from_datetime(dt) == Timestamp(sec=1_735_689_600, nsec=42_000)
+
+    # alternative timezone
+    local_tz = datetime.timezone(datetime.timedelta(hours=-1))
+    dt = datetime.datetime(1970, 1, 1, 0, 0, 1, 123_000, tzinfo=local_tz)
+    assert Timestamp.from_datetime(dt) == Timestamp(sec=3601, nsec=123_000_000)
+
+    with pytest.raises(OverflowError):
+        Timestamp.from_datetime(datetime.datetime(1969, 12, 31, tzinfo=utc))
+
+    with pytest.raises(OverflowError):
+        Timestamp.from_datetime(datetime.datetime(2106, 2, 8, tzinfo=utc))

foxglove/websocket.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Optional, Protocol, TypeAlias, Union
+
+from ._foxglove_py.websocket import (
+    Capability,
+    ChannelView,
+    Client,
+    ClientChannel,
+    ConnectionGraph,
+    MessageSchema,
+    Parameter,
+    ParameterType,
+    ParameterValue,
+    PlaybackCommand,
+    PlaybackControlRequest,
+    PlaybackState,
+    PlaybackStatus,
+    Service,
+    ServiceRequest,
+    ServiceSchema,
+    StatusLevel,
+    WebSocketServer,
+)
+
+ServiceHandler: TypeAlias = Callable[[ServiceRequest], bytes]
+AssetHandler: TypeAlias = Callable[[str], "bytes | None"]
+AnyParameterValue: TypeAlias = Union[
+    ParameterValue.Integer,
+    ParameterValue.Bool,
+    ParameterValue.Float64,
+    ParameterValue.String,
+    ParameterValue.Array,
+    ParameterValue.Dict,
+]
+AnyInnerParameterValue: TypeAlias = Union[
+    AnyParameterValue,
+    bool,
+    int,
+    float,
+    str,
+    "list[AnyInnerParameterValue]",
+    "dict[str, AnyInnerParameterValue]",
+]
+AnyNativeParameterValue: TypeAlias = Union[
+    AnyInnerParameterValue,
+    bytes,
+]
+
+
+class ServerListener(Protocol):
+    """
+    A mechanism to register callbacks for handling client message events.
+    """
+
+    def on_subscribe(self, client: Client, channel: ChannelView) -> None:
+        """
+        Called by the server 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 by the server 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 by the server 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 by the server 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 by the server 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
+
+    def on_get_parameters(
+        self,
+        client: Client,
+        param_names: list[str],
+        request_id: str | None = None,
+    ) -> list[Parameter]:
+        """
+        Called by the server when a client requests parameters.
+
+        Requires :py:data:`Capability.Parameters`.
+
+        :param client: The client (id) that sent the message.
+        :param param_names: The names of the parameters to get.
+        :param request_id: An optional request id.
+        """
+        return []
+
+    def on_set_parameters(
+        self,
+        client: Client,
+        parameters: list[Parameter],
+        request_id: str | None = None,
+    ) -> list[Parameter]:
+        """
+        Called by the server when a client sets parameters.
+        Note that only `parameters` which have changed are included in the callback, but the return
+        value must include all parameters. If a parameter that is unset is included in the return
+        value, it will not be published to clients.
+
+        Requires :py:data:`Capability.Parameters`.
+
+        :param client: The client (id) that sent the message.
+        :param parameters: The parameters to set.
+        :param request_id: An optional request id.
+        """
+        return parameters
+
+    def on_parameters_subscribe(
+        self,
+        param_names: list[str],
+    ) -> None:
+        """
+        Called by the server when a client subscribes to one or more parameters for the first time.
+
+        Requires :py:data:`Capability.Parameters`.
+
+        :param param_names: The names of the parameters to subscribe to.
+        """
+        return None
+
+    def on_parameters_unsubscribe(
+        self,
+        param_names: list[str],
+    ) -> None:
+        """
+        Called by the server when the last client subscription to one or more parameters has been
+        removed.
+
+        Requires :py:data:`Capability.Parameters`.
+
+        :param param_names: The names of the parameters to unsubscribe from.
+        """
+        return None
+
+    def on_connection_graph_subscribe(self) -> None:
+        """
+        Called by the server when the first client subscribes to the connection graph.
+        """
+        return None
+
+    def on_connection_graph_unsubscribe(self) -> None:
+        """
+        Called by the server when the last client unsubscribes from the connection graph.
+        """
+        return None
+
+    def on_playback_control_request(
+        self, playback_control_request: PlaybackControlRequest
+    ) -> Optional[PlaybackState]:
+        """
+        Called by the server when it receives an updated player state from the client.
+
+        Requires :py:data:`Capability.RangedPlayback`.
+
+        :meta private:
+        :param playback_control_request: The playback control request sent from the client
+        """
+        return None
+
+
+__all__ = [
+    "AnyInnerParameterValue",
+    "AnyNativeParameterValue",
+    "AnyParameterValue",
+    "AssetHandler",
+    "Capability",
+    "ChannelView",
+    "Client",
+    "ClientChannel",
+    "ConnectionGraph",
+    "MessageSchema",
+    "Parameter",
+    "ParameterType",
+    "ParameterValue",
+    "PlaybackCommand",
+    "PlaybackControlRequest",
+    "PlaybackState",
+    "PlaybackStatus",
+    "ServerListener",
+    "Service",
+    "ServiceHandler",
+    "ServiceRequest",
+    "ServiceSchema",
+    "StatusLevel",
+    "WebSocketServer",
+]

foxglove_sdk-0.16.3.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: foxglove-sdk
+Version: 0.16.3
+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: documentation, https://docs.foxglove.dev/
+Project-URL: repository, https://github.com/foxglove/foxglove-sdk
+
+# 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.3.dist-info/RECORD

@@ -0,0 +1,32 @@
+foxglove/__init__.py,sha256=utf_uU_ViL7xDrTqheP6JGs3ezfPsnve2EXFdS0uq-A,8490
+foxglove/_foxglove_py/__init__.pyi,sha256=Ppw0LllCD5Jos1ZGPwEefRFJXVEj9ZWd_Nez2hUYjSs,6072
+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=yh3RDXNiqSN5URCQF0efxezmWldvdQk_VHlW-clS0Cw,4936
+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=NuCIpXp9P2bPNLyvjVYqcaeL71wKRyYB6RbTfkE6X7A,10511
+foxglove/_foxglove_py.cpython-312-aarch64-linux-gnu.so,sha256=wR2OWmMU5uQJgyXfvPqEAw4FYo227AEb_ZHEO7K3yKM,6461552
+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/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=Y4OYgWvkPSD288rJdlrgg1haVGeDRR39sWeUcb6VO8E,14863
+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=rR50x21OOUMVuyYmYqiRTxOrgJFyL4ZL9W4pOshfAFc,3795
+foxglove/tests/test_time.py,sha256=By_sM5r87s9iu4Df12r6p9DJrzTeZSLys3XGUGhvUps,4661
+foxglove/websocket.py,sha256=PvsSGmWFayjRV20u86ZEZ9zcUD7nBC9j6CKPWNZy5ks,6331
+foxglove_sdk-0.16.3.dist-info/METADATA,sha256=-R_TiQnJptVFk1IqvoAQ10Fbk0wSm17dC-gEUe8MPDw,1716
+foxglove_sdk-0.16.3.dist-info/WHEEL,sha256=52Zi36pDPQlOrLthVvXF6f11TX-HRQ2sllWxsSJsrtQ,149
+foxglove_sdk-0.16.3.dist-info/RECORD,,

foxglove_sdk-0.16.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_17_aarch64
+Tag: cp312-cp312-manylinux2014_aarch64