fix: warn on C++ extension load failure and add Python 3.14 wheel support

The C++ extension import failure was silently swallowed, causing transport
classes to degrade to no-op stubs without any user-visible indication.
Emit an ImportWarning with the error details and a macOS-specific hint
about libc++ ABI mismatches when Homebrew LLVM is in PATH.

Add cp314 to the cibuildwheel build matrix so pre-built wheels are
published for Python 3.14 (stable since Oct 2025). Skip free-threaded
builds (*t-*) until thread safety is validated. Update CI test matrix
and pyproject.toml classifiers accordingly.

Add a Troubleshooting section to the README covering the ABI mismatch
and silent no-op transport symptoms.

Made-with: Cursor

Author: vtz

.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 

.github/workflows/wheels.yml

@@ -28,8 +28,8 @@ jobs:
           CIBW_ARCHS_LINUX: x86_64 aarch64
           CIBW_ARCHS_MACOS: x86_64 arm64
           CIBW_ARCHS_WINDOWS: AMD64
-          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-*"
-          CIBW_SKIP: "*-musllinux*"
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+          CIBW_SKIP: "*-musllinux* *t-*"
           CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
           CIBW_MANYLINUX_AARCH64_IMAGE: manylinux2014
           CIBW_TEST_COMMAND: pytest {project}/tests -v --ignore={project}/tests/integration

README.md

@@ -177,6 +177,52 @@ and type checking.
 | `opensomeip.client` | `SomeIpClient` — high-level client composing all components |
 | `opensomeip.receiver` | `MessageReceiver` — sync/async message iterator |
 
+## Troubleshooting
+
+### macOS: C++ extension fails to load (`ImportError` / symbol not found)
+
+When installing from source on macOS (e.g. `pip install opensomeip` on a Python
+version for which no pre-built wheel is available), the C++ extension may fail to
+load at runtime with an error like:
+
+```
+ImportError: dlopen(…/_opensomeip.cpython-3xx-darwin.so, 0x0002):
+  symbol not found in flat namespace '__ZNSt3__113__hash_memoryEPKvm'
+```
+
+**Cause:** If [Homebrew LLVM](https://formulae.brew.sh/formula/llvm) is installed
+and its `clang++` appears in `PATH` before `/usr/bin/clang++`, CMake will use it
+during the build. Homebrew's compiler ships a newer libc++ than the one bundled
+with macOS, so the compiled extension references symbols that don't exist in the
+system library loaded at runtime.
+
+**Fix — rebuild with the system compiler:**
+
+```bash
+CC=/usr/bin/clang CXX=/usr/bin/clang++ \
+  pip install --no-cache-dir --force-reinstall --no-binary=opensomeip opensomeip
+```
+
+**Tip:** Pre-built wheels (available for Python 3.10 – 3.14 on macOS, Linux, and
+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)
+
+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:
+
+```bash
+python -W all your_script.py
+```
+
+If you see the warning, follow the steps in the section above to fix the
+extension build.
+
 ## Development
 
 ```bash

pyproject.toml

@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: C++",
     "Topic :: System :: Networking",
     "Topic :: Software Development :: Libraries :: Python Modules",

src/opensomeip/_bridge.py

@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 import functools
+import warnings
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -32,8 +33,19 @@ def _load_extension() -> Any:
         _ext = _opensomeip
         HAS_NATIVE = True
         return _ext
-    except ImportError:
+    except ImportError as exc:
         HAS_NATIVE = False
+        _msg = (
+            f"opensomeip C++ extension failed to load: {exc}\n"
+            "Transport classes will run as no-op stubs (no sockets will be opened).\n"
+            "On macOS, this is often caused by a libc++ ABI mismatch when building "
+            "from source with a non-system compiler (e.g. Homebrew LLVM). "
+            "Rebuild with the system compiler:\n"
+            "  CC=/usr/bin/clang CXX=/usr/bin/clang++ "
+            "pip install --no-cache-dir --force-reinstall --no-binary=opensomeip opensomeip\n"
+            "See https://github.com/vtz/opensomeip-python#troubleshooting for details."
+        )
+        warnings.warn(_msg, ImportWarning, stacklevel=2)
         return None