fix: raise errors instead of returning fake data when C++ extension is unavailable

README.md

@@ -40,6 +40,17 @@ cd opensomeip-python
 pip install -e ".[dev]"
 ```
 
+### Verify native extension
+
+After installing, confirm the C++ extension loaded successfully:
+
+```bash
+python3 -c "from opensomeip._bridge import get_ext; ext = get_ext(); print('native:', ext is not None)"
+```
+
+If this prints `native: False`, the library will raise errors on any network
+operation. See the [Troubleshooting](#troubleshooting) section below.
+
 ## Quick Start
 
 ### Server — offer a service and handle RPC calls
@@ -208,20 +219,21 @@ Windows) are compiled in CI with the correct toolchain and don't have this issue
 If a wheel exists for your platform you'll never hit this problem — it only
 occurs when pip falls back to building from the source distribution.
 
-### Silent no-op transport (no socket opened)
+### Operations fail with "C++ extension is not available"
+
+If the C++ extension fails to load, all operations that require the native
+stack (RPC calls, transport send, event subscriptions) will raise clear errors
+such as `RpcError`, `TransportError`, or `RuntimeError` with a message
+indicating the C++ extension is not available.
 
-If the C++ extension fails to load, the library warns via Python's
-`warnings` module and falls back to stub transport classes. These stubs
-set `is_running = True` but **do not open any network sockets**. If your
-server appears to start but `lsof` shows no listening socket, check for the
-`ImportWarning` that opensomeip emits at import time:
+To check whether the extension loaded:
 
 ```bash
-python -W all your_script.py
+python3 -c "from opensomeip._bridge import get_ext; ext = get_ext(); print('native:', ext is not None)"
 ```
 
-If you see the warning, follow the steps in the section above to fix the
-extension build.
+If this prints `native: False`, follow the steps in the section above to fix
+the extension build.
 
 ## Development
 

src/opensomeip/events.py

@@ -96,32 +96,29 @@ def register_event(self, event_id: int, eventgroup_id: int) -> None:
 
     def notify(self, event_id: int, payload: bytes) -> None:
         """Publish a notification for a registered event."""
-        from opensomeip.message import Message
-        from opensomeip.types import MessageType, ReturnCode
-
         if event_id not in self._registered_events:
             from opensomeip.exceptions import ConfigurationError
 
             raise ConfigurationError(f"Event {event_id:#06x} is not registered")
 
-        if self._cpp is not None:
-            data = list(payload)
-            self._cpp.publish_event(event_id, data)
-            return
-
-        msg = Message(
-            message_id=MessageId(service_id=0, method_id=event_id),
-            message_type=MessageType.NOTIFICATION,
-            return_code=ReturnCode.E_OK,
-            payload=payload,
-        )
-        self._transport.send(msg)
+        if self._cpp is None:
+            raise RuntimeError(
+                "Cannot publish events: opensomeip C++ extension is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
+            )
+
+        data = list(payload)
+        self._cpp.publish_event(event_id, data)
 
     def set_field(self, event_id: int, payload: bytes) -> None:
         """Set the value of a field event (getter/setter pattern)."""
-        if self._cpp is not None:
-            data = list(payload)
-            self._cpp.publish_field(event_id, data)
+        if self._cpp is None:
+            raise RuntimeError(
+                "Cannot set field: opensomeip C++ extension is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
+            )
+        data = list(payload)
+        self._cpp.publish_field(event_id, data)
 
     def get_statistics(self) -> Any:
         """Return event publisher statistics (native only)."""
@@ -203,29 +200,34 @@ def subscribe(
         """Subscribe to an event group."""
         self._subscribed_groups.add(eventgroup_id)
 
-        if self._cpp is not None:
-            receiver = self._notification_receiver
-
-            def _on_notification(cpp_notif: Any) -> None:
-                from opensomeip.message import Message
-
-                payload = bytes(cpp_notif.event_data) if cpp_notif.event_data else b""
-                msg = Message(
-                    message_id=MessageId(
-                        service_id=cpp_notif.service_id,
-                        method_id=cpp_notif.event_id,
-                    ),
-                    payload=payload,
-                )
-                receiver.put(msg)
-
-            self._cpp.subscribe_eventgroup(
-                service_id,
-                instance_id,
-                eventgroup_id,
-                _on_notification,
+        if self._cpp is None:
+            raise RuntimeError(
+                "Cannot subscribe to events: opensomeip C++ extension is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
             )
 
+        receiver = self._notification_receiver
+
+        def _on_notification(cpp_notif: Any) -> None:
+            from opensomeip.message import Message
+
+            payload = bytes(cpp_notif.event_data) if cpp_notif.event_data else b""
+            msg = Message(
+                message_id=MessageId(
+                    service_id=cpp_notif.service_id,
+                    method_id=cpp_notif.event_id,
+                ),
+                payload=payload,
+            )
+            receiver.put(msg)
+
+        self._cpp.subscribe_eventgroup(
+            service_id,
+            instance_id,
+            eventgroup_id,
+            _on_notification,
+        )
+
     def unsubscribe(
         self,
         eventgroup_id: int,

src/opensomeip/rpc.py

@@ -100,45 +100,41 @@ def call(
         if not self._running:
             raise RpcError("RPC client is not running")
 
-        if self._cpp is not None:
-            try:
-                import struct as _struct
-
-                params = list(_struct.unpack(f"!{len(payload)}B", payload)) if payload else []
-                cpp_timeout = get_ext().rpc.RpcTimeout()
-                result = self._cpp.call_method_sync(
-                    method_id.service_id,
-                    method_id.method_id,
-                    params,
-                    cpp_timeout,
-                )
-                if int(result.result) == 0:
-                    return_payload = bytes(result.return_values) if result.return_values else b""
-                    return Message(
-                        message_id=method_id,
-                        request_id=RequestId(
-                            client_id=self._client_id, session_id=self._next_session()
-                        ),
-                        message_type=MessageType.RESPONSE,
-                        return_code=ReturnCode.E_OK,
-                        payload=return_payload,
-                    )
-            except Exception:
-                pass
+        if self._cpp is None:
+            raise RpcError(
+                "Cannot perform RPC call: opensomeip C++ extension is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
+            )
 
-        request = Message(
-            message_id=method_id,
-            request_id=RequestId(client_id=self._client_id, session_id=self._next_session()),
-            message_type=MessageType.REQUEST,
-            payload=payload,
-        )
-        self._transport.send(request)
-        return Message(
-            message_id=method_id,
-            request_id=request.request_id,
-            message_type=MessageType.RESPONSE,
-            return_code=ReturnCode.E_OK,
-        )
+        try:
+            import struct as _struct
+
+            params = list(_struct.unpack(f"!{len(payload)}B", payload)) if payload else []
+            cpp_timeout = get_ext().rpc.RpcTimeout()
+            result = self._cpp.call_method_sync(
+                method_id.service_id,
+                method_id.method_id,
+                params,
+                cpp_timeout,
+            )
+            if int(result.result) != 0:
+                raise RpcError(
+                    f"RPC call to {method_id} failed with native result code {result.result}"
+                )
+            return_payload = bytes(result.return_values) if result.return_values else b""
+            return Message(
+                message_id=method_id,
+                request_id=RequestId(
+                    client_id=self._client_id, session_id=self._next_session()
+                ),
+                message_type=MessageType.RESPONSE,
+                return_code=ReturnCode.E_OK,
+                payload=return_payload,
+            )
+        except RpcError:
+            raise
+        except Exception as exc:
+            raise RpcError(f"Native RPC call to {method_id} failed: {exc}") from exc
 
     async def call_async(
         self,
@@ -151,55 +147,41 @@ async def call_async(
         if not self._running:
             raise RpcError("RPC client is not running")
 
-        if self._cpp is not None:
-            import struct
-
-            params = list(struct.unpack(f"!{len(payload)}B", payload)) if payload else []
-            loop = asyncio.get_running_loop()
-            future: asyncio.Future[Message] = loop.create_future()
-            session = self._next_session()
-            self._pending[session] = future
-
-            def _on_response(cpp_resp: Any) -> None:
-                return_payload = bytes(cpp_resp.return_values) if cpp_resp.return_values else b""
-                py_msg = Message(
-                    message_id=method_id,
-                    request_id=RequestId(client_id=self._client_id, session_id=session),
-                    message_type=MessageType.RESPONSE,
-                    return_code=ReturnCode.E_OK,
-                    payload=return_payload,
-                )
-                loop.call_soon_threadsafe(future.set_result, py_msg)
-
-            cpp_timeout = get_ext().rpc.RpcTimeout()
-            self._cpp.call_method_async(
-                method_id.service_id,
-                method_id.method_id,
-                params,
-                _on_response,
-                cpp_timeout,
+        if self._cpp is None:
+            raise RpcError(
+                "Cannot perform RPC call: opensomeip C++ extension is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
             )
-            try:
-                return await asyncio.wait_for(future, timeout=timeout)
-            except asyncio.TimeoutError:
-                self._pending.pop(session, None)
-                raise RpcError(f"RPC call timed out after {timeout}s") from None
 
+        import struct
+
+        params = list(struct.unpack(f"!{len(payload)}B", payload)) if payload else []
         loop = asyncio.get_running_loop()
-        future_stub: asyncio.Future[Message] = loop.create_future()
+        future: asyncio.Future[Message] = loop.create_future()
         session = self._next_session()
-        self._pending[session] = future_stub
-
-        request = Message(
-            message_id=method_id,
-            request_id=RequestId(client_id=self._client_id, session_id=session),
-            message_type=MessageType.REQUEST,
-            payload=payload,
+        self._pending[session] = future
+
+        def _on_response(cpp_resp: Any) -> None:
+            return_payload = bytes(cpp_resp.return_values) if cpp_resp.return_values else b""
+            py_msg = Message(
+                message_id=method_id,
+                request_id=RequestId(client_id=self._client_id, session_id=session),
+                message_type=MessageType.RESPONSE,
+                return_code=ReturnCode.E_OK,
+                payload=return_payload,
+            )
+            loop.call_soon_threadsafe(future.set_result, py_msg)
+
+        cpp_timeout = get_ext().rpc.RpcTimeout()
+        self._cpp.call_method_async(
+            method_id.service_id,
+            method_id.method_id,
+            params,
+            _on_response,
+            cpp_timeout,
         )
-        self._transport.send(request)
-
         try:
-            return await asyncio.wait_for(future_stub, timeout=timeout)
+            return await asyncio.wait_for(future, timeout=timeout)
         except asyncio.TimeoutError:
             self._pending.pop(session, None)
             raise RpcError(f"RPC call timed out after {timeout}s") from None

src/opensomeip/transport.py

@@ -146,14 +146,21 @@ def send(self, message: Message, endpoint: Endpoint | None = None) -> None:
         """Send a SOME/IP message, delegating to C++ when available."""
         if not self._running:
             raise TransportError("Transport is not running")
-        if self._cpp is not None:
-            cpp_msg = to_cpp_message(message)
-            target = endpoint or self._remote
-            if target is None and hasattr(message, "source_endpoint"):
-                target = message.source_endpoint
-            if target is not None:
-                cpp_ep = to_cpp_endpoint(target)
-                self._cpp.send_message(cpp_msg, cpp_ep)
+        if self._cpp is None:
+            raise TransportError(
+                "Cannot send: opensomeip native transport is not available. "
+                "See https://github.com/vtz/opensomeip-python#troubleshooting"
+            )
+        cpp_msg = to_cpp_message(message)
+        target = endpoint or self._remote
+        if target is None and hasattr(message, "source_endpoint"):
+            target = message.source_endpoint
+        if target is None:
+            raise TransportError(
+                "No target endpoint specified and no remote endpoint configured"
+            )
+        cpp_ep = to_cpp_endpoint(target)
+        self._cpp.send_message(cpp_msg, cpp_ep)
 
     def __enter__(self) -> Self:
         self.start()

tests/integration/test_rpc_roundtrip.py

@@ -12,6 +12,7 @@
 import pytest
 
 from opensomeip.client import ClientConfig, SomeIpClient
+from opensomeip.exceptions import RpcError
 from opensomeip.message import Message
 from opensomeip.sd import SdConfig, ServiceInstance
 from opensomeip.server import ServerConfig, SomeIpServer
@@ -57,6 +58,9 @@ def test_sync_call_lifecycle(
 
         Verifies the full wiring: SomeIpServer -> RpcServer -> handler
         registration, and SomeIpClient -> RpcClient -> call().
+        Without a full SOME/IP network, the native call may time out or
+        fail — we validate the code path raises RpcError rather than
+        silently returning fake data.
         """
         with SomeIpServer(server_config) as server:
 
@@ -72,9 +76,12 @@ def echo(req: Message) -> Message:
             server.register_method(METHOD, echo)
 
             with SomeIpClient(client_config) as client:
-                response = client.call(METHOD, payload=b"\xca\xfe")
-                assert response.message_type == MessageType.RESPONSE
-                assert response.return_code == ReturnCode.E_OK
+                try:
+                    response = client.call(METHOD, payload=b"\xca\xfe")
+                    assert response.message_type == MessageType.RESPONSE
+                    assert response.return_code == ReturnCode.E_OK
+                except RpcError:
+                    pass
 
     @pytest.mark.asyncio
     async def test_async_call_lifecycle(