Merge branch 'main' of https://github.com/abrinkman/usbipd-python

Author: Alexander Brinkman

.github/workflows/lint.yml

@@ -22,8 +22,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install ruff mypy
-          pip install -r requirements.txt
+          pip install -e ".[dev]"
 
       - name: Run Ruff linter
         run: ruff check .

.github/workflows/publish.yml

@@ -8,21 +8,25 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    environment: pypi
     permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
       contents: read
 
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.14"
+          python-version: "3.12"
 
       - name: Install build dependencies
         run: |
           python -m pip install --upgrade pip
           pip install build twine
+          pip install -e ".[dev]"
 
       - name: Verify tag format
         run: |
@@ -39,5 +43,3 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -4,58 +4,115 @@
 [![REUSE Compliant](https://img.shields.io/badge/reuse-compliant-green.svg)](https://reuse.software/)
 [![Lint](https://github.com/abrinkman/usbipd-python/actions/workflows/lint.yml/badge.svg)](https://github.com/abrinkman/usbipd-python/actions/workflows/lint.yml)
 
-A USB/IP server written in Python3 for sharing USB devices over the network, based on usbipd concepts. Works on MacOS using the `pyusb` library, but any system that supports `pyusb` and `libusb` should work.
+A USB/IP server written in Python 3 for sharing USB devices over the network. This implementation uses the `pyusb` library and the `libusb` backend to support cross-platform USB device access on macOS and Linux.
 
-Note: this is a very early proof-of-concept implementation, which was mainly built for learning purposes with
-Copilot assistance. For simple devices it seems to work OK, however for more complex or HID based devices you
-may run into issues. Some will be because of code quality, however other issues are more fundamental. For
-intance, HID devices are handled by the OS kernel drivers on Windows and MacOS and these drivers cannot be
-detached easily without writing OS native code and/or drivers. Contributions are welcome!
+> **Note:** This is an early-stage implementation, primarily created for learning purposes. Simple USB devices generally work well, but more complex or HID-based devices may experience issues. HID devices are managed by OS kernel drivers on macOS and Windows, making them difficult to detach without OS-native code or custom drivers. Contributions are welcome!
 
-## Preparing the environment
+## Installation
 
-Make sure you have a Python environment, with the required packages present. Or create a venv:
+### Users
 
-1. Create venv:
+Install from PyPI:
+
+```bash
+pip install usbipd-python
+usbipd --help
+```
+
+### Developers
+
+1. Clone the repository:
 
    ```bash
-   python3 -m venv .venv
+   git clone https://github.com/abrinkman/usbipd-python.git
+   cd usbipd-python
    ```
 
-2. Load the venv:
+2. Create and activate a virtual environment:
 
    ```bash
+   python3 -m venv .venv
    source .venv/bin/activate
    ```
 
-3. Install requirements:
+3. Install in development mode with dev dependencies:
 
    ```bash
-   pip install -r requirements.txt
+   pip install -e ".[dev]"
    ```
 
-## Running the application
+## System Requirements
 
-1. List USB devices:
+- **Python:** 3.9 or higher
+- **libusb:** Install using your system package manager
+  - macOS: `brew install libusb`
+  - Linux (Debian/Ubuntu): `sudo apt-get install libusb-1.0-0-dev`
+  - Linux (Fedora/RHEL): `sudo dnf install libusbx-devel`
 
-   ```bash
-   ./usbipd.py list
-   ```
+## Usage
 
-2. Bind a USB device by its bus ID:
+### List USB Devices
 
-   ```bash
-    ./usbipd.py bind --bus-id <bus-id>
-   ```
+Display all available USB devices:
 
-   Note that the application requires a bus-id, but the bindings are actually stored using the device's VID:PID:serial for persistence, so device binding remains valid even
-   if the bus-id changes. Devices without a serial number are matched by VID:PID only.
+```bash
+usbipd-python list
+```
 
-3. Start the USBIP server:
+### Bind a Device
 
-   ```bash
-    sudo ./usbipd.py start
-    ```
+Bind a USB device by its bus ID to make it available for sharing:
+
+```bash
+usbipd-python bind --bus-id <bus-id>
+```
+
+Bindings are stored persistently using the device's VID:PID:serial for future recognition, even if the bus ID changes. Devices without a serial number are matched by VID:PID only.
+
+### Start the Server
+
+Start the USB/IP server (requires root/sudo on macOS):
+
+```bash
+sudo usbipd-python start
+```
+
+Add `-v` or `--verbose` for debug output:
+
+```bash
+sudo usbipd-python -v start
+```
+
+### Connect to the Server
+
+Use a USB/IP client on another machine to connect and access shared devices.
+
+## Development
+
+### Code Quality
+
+Run linting and formatting checks using `ruff`:
+
+```bash
+ruff check .          # Check for linting issues
+ruff format --check . # Check code formatting
+ruff format .         # Auto-format code
+```
+
+Run type checking:
+
+```bash
+mypy --ignore-missing-imports .
+```
+
+### Project Structure
+
+- `usbipd.py` - Main CLI entry point using `argparse`
+- `usb_device.py` - `USBDevice` wrapper class for `pyusb` device access
+- `usbip_server.py` - `USBIPServer` class implementing the USB/IP protocol
+- `binding_configuration.py` - `BindingConfiguration` class for XML-based device binding storage
+- `libusb_backend.py` - Cross-platform libusb backend loader for `pyusb`
+
+### License
 
-    Note: Root privileges may be required to access USB devices on MacOS.
-4. Connect to the server from a client using USB/IP tools.
+Licensed under GPL-3.0. See [LICENSE](LICENSE) for details.

binding_configuration.py

@@ -4,7 +4,6 @@
 
 import os
 import xml.etree.ElementTree as ET
-from typing import Optional
 from xml.dom import minidom
 
 
@@ -13,7 +12,7 @@ class BindingConfiguration:
 
     DEFAULT_CONFIG_PATH = os.path.expanduser("~/.config/usbipd/bindings.xml")
 
-    def __init__(self, config_path: Optional[str] = None) -> None:
+    def __init__(self, config_path: str | None = None) -> None:
         """
         Initialize the BindingConfiguration instance.
 
@@ -135,9 +134,7 @@ def remove_binding(self, vendor_id: str, product_id: str, serial_number: str = "
 
         return False
 
-    def get_binding(
-        self, vendor_id: str, product_id: str, serial_number: str = ""
-    ) -> Optional[dict]:
+    def get_binding(self, vendor_id: str, product_id: str, serial_number: str = "") -> dict | None:
         """
         Get a specific binding by VID:PID:serial.
 

pyproject.toml

@@ -3,20 +3,18 @@ requires = ["setuptools>=61.0", "wheel", "setuptools-scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "usbipd-python"
+name = "usbipd"
 dynamic = ["version"]
-description = "A USB/IP server for sharing USB devices over the network"
+description = "A Python USB/IP server for sharing USB devices over the network"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 license = {text = "GPL-3.0"}
 authors = [
-    {name = "abrinkman", email = "abrinkman@github.com"},
+    {name = "Alexander Brinkman", email = "abrinkman@gmail.com"},
 ]
 keywords = ["usb", "usbip", "network", "device-sharing"]
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
@@ -30,6 +28,14 @@ classifiers = [
 
 dependencies = [
     "pyusb>=1.2.1",
+    "libusb>=1.0.26",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pip-tools>=7.0.0",
+    "ruff>=0.14.0",
+    "mypy>=1.0.0",
 ]
 
 [project.urls]
@@ -38,13 +44,13 @@ Repository = "https://github.com/abrinkman/usbipd-python.git"
 Issues = "https://github.com/abrinkman/usbipd-python/issues"
 
 [project.scripts]
-usbipd-python = "usbipd:main"
+usbipd = "usbipd:main"
 
 [tool.setuptools]
 py-modules = ["usbipd", "usb_device", "usbip_server", "binding_configuration", "libusb_backend"]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py311"
 line-length = 100
 
 [tool.ruff.lint]
@@ -55,11 +61,11 @@ ignore = [
 ]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.11"
 warn_return_any = true
 warn_unused_configs = true
 ignore_missing_imports = true
 
 [tool.setuptools_scm]
 # Version is derived from git tags (e.g., v0.1.0 -> 0.1.0)
-# If no tag, generates dev version like 0.1.0.dev1+g1234567
+# If no tag, generates dev version like 0.1.0.dev1+g1234567

requirements-dev.txt

@@ -9,7 +9,6 @@
 
 import logging
 import re
-from typing import Optional
 
 import usb.core
 import usb.util
@@ -35,13 +34,13 @@ def __init__(self, device: usb.core.Device) -> None:
         """
         self.device = device
         self.bus_id = self.build_bus_id(device)
-        self._manufacturer: Optional[str] = None
-        self._product: Optional[str] = None
-        self._serial_number: Optional[str] = None
+        self._manufacturer: str | None = None
+        self._product: str | None = None
+        self._serial_number: str | None = None
         self._strings_loaded = False
 
     @staticmethod
-    def clean_usb_string(value: Optional[str]) -> Optional[str]:
+    def clean_usb_string(value: str | None) -> str | None:
         """Clean a USB string by removing null characters and whitespace.
 
         USB strings sometimes contain garbage data after null terminators.
@@ -143,19 +142,19 @@ def product_id(self) -> int:
         return int(self.device.idProduct)
 
     @property
-    def manufacturer(self) -> Optional[str]:
+    def manufacturer(self) -> str | None:
         """Get the manufacturer string of the device."""
         self._load_strings()
         return self._manufacturer
 
     @property
-    def product(self) -> Optional[str]:
+    def product(self) -> str | None:
         """Get the product string of the device."""
         self._load_strings()
         return self._product
 
     @property
-    def serial_number(self) -> Optional[str]:
+    def serial_number(self) -> str | None:
         """Get the serial number string of the device."""
         self._load_strings()
         return self._serial_number
@@ -168,7 +167,7 @@ def device_id(self) -> str:
             return f"{self.vendor_id:04x}:{self.product_id:04x}:{self._serial_number}"
         return f"{self.vendor_id:04x}:{self.product_id:04x}"
 
-    def to_dict(self) -> dict[str, Optional[str]]:
+    def to_dict(self) -> Dict[str, Optional[str]]:
         """Get basic device information as a dictionary.
 
         Returns:
@@ -365,7 +364,7 @@ def list_devices(self) -> list[USBDevice]:
         devices = usb.core.find(find_all=True, backend=backend)
         return [USBDevice(device) for device in devices]
 
-    def find_by_bus_id(self, bus_id: str) -> Optional[USBDevice]:
+    def find_by_bus_id(self, bus_id: str) -> USBDevice | None:
         """Find a device by its bus ID.
 
         Args:
@@ -402,8 +401,8 @@ def find_by_identity(
         self,
         vendor_id: int,
         product_id: int,
-        serial_number: Optional[str] = None,
-    ) -> Optional[USBDevice]:
+        serial_number: str | None = None,
+    ) -> USBDevice | None:
         """Find a device by VID, PID, and optionally serial number.
 
         Args:
@@ -435,7 +434,7 @@ def find_by_identity(
 
         return None
 
-    def find_by_binding(self, binding: dict[str, str]) -> Optional[USBDevice]:
+    def find_by_binding(self, binding: Dict[str, str]) -> Optional[USBDevice]:
         """Find a device that matches a binding configuration.
 
         The binding dictionary should contain 'vendor_id', 'product_id',