feat: switch from libusb to libusb-package-tng for Python 3.14+ support

- Replace `libusb>=1.0.27; sys_platform == 'win32'` with
  `libusb-package-tng>=1.0.29.0` in pyproject.toml (cross-platform,
  no per-Python-release rebuilds needed)
- Update `init_libusb_windows()` in stm32_dfu.py to use the new
  `libusb_package_tng.find_library` API with OS fallback
- Add `TestInitLibusbWindows` test class covering the new behaviour:
  find_library usage, caching, fallback, and error on missing backend

Closes #101

Author: Copilot

=1.0.29.0

@@ -13,21 +13,25 @@ def init_libusb_windows():
     """
     Initializes the libusb backend on Windows and caches it module-wide.
 
+    Uses libusb_package_tng which embeds pre-built libusb binaries and supports
+    Python 3.14+ without requiring per-release package updates.
+
     Returns:
         The usb backend object if successful, None otherwise.
     """
     global _libusb_backend
     if _libusb_backend is not None:
         return _libusb_backend
 
-    import libusb  # type: ignore
+    import libusb_package_tng  # type: ignore
     import usb.backend.libusb1 as libusb1
 
-    arch = "x86_64" if platform.architecture()[0] == "64bit" else "x86"
-    libusb1_dll = Path(libusb.__file__).parent / "_platform" / "windows" / arch / "libusb-1.0.dll"
-    if not libusb1_dll.exists():
-        raise FileNotFoundError(f"libusb1.dll not found at {libusb1_dll}")
-    _libusb_backend = libusb1.get_backend(find_library=lambda x: libusb1_dll.as_posix())
+    _libusb_backend = libusb1.get_backend(find_library=libusb_package_tng.find_library)
+    if _libusb_backend is None:
+        # Fall back to any OS-provided libusb
+        _libusb_backend = libusb1.get_backend()
+    if _libusb_backend is None:
+        raise RuntimeError("Could not find a usable libusb backend")
     return _libusb_backend
 
 

mpflash/flash/stm32_dfu.py

@@ -37,7 +37,7 @@ dependencies = [
     "questionary>=2.0.0",
     "jsonlines>=4.0.0",
     "jsons>=1.6.3",
-    "libusb>=1.0.27; sys_platform == 'win32'",
+    "libusb-package-tng>=1.0.29.0",
     "pywin32>=310; sys_platform == 'win32'",
     "loguru>=0.7.2",
     "mpremote>=1.22.0",

pyproject.toml

@@ -62,6 +62,91 @@ def test_windows_calls_libusb_init(self, mock_platform):
             mock_init.assert_called_once()
 
 
+# ---------------------------------------------------------------------------
+# init_libusb_windows
+# ---------------------------------------------------------------------------
+
+
+class TestInitLibusbWindows:
+    def setup_method(self):
+        """Reset the cached backend before each test."""
+        import mpflash.flash.stm32_dfu as mod
+
+        mod._libusb_backend = None
+
+    def test_uses_libusb_package_tng_find_library(self):
+        """init_libusb_windows passes libusb_package_tng.find_library to get_backend."""
+        mock_backend = MagicMock()
+        mock_tng = MagicMock()
+        mock_tng.find_library = MagicMock()
+
+        with (
+            patch.dict("sys.modules", {"libusb_package_tng": mock_tng}),
+            patch("usb.backend.libusb1.get_backend", return_value=mock_backend) as mock_get,
+        ):
+            from mpflash.flash import stm32_dfu
+
+            stm32_dfu._libusb_backend = None
+            result = stm32_dfu.init_libusb_windows()
+
+        mock_get.assert_called_once_with(find_library=mock_tng.find_library)
+        assert result is mock_backend
+
+    def test_caches_backend_on_second_call(self):
+        """init_libusb_windows returns cached result without re-importing on second call."""
+        mock_backend = MagicMock()
+        mock_tng = MagicMock()
+
+        with (
+            patch.dict("sys.modules", {"libusb_package_tng": mock_tng}),
+            patch("usb.backend.libusb1.get_backend", return_value=mock_backend) as mock_get,
+        ):
+            from mpflash.flash import stm32_dfu
+
+            stm32_dfu._libusb_backend = None
+            first = stm32_dfu.init_libusb_windows()
+            second = stm32_dfu.init_libusb_windows()
+
+        assert first is second
+        # get_backend should only be called once due to caching
+        mock_get.assert_called_once()
+
+    def test_falls_back_to_os_backend_when_tng_returns_none(self):
+        """Falls back to OS-provided libusb when libusb_package_tng returns None."""
+        mock_os_backend = MagicMock()
+        mock_tng = MagicMock()
+
+        def fake_get_backend(find_library=None):
+            if find_library is not None:
+                return None  # tng found nothing
+            return mock_os_backend  # OS fallback
+
+        with (
+            patch.dict("sys.modules", {"libusb_package_tng": mock_tng}),
+            patch("usb.backend.libusb1.get_backend", side_effect=fake_get_backend),
+        ):
+            from mpflash.flash import stm32_dfu
+
+            stm32_dfu._libusb_backend = None
+            result = stm32_dfu.init_libusb_windows()
+
+        assert result is mock_os_backend
+
+    def test_raises_runtime_error_when_no_backend_found(self):
+        """Raises RuntimeError when neither libusb_package_tng nor OS provides a backend."""
+        mock_tng = MagicMock()
+
+        with (
+            patch.dict("sys.modules", {"libusb_package_tng": mock_tng}),
+            patch("usb.backend.libusb1.get_backend", return_value=None),
+        ):
+            from mpflash.flash import stm32_dfu
+
+            stm32_dfu._libusb_backend = None
+            with pytest.raises(RuntimeError, match="libusb backend"):
+                stm32_dfu.init_libusb_windows()
+
+
 # ---------------------------------------------------------------------------
 # flash_stm32_dfu – guard conditions
 # ---------------------------------------------------------------------------