python-can-hub 0.2.2__py3-none-win_amd64.whl → 0.2.4__py3-none-win_amd64.whl

canhub/_native.py

@@ -126,3 +126,14 @@ lib.canhub_send.argtypes = [c_void_p, POINTER(CanHubFrame)]
 def last_error(session):
     detail = lib.canhub_last_error(session)
     return detail.decode("utf-8", errors="replace") if detail else "unknown error"
+
+
+def list_interfaces(session, timeout_ms, capacity=64):
+    while True:
+        buffer = (CanHubInterfaceInfo * capacity)()
+        count = lib.canhub_list(session, buffer, capacity, timeout_ms)
+        if count < 0:
+            raise OSError(last_error(session))
+        if count < capacity:
+            return [buffer[index] for index in range(count)]
+        capacity *= 2

canhub/bus.py

@@ -1,7 +1,8 @@
 """python-can backend over libcanhub: can.Bus(interface="canhub", ...)."""
 
 import ctypes
-from typing import Optional, Tuple
+import os
+from typing import List, Optional, Tuple
 
 from can import BusABC, CanInitializationError, CanOperationError, Message
 
@@ -49,22 +50,9 @@ class CanHubBus(BusABC):
         self._session = None
         self._writable = False
 
-        if hub_fingerprint is not None:
-            hub_fingerprint = str(hub_fingerprint)
-            if not _is_fingerprint(hub_fingerprint):
-                raise CanInitializationError(
-                    "hub_fingerprint must be 64 hex characters (it may have been "
-                    "mangled by python-can config value casting; pass it as a string)"
-                )
-
-        config = native.CanHubConnectConfig()
-        config.struct_size = ctypes.sizeof(config)
-        config.url = url.encode() if url else None
-        config.state_directory = state_dir.encode() if state_dir else None
-        config.certificate_path = identity_cert.encode() if identity_cert else None
-        config.key_path = identity_key.encode() if identity_key else None
-        config.hub_fingerprint = hub_fingerprint.encode() if hub_fingerprint else None
-        config.connect_timeout_ms = DEFAULT_TIMEOUT_MS
+        config = self._build_connect_config(
+            url, identity_cert, identity_key, hub_fingerprint, state_dir, DEFAULT_TIMEOUT_MS
+        )
 
         self._session = native.lib.canhub_connect(ctypes.byref(config))
         if not self._session:
@@ -74,6 +62,62 @@ class CanHubBus(BusABC):
         self.channel_info = f"canhub {channel} via {url or 'unix socket'}"
         super().__init__(channel=channel, **kwargs)
 
+    @classmethod
+    def list_interfaces(
+        cls,
+        url: Optional[str] = None,
+        identity_cert: Optional[str] = None,
+        identity_key: Optional[str] = None,
+        hub_fingerprint: Optional[str] = None,
+        state_dir: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_MS / 1000,
+    ) -> List[dict]:
+        """List the interfaces a hub exports, ready to splat into ``can.Bus``.
+
+        Connects to ``url`` (or the local hub unix socket when ``None``), asks the
+        hub for its interface directory and disconnects. Each entry is a python-can
+        config dict whose keys ``can.Bus(**entry)`` consumes directly. Connection
+        parameters mirror :class:`CanHubBus`.
+        """
+        timeout_ms = max(0, int(timeout * 1000))
+        config = cls._build_connect_config(
+            url, identity_cert, identity_key, hub_fingerprint, state_dir, timeout_ms
+        )
+
+        session = native.lib.canhub_connect(ctypes.byref(config))
+        if not session:
+            raise CanInitializationError(f"could not connect to {url or 'the local can-hub socket'}")
+
+        try:
+            interfaces = native.list_interfaces(session, timeout_ms)
+        except OSError as error:
+            raise CanOperationError(str(error)) from error
+        finally:
+            native.lib.canhub_close(session)
+
+        connection = {
+            "url": url,
+            "identity_cert": identity_cert,
+            "identity_key": identity_key,
+            "hub_fingerprint": hub_fingerprint,
+            "state_dir": state_dir,
+        }
+        present = {key: value for key, value in connection.items() if value is not None}
+        return [cls._to_config(info, present) for info in interfaces]
+
+    @classmethod
+    def _detect_available_configs(cls) -> List[dict]:
+        try:
+            return cls.list_interfaces(
+                url=os.environ.get("CANHUB_URL"),
+                identity_cert=os.environ.get("CANHUB_IDENTITY_CERT"),
+                identity_key=os.environ.get("CANHUB_IDENTITY_KEY"),
+                hub_fingerprint=os.environ.get("CANHUB_HUB_FINGERPRINT"),
+                state_dir=os.environ.get("CANHUB_STATE_DIR"),
+            )
+        except Exception:
+            return []
+
     def _recv_internal(self, timeout: Optional[float]) -> Tuple[Optional[Message], bool]:
         frame = native.CanHubFrame()
         timeout_ms = -1 if timeout is None else max(0, int(timeout * 1000))
@@ -151,6 +195,39 @@ class CanHubBus(BusABC):
             self._session = None
             raise CanInitializationError(f"could not open {channel}: {detail}")
 
+    @staticmethod
+    def _build_connect_config(
+        url: Optional[str],
+        identity_cert: Optional[str],
+        identity_key: Optional[str],
+        hub_fingerprint: Optional[str],
+        state_dir: Optional[str],
+        timeout_ms: int,
+    ) -> "native.CanHubConnectConfig":
+        if hub_fingerprint is not None:
+            hub_fingerprint = str(hub_fingerprint)
+            if not _is_fingerprint(hub_fingerprint):
+                raise CanInitializationError(
+                    "hub_fingerprint must be 64 hex characters (it may have been "
+                    "mangled by python-can config value casting; pass it as a string)"
+                )
+
+        config = native.CanHubConnectConfig()
+        config.struct_size = ctypes.sizeof(config)
+        config.url = url.encode() if url else None
+        config.state_directory = state_dir.encode() if state_dir else None
+        config.certificate_path = identity_cert.encode() if identity_cert else None
+        config.key_path = identity_key.encode() if identity_key else None
+        config.hub_fingerprint = hub_fingerprint.encode() if hub_fingerprint else None
+        config.connect_timeout_ms = timeout_ms
+        return config
+
+    @staticmethod
+    def _to_config(info: native.CanHubInterfaceInfo, connection: dict) -> dict:
+        agent = info.agent.decode("utf-8", errors="replace")
+        name = info.interface_name.decode("utf-8", errors="replace")
+        return {"interface": "canhub", "channel": f"{agent}/{name}", **connection}
+
     @staticmethod
     def _to_message(frame: native.CanHubFrame) -> Message:
         return Message(

{python_can_hub-0.2.2.dist-info → python_can_hub-0.2.4.dist-info}/METADATA

@@ -1,12 +1,14 @@
 Metadata-Version: 2.1
 Name: python-can-hub
-Version: 0.2.2
+Version: 0.2.4
 Summary: python-can backend for can-hub: remote CAN interfaces over unix/tcp/tls/quic
 License: AGPL-3.0-only
 Project-URL: Homepage, https://github.com/can-hub-io/can-hub
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: python-can >=4.0
+Provides-Extra: test
+Requires-Dist: pytest >=7 ; extra == 'test'
 
 # python-can-hub
 
@@ -38,9 +40,47 @@ for message in bus:
 Write access follows the hub client ACLs: if the ACL grants read-only, the
 bus opens read-only and `send()` raises.
 
+## Listing interfaces
+
+`CanHubBus.list_interfaces()` asks a hub for the interfaces it exports. Each
+entry is a python-can config dict you can splat straight into `can.Bus`:
+
+```python
+from canhub import CanHubBus
+import can
+
+for config in CanHubBus.list_interfaces(url="quic://hub.example.com:7227"):
+    print(config["channel"])          # e.g. "can-agent/can0"
+bus = can.Bus(**CanHubBus.list_interfaces()[0])   # first interface, local hub
+```
+
+It accepts the same connection arguments as the bus (`url`, `identity_cert`,
+`identity_key`, `hub_fingerprint`, `state_dir`); omit `url` to query the local
+hub unix socket.
+
+This also wires python-can's discovery: `can.detect_available_configs("canhub")`
+returns the same dicts. With no explicit target it reads the connection from the
+environment — `CANHUB_URL`, `CANHUB_STATE_DIR`, `CANHUB_IDENTITY_CERT`,
+`CANHUB_IDENTITY_KEY`, `CANHUB_HUB_FINGERPRINT` — falling back to the local hub
+unix socket. So `CANHUB_URL=quic://hub.example.com:7227` points discovery at a
+remote host without any code.
+
 The wheel bundles `libcanhub.so` with the TLS/QUIC stack linked in
 statically; the only runtime dependency is glibc.
 
+## Testing
+
+The unit tests stub the native library, so they run without a build:
+
+```sh
+pip install -e python/.[test]
+pytest python/tests
+```
+
+The backend is also exercised end-to-end against real binaries (recv, send,
+`list_interfaces`, and `can.detect_available_configs` discovery) by
+`test/e2e/tests/python_can.robot`; run the whole bench with `make e2e`.
+
 ## Building from source
 
 ```sh
@@ -58,5 +98,6 @@ cross arches):
 ./scripts/build-python-wheel.sh armv7l
 ```
 
-The release workflow builds all three and publishes them to PyPI on a `v*`
-tag.
+The release workflow builds these three on native runners (aarch64/armv7l on
+the arm64 hosted runner, no QEMU) plus a cross-compiled win_amd64 wheel, and
+publishes all four to PyPI on a `v*` tag.

python_can_hub-0.2.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+canhub/__init__.py,sha256=yC7SFSz4vUDFgve7gehAaOSqZ1Iv1Kbv1A4c5nj_XcM,485
+canhub/__main__.py,sha256=WM0VMTSjzySENh7zkbTT4WpLnqyS_gsZBgJ4f05qNHQ,366
+canhub/_native.py,sha256=Dnk0z-fWQ3UkaoxXt4N6Ml7OHJQtXKSGtU-46CH56qo,3672
+canhub/bus.py,sha256=6qv9tXgIA7hHIqnBJMewOyGyFxS-48Of9OaaJ9Abhrw,10085
+canhub/fingerprint.py,sha256=N38dP3_odFYn6821XViWG6aQKUPhxJHDY8xE8uW8zNo,711
+canhub/libcanhub.dll,sha256=xPTHIVUv-1ti0sMR6lA_8iePdFKK5dA9gzTKpd1CKgo,6398464
+python_can_hub-0.2.4.dist-info/METADATA,sha256=t0735LhHCZw2lPs1EI_zNTg971bs8ymKQx05G8JZLZw,3588
+python_can_hub-0.2.4.dist-info/WHEEL,sha256=KTdQDMVZqs2eeRhOpF4kInPW2OgLgRWl7KhVZQueA2o,99
+python_can_hub-0.2.4.dist-info/entry_points.txt,sha256=ZfPo9cCR4xH9BjYRCi_nOcw_48SN6vqboV0B2y8HcjU,46
+python_can_hub-0.2.4.dist-info/top_level.txt,sha256=nPyUT2Mw-NsKrJhpH-4EUcBBqz7GOSwfxnGkFEILnKk,7
+python_can_hub-0.2.4.dist-info/RECORD,,

python_can_hub-0.2.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-canhub/__init__.py,sha256=yC7SFSz4vUDFgve7gehAaOSqZ1Iv1Kbv1A4c5nj_XcM,485
-canhub/__main__.py,sha256=WM0VMTSjzySENh7zkbTT4WpLnqyS_gsZBgJ4f05qNHQ,366
-canhub/_native.py,sha256=4MHqnxR86NfMN_4jrp5rg60MR1hfhD7p-zXozSoAEAg,3295
-canhub/bus.py,sha256=dLwIGXdGplCyG_vh0Rb9DmM5kUjGCMyV_OlMU10q4x4,7060
-canhub/fingerprint.py,sha256=N38dP3_odFYn6821XViWG6aQKUPhxJHDY8xE8uW8zNo,711
-canhub/libcanhub.dll,sha256=BFcvsPyRdRgD2wiGAAlHZEDRXTqHQlHwjlTkDaxu19k,6396928
-python_can_hub-0.2.2.dist-info/METADATA,sha256=MaxFh9oRfrcQ60f7_UfbYdbz6Ng3RarPS0Om8fDaWVs,1998
-python_can_hub-0.2.2.dist-info/WHEEL,sha256=KTdQDMVZqs2eeRhOpF4kInPW2OgLgRWl7KhVZQueA2o,99
-python_can_hub-0.2.2.dist-info/entry_points.txt,sha256=ZfPo9cCR4xH9BjYRCi_nOcw_48SN6vqboV0B2y8HcjU,46
-python_can_hub-0.2.2.dist-info/top_level.txt,sha256=nPyUT2Mw-NsKrJhpH-4EUcBBqz7GOSwfxnGkFEILnKk,7
-python_can_hub-0.2.2.dist-info/RECORD,,