python-usb 0.1.0__tar.gz

python_usb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_usb-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: python-usb
+Version: 0.1.0
+Summary: List all USB devices in a developer-friendly tree view (Windows/macOS/Linux)
+Author: Peter
+License: MIT
+Project-URL: Homepage, https://github.com/peterdemin/python-usb
+Project-URL: Issues, https://github.com/peterdemin/python-usb/issues
+Keywords: usb,devices,hardware,tree,cli,debug
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# python-usb
+
+List all USB devices in a developer-friendly tree view. Zero dependencies — works on **macOS**, **Linux**, and **Windows**.
+
+## Dev
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+python-usb
+```
+
+## Install
+
+```
+pip install python-usb
+```
+
+## Usage
+
+```
+python-usb
+```
+
+Example output (macOS):
+
+```
+└── USB 3.1 Bus
+    ├── USB Keyboard [05ac:024f]
+    │   Vendor:    Apple Inc.
+    │   Serial:    ABCD1234
+    │   Speed:     Full Speed
+    │   Power:     50 mA
+    ├── USB Mouse [046d:c077]
+    │   Vendor:    Logitech
+    │   Speed:     Low Speed
+    └── USB Hub [2109:2817]
+        Vendor:    VIA Labs, Inc.
+        Speed:     Super Speed
+        └── External SSD [0781:5583]
+            Vendor:    SanDisk
+            Serial:    12345678
+            Speed:     Super Speed
+            Power:     896 mA
+```
+
+### JSON output
+
+```
+python-usb --json
+```
+
+### What it shows
+
+| Field     | Description                      |
+|-----------|----------------------------------|
+| Name      | Product / device name            |
+| ID        | `vendor_id:product_id` (hex)     |
+| Vendor    | Manufacturer name                |
+| Serial    | Serial number                    |
+| Speed     | Low / Full / High / Super Speed  |
+| Class     | USB device class                 |
+| Driver    | Kernel driver in use             |
+| Location  | Bus and device number            |
+| Power     | Max power draw                   |
+| USB Ver   | USB specification version        |
+
+## How it works
+
+| Platform | Method                                    |
+|----------|-------------------------------------------|
+| macOS    | `system_profiler SPUSBDataType -json`      |
+| Linux    | `/sys/bus/usb/devices` sysfs (or `lsusb`) |
+| Windows  | PowerShell + WMI `Win32_PnPEntity`        |
+
+No compiled extensions, no `libusb` dependency.
+
+## Publish to PyPI
+
+1. Update the version in `pyproject.toml`.
+2. Create a PyPI API token at <https://pypi.org/manage/account/token/>.
+3. Install the publishing tools:
+
+```
+python -m pip install --upgrade build twine
+```
+
+4. Build the distribution files:
+
+```
+python -m build
+python -m twine check dist/*
+```
+
+5. Upload to PyPI:
+
+```
+python -m twine upload dist/*
+```
+
+Use `__token__` as the username and your PyPI API token as the password when prompted.
+
+## License
+
+MIT

python_usb-0.1.0/README.md

@@ -0,0 +1,106 @@
+# python-usb
+
+List all USB devices in a developer-friendly tree view. Zero dependencies — works on **macOS**, **Linux**, and **Windows**.
+
+## Dev
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+python-usb
+```
+
+## Install
+
+```
+pip install python-usb
+```
+
+## Usage
+
+```
+python-usb
+```
+
+Example output (macOS):
+
+```
+└── USB 3.1 Bus
+    ├── USB Keyboard [05ac:024f]
+    │   Vendor:    Apple Inc.
+    │   Serial:    ABCD1234
+    │   Speed:     Full Speed
+    │   Power:     50 mA
+    ├── USB Mouse [046d:c077]
+    │   Vendor:    Logitech
+    │   Speed:     Low Speed
+    └── USB Hub [2109:2817]
+        Vendor:    VIA Labs, Inc.
+        Speed:     Super Speed
+        └── External SSD [0781:5583]
+            Vendor:    SanDisk
+            Serial:    12345678
+            Speed:     Super Speed
+            Power:     896 mA
+```
+
+### JSON output
+
+```
+python-usb --json
+```
+
+### What it shows
+
+| Field     | Description                      |
+|-----------|----------------------------------|
+| Name      | Product / device name            |
+| ID        | `vendor_id:product_id` (hex)     |
+| Vendor    | Manufacturer name                |
+| Serial    | Serial number                    |
+| Speed     | Low / Full / High / Super Speed  |
+| Class     | USB device class                 |
+| Driver    | Kernel driver in use             |
+| Location  | Bus and device number            |
+| Power     | Max power draw                   |
+| USB Ver   | USB specification version        |
+
+## How it works
+
+| Platform | Method                                    |
+|----------|-------------------------------------------|
+| macOS    | `system_profiler SPUSBDataType -json`      |
+| Linux    | `/sys/bus/usb/devices` sysfs (or `lsusb`) |
+| Windows  | PowerShell + WMI `Win32_PnPEntity`        |
+
+No compiled extensions, no `libusb` dependency.
+
+## Publish to PyPI
+
+1. Update the version in `pyproject.toml`.
+2. Create a PyPI API token at <https://pypi.org/manage/account/token/>.
+3. Install the publishing tools:
+
+```
+python -m pip install --upgrade build twine
+```
+
+4. Build the distribution files:
+
+```
+python -m build
+python -m twine check dist/*
+```
+
+5. Upload to PyPI:
+
+```
+python -m twine upload dist/*
+```
+
+Use `__token__` as the username and your PyPI API token as the password when prompted.
+
+## License
+
+MIT

python_usb-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-usb"
+version = "0.1.0"
+description = "List all USB devices in a developer-friendly tree view (Windows/macOS/Linux)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [{name = "Peter"}]
+keywords = ["usb", "devices", "hardware", "tree", "cli", "debug"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Hardware",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+python-usb = "python_usb.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/peterdemin/python-usb"
+Issues = "https://github.com/peterdemin/python-usb/issues"

python_usb-0.1.0/python_usb/__init__.py

@@ -0,0 +1,3 @@
+"""python-usb: List all USB devices in a developer-friendly tree view."""
+
+__version__ = "0.1.0"

python_usb-0.1.0/python_usb/cli.py

@@ -0,0 +1,62 @@
+"""CLI entry point for python-usb."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List
+
+from . import __version__
+from .device import USBDevice
+from .discover import discover
+from .tree import render_tree
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="python-usb",
+        description="List USB devices in a developer-friendly tree view.",
+    )
+    parser.add_argument(
+        "-V", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-j", "--json",
+        action="store_true",
+        help="output as JSON instead of tree view",
+    )
+    parser.parse_args(argv)
+
+    try:
+        devices = discover()
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    args = parser.parse_args(argv)
+    if args.json:
+        print(json.dumps(_devices_to_dicts(devices), indent=2))
+    else:
+        render_tree(devices)
+
+
+def _devices_to_dicts(devices: List[USBDevice]) -> list:
+    return [_dev_dict(d) for d in devices]
+
+
+def _dev_dict(dev: USBDevice) -> dict:
+    d: dict = {"name": dev.name}
+    for attr in (
+        "vendor_id", "product_id", "vendor_name", "product_name",
+        "serial", "speed", "bus", "address", "device_class",
+        "driver", "max_power", "version", "port",
+    ):
+        val = getattr(dev, attr)
+        if val is not None:
+            d[attr] = val
+    if dev.children:
+        d["children"] = _devices_to_dicts(dev.children)
+    return d

python_usb-0.1.0/python_usb/device.py

@@ -0,0 +1,31 @@
+"""USB device data model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class USBDevice:
+    name: str
+    vendor_id: Optional[str] = None
+    product_id: Optional[str] = None
+    vendor_name: Optional[str] = None
+    product_name: Optional[str] = None
+    serial: Optional[str] = None
+    speed: Optional[str] = None
+    bus: Optional[str] = None
+    address: Optional[str] = None
+    device_class: Optional[str] = None
+    driver: Optional[str] = None
+    max_power: Optional[str] = None
+    version: Optional[str] = None
+    port: Optional[str] = None
+    children: List[USBDevice] = field(default_factory=list)
+
+    @property
+    def id_pair(self) -> str:
+        if self.vendor_id and self.product_id:
+            return f"{self.vendor_id}:{self.product_id}"
+        return ""

python_usb-0.1.0/python_usb/discover.py

@@ -0,0 +1,570 @@
+"""Cross-platform USB device discovery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+import os
+import platform
+import re
+import subprocess
+from pathlib import Path
+from typing import List, Optional
+
+from .device import USBDevice
+
+_USB_CLASSES = {
+    "00": "Per-interface",
+    "01": "Audio",
+    "02": "CDC-Comm",
+    "03": "HID",
+    "05": "Physical",
+    "06": "Image",
+    "07": "Printer",
+    "08": "Mass Storage",
+    "09": "Hub",
+    "0a": "CDC-Data",
+    "0b": "Smart Card",
+    "0d": "Content Security",
+    "0e": "Video",
+    "0f": "Personal Healthcare",
+    "10": "Audio/Video",
+    "11": "Billboard",
+    "12": "USB-C Bridge",
+    "dc": "Diagnostic",
+    "e0": "Wireless",
+    "ef": "Miscellaneous",
+    "fe": "Application Specific",
+    "ff": "Vendor Specific",
+}
+
+_IOREG_DEVICE_CLASSES = {"IOUSBHostDevice", "IOUSBDevice"}
+_IOREG_NODE_RE = re.compile(
+    r"^(?P<prefix>(?:\| |\s{2})*)\+-o (?P<name>.+?)  <class (?P<class_name>[^,>]+)"
+)
+_IOREG_PROPERTY_RE = re.compile(r'"(?P<key>[^"]+)"\s*=\s*(?P<value>.+)$')
+
+
+@dataclass
+class _MacOSIONode:
+    name: str
+    class_name: str
+    properties: dict[str, object] = field(default_factory=dict)
+    children: list[_MacOSIONode] = field(default_factory=list)
+
+
+def discover() -> List[USBDevice]:
+    """Return USB device tree for the current platform."""
+    system = platform.system()
+    if system == "Darwin":
+        return _discover_macos()
+    elif system == "Linux":
+        return _discover_linux()
+    elif system == "Windows":
+        return _discover_windows()
+    else:
+        raise RuntimeError(f"Unsupported platform: {system}")
+
+
+# ---------------------------------------------------------------------------
+# macOS
+# ---------------------------------------------------------------------------
+
+def _discover_macos() -> List[USBDevice]:
+    devices = _discover_macos_system_profiler()
+    if devices:
+        return devices
+    return _discover_macos_ioreg()
+
+
+def _discover_macos_system_profiler() -> List[USBDevice]:
+    try:
+        raw = subprocess.check_output(
+            ["system_profiler", "SPUSBDataType", "-json"],
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return []
+    data = json.loads(raw)
+    items = data.get("SPUSBDataType", [])
+    return [dev for item in items for dev in _parse_macos_item(item)]
+
+
+def _discover_macos_ioreg() -> List[USBDevice]:
+    try:
+        raw = subprocess.check_output(
+            ["ioreg", "-p", "IOUSB", "-w0", "-l"],
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return []
+    return _parse_macos_ioreg(raw.decode(errors="replace").splitlines())
+
+
+def _parse_macos_item(item: dict) -> List[USBDevice]:
+    devices: List[USBDevice] = []
+    if "_items" in item:
+        for child in item["_items"]:
+            devices.extend(_parse_macos_entry(child))
+    else:
+        devices.extend(_parse_macos_entry(item))
+    return devices
+
+
+def _parse_macos_entry(entry: dict) -> List[USBDevice]:
+    vid_pid = entry.get("vendor_id", ""), entry.get("product_id", "")
+
+    vid_raw = entry.get("vendor_id", "") or ""
+    pid_raw = entry.get("product_id", "") or ""
+    vid = _extract_hex(vid_raw)
+    pid = _extract_hex(pid_raw)
+
+    speed_raw = entry.get("device_speed", "")
+    speed = _normalise_speed(speed_raw)
+
+    dev = USBDevice(
+        name=entry.get("_name", "Unknown"),
+        vendor_id=vid,
+        product_id=pid,
+        vendor_name=entry.get("manufacturer", None),
+        serial=entry.get("serial_num", None),
+        speed=speed,
+        bus=entry.get("location_id", "").split("/")[0] if entry.get("location_id") else None,
+        max_power=entry.get("bus_power_used", entry.get("bus_power", None)),
+        device_class=None,
+    )
+    if "_items" in entry:
+        for child in entry["_items"]:
+            dev.children.extend(_parse_macos_entry(child))
+    return [dev]
+
+
+def _parse_macos_ioreg(lines: List[str]) -> List[USBDevice]:
+    roots: list[_MacOSIONode] = []
+    stack: list[_MacOSIONode] = []
+    current_node: Optional[_MacOSIONode] = None
+    in_properties = False
+
+    for line in lines:
+        node_match = _IOREG_NODE_RE.match(line)
+        if node_match:
+            depth = len(node_match.group("prefix")) // 2
+            node = _MacOSIONode(
+                name=_strip_ioreg_location(node_match.group("name").strip()),
+                class_name=node_match.group("class_name"),
+            )
+            stack = stack[:depth]
+            if stack:
+                stack[-1].children.append(node)
+            else:
+                roots.append(node)
+            stack.append(node)
+            current_node = node
+            in_properties = False
+            continue
+
+        if current_node is None:
+            continue
+
+        stripped = line.strip()
+        block_marker = stripped.replace("|", "").strip()
+        if block_marker == "{":
+            in_properties = True
+            continue
+        if block_marker == "}":
+            in_properties = False
+            continue
+        if not in_properties:
+            continue
+
+        property_match = _IOREG_PROPERTY_RE.search(line)
+        if property_match:
+            current_node.properties[property_match.group("key")] = _parse_ioreg_value(
+                property_match.group("value")
+            )
+
+    return _macos_ioreg_nodes_to_devices(roots)
+
+
+def _macos_ioreg_nodes_to_devices(nodes: List[_MacOSIONode]) -> List[USBDevice]:
+    devices: List[USBDevice] = []
+    for node in nodes:
+        child_devices = _macos_ioreg_nodes_to_devices(node.children)
+        if node.class_name not in _IOREG_DEVICE_CLASSES:
+            devices.extend(child_devices)
+            continue
+        devices.append(_macos_ioreg_node_to_device(node, child_devices))
+    return devices
+
+
+def _macos_ioreg_node_to_device(node: _MacOSIONode, children: List[USBDevice]) -> USBDevice:
+    location_id = _coerce_int(node.properties.get("locationID"))
+    device_class = _coerce_int(node.properties.get("bDeviceClass"))
+
+    dev = USBDevice(
+        name=_first_value(
+            node.properties.get("USB Product Name"),
+            node.properties.get("kUSBProductString"),
+            node.name,
+            "Unknown",
+        )
+        or "Unknown",
+        vendor_id=_format_hex_id(node.properties.get("idVendor")),
+        product_id=_format_hex_id(node.properties.get("idProduct")),
+        vendor_name=_first_value(
+            node.properties.get("USB Vendor Name"),
+            node.properties.get("kUSBVendorString"),
+        ),
+        serial=_first_value(
+            node.properties.get("USB Serial Number"),
+            node.properties.get("kUSBSerialNumberString"),
+        ),
+        speed=_normalise_ioreg_speed(
+            node.properties.get("UsbLinkSpeed"),
+            node.properties.get("Device Speed"),
+            node.properties.get("USBSpeed"),
+        ),
+        bus=_macos_bus_from_location_id(location_id),
+        address=_first_value(
+            node.properties.get("USB Address"),
+            node.properties.get("kUSBAddress"),
+        ),
+        device_class=_USB_CLASSES.get(f"{device_class:02x}", f"{device_class:02x}")
+        if device_class is not None
+        else None,
+        max_power=_format_current_ma(node.properties.get("UsbPowerSinkAllocation")),
+        version=_decode_bcd(node.properties.get("bcdUSB")),
+        port=_format_location_id(location_id),
+    )
+    dev.children.extend(children)
+    return dev
+
+
+def _extract_hex(value: str) -> Optional[str]:
+    m = re.search(r"0x([0-9a-fA-F]{4})", str(value))
+    return m.group(1).lower() if m else (value.strip() or None)
+
+
+def _format_hex_id(value: object) -> Optional[str]:
+    numeric = _coerce_int(value)
+    if numeric is not None:
+        return f"{numeric:04x}"
+    text = _stringify(value)
+    return _extract_hex(text) if text else None
+
+
+def _normalise_ioreg_speed(link_speed: object, *fallbacks: object) -> Optional[str]:
+    bits_per_second = _coerce_int(link_speed)
+    if bits_per_second is not None:
+        if bits_per_second <= 2_000_000:
+            return "Low Speed"
+        if bits_per_second <= 20_000_000:
+            return "Full Speed"
+        if bits_per_second <= 600_000_000:
+            return "High Speed"
+        if bits_per_second <= 6_000_000_000:
+            return "Super Speed"
+        return "Super Speed+"
+
+    speed_codes = {
+        0: "Low Speed",
+        1: "Full Speed",
+        2: "High Speed",
+        3: "Super Speed",
+        4: "Super Speed+",
+    }
+    for value in fallbacks:
+        numeric = _coerce_int(value)
+        if numeric is not None and numeric in speed_codes:
+            return speed_codes[numeric]
+        text = _stringify(value)
+        if text:
+            return _normalise_speed(text)
+    return None
+
+
+def _normalise_speed(raw: str) -> Optional[str]:
+    if not raw:
+        return None
+    low = raw.lower().replace("_", " ").strip()
+    for label in ("super speed plus", "super speed", "high speed", "full speed", "low speed"):
+        if label.replace(" ", "") in low.replace(" ", ""):
+            return label.title()
+    if "10" in low:
+        return "Super Speed+ (10 Gbps)"
+    if "5" in low:
+        return "Super Speed (5 Gbps)"
+    return raw
+
+
+def _parse_ioreg_value(raw: str) -> object:
+    raw = raw.strip()
+    if raw.startswith('"') and raw.endswith('"'):
+        return raw[1:-1]
+    if raw == "Yes":
+        return True
+    if raw == "No":
+        return False
+    numeric = _coerce_int(raw)
+    if numeric is not None:
+        return numeric
+    return raw
+
+
+def _coerce_int(value: object) -> Optional[int]:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            return int(text, 0)
+        except ValueError:
+            return None
+    return None
+
+
+def _stringify(value: object) -> Optional[str]:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _first_value(*values: object) -> Optional[str]:
+    for value in values:
+        text = _stringify(value)
+        if text:
+            return text
+    return None
+
+
+def _strip_ioreg_location(name: str) -> str:
+    return re.sub(r"@[0-9A-Fa-f]+$", "", name)
+
+
+def _macos_bus_from_location_id(location_id: Optional[int]) -> Optional[str]:
+    if location_id is None:
+        return None
+    bus = location_id >> 24
+    return str(bus) if bus else None
+
+
+def _format_location_id(location_id: Optional[int]) -> Optional[str]:
+    if location_id is None:
+        return None
+    return f"0x{location_id:08x}"
+
+
+def _format_current_ma(value: object) -> Optional[str]:
+    current = _coerce_int(value)
+    if current is None:
+        return None
+    return f"{current} mA"
+
+
+def _decode_bcd(value: object) -> Optional[str]:
+    numeric = _coerce_int(value)
+    if numeric is None:
+        return None
+    digits = f"{numeric:04x}"
+    return f"{int(digits[:2])}.{digits[2:]}"
+
+
+# ---------------------------------------------------------------------------
+# Linux
+# ---------------------------------------------------------------------------
+
+_SYSFS = Path("/sys/bus/usb/devices")
+
+
+def _discover_linux() -> List[USBDevice]:
+    if not _SYSFS.is_dir():
+        return _discover_linux_lsusb()
+    return _build_linux_tree()
+
+
+def _build_linux_tree() -> List[USBDevice]:
+    devices_by_path: dict[str, USBDevice] = {}
+    root_buses: List[str] = []
+
+    for entry in sorted(_SYSFS.iterdir()):
+        name = entry.name
+        # Skip interfaces like 1-1:1.0
+        if ":" in name:
+            continue
+        dev = _read_sysfs_device(entry)
+        devices_by_path[name] = dev
+        # Root hubs are "usbN"
+        if name.startswith("usb"):
+            root_buses.append(name)
+
+    # Build hierarchy: "1-2.3" is child of "1-2", "1-2" is child of "usb1"
+    for path, dev in devices_by_path.items():
+        if path.startswith("usb"):
+            continue
+        parent_path = _linux_parent_path(path)
+        if parent_path and parent_path in devices_by_path:
+            devices_by_path[parent_path].children.append(dev)
+
+    return [devices_by_path[rb] for rb in sorted(root_buses) if rb in devices_by_path]
+
+
+def _linux_parent_path(path: str) -> Optional[str]:
+    # "1-2.3.4" -> "1-2.3"; "1-2" -> "usb1"
+    if "." in path:
+        return path.rsplit(".", 1)[0]
+    m = re.match(r"(\d+)-", path)
+    if m:
+        return f"usb{m.group(1)}"
+    return None
+
+
+def _read_sysfs_device(path: Path) -> USBDevice:
+    def _read(attr: str) -> Optional[str]:
+        try:
+            return (path / attr).read_text().strip() or None
+        except (OSError, PermissionError):
+            return None
+
+    vid = _read("idVendor")
+    pid = _read("idProduct")
+    bclass = _read("bDeviceClass")
+    speed_mbs = _read("speed")
+    speed = f"{speed_mbs} Mbps" if speed_mbs else None
+
+    return USBDevice(
+        name=_read("product") or path.name,
+        vendor_id=vid,
+        product_id=pid,
+        vendor_name=_read("manufacturer"),
+        serial=_read("serial"),
+        speed=speed,
+        bus=_read("busnum"),
+        address=_read("devnum"),
+        device_class=_USB_CLASSES.get((bclass or "").lower(), bclass),
+        driver=_read_driver(path),
+        max_power=_read("bMaxPower"),
+        version=_read("version"),
+        port=path.name,
+    )
+
+
+def _read_driver(path: Path) -> Optional[str]:
+    driver_link = path / "driver"
+    try:
+        if driver_link.is_symlink():
+            return os.path.basename(os.readlink(str(driver_link)))
+    except OSError:
+        pass
+    return None
+
+
+def _discover_linux_lsusb() -> List[USBDevice]:
+    """Fallback: parse lsusb output (flat list, no tree)."""
+    try:
+        raw = subprocess.check_output(["lsusb"], stderr=subprocess.DEVNULL, timeout=10)
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return []
+    devices: List[USBDevice] = []
+    for line in raw.decode(errors="replace").splitlines():
+        m = re.match(
+            r"Bus\s+(\d+)\s+Device\s+(\d+):\s+ID\s+([0-9a-f]{4}):([0-9a-f]{4})\s+(.*)",
+            line,
+        )
+        if m:
+            devices.append(USBDevice(
+                name=m.group(5).strip() or "Unknown",
+                vendor_id=m.group(3),
+                product_id=m.group(4),
+                bus=m.group(1),
+                address=m.group(2),
+            ))
+    return devices
+
+
+# ---------------------------------------------------------------------------
+# Windows
+# ---------------------------------------------------------------------------
+
+def _discover_windows() -> List[USBDevice]:
+    return _discover_windows_powershell()
+
+
+def _discover_windows_powershell() -> List[USBDevice]:
+    ps_script = r"""
+Get-CimInstance Win32_USBControllerDevice | ForEach-Object {
+    $dep = $_.Dependent
+    $ref = $dep.ToString()
+    if ($ref -match 'DeviceID="(.+?)"') {
+        $devId = $Matches[1] -replace '\\\\', '\\'
+    } else { return }
+    $dev = Get-CimInstance Win32_PnPEntity | Where-Object { $_.DeviceID -eq $devId } | Select-Object -First 1
+    if (-not $dev) { return }
+    $vid = ''; $pid = ''
+    if ($devId -match 'VID_([0-9A-Fa-f]{4})') { $vid = $Matches[1].ToLower() }
+    if ($devId -match 'PID_([0-9A-Fa-f]{4})') { $pid = $Matches[1].ToLower() }
+    [PSCustomObject]@{
+        Name = $dev.Name
+        DeviceID = $devId
+        VID = $vid
+        PID = $pid
+        Manufacturer = $dev.Manufacturer
+        Description = $dev.Description
+        Service = $dev.Service
+        Status = $dev.Status
+    }
+} | ConvertTo-Json -Depth 3
+"""
+    try:
+        raw = subprocess.check_output(
+            ["powershell", "-NoProfile", "-Command", ps_script],
+            stderr=subprocess.DEVNULL,
+            timeout=15,
+        )
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return []
+
+    text = raw.decode(errors="replace").strip()
+    if not text:
+        return []
+
+    data = json.loads(text)
+    if isinstance(data, dict):
+        data = [data]
+
+    hubs: dict[str, USBDevice] = {}
+    orphans: List[USBDevice] = []
+
+    for item in data:
+        dev_id = item.get("DeviceID", "")
+        dev = USBDevice(
+            name=item.get("Name") or item.get("Description") or "Unknown",
+            vendor_id=item.get("VID") or None,
+            product_id=item.get("PID") or None,
+            vendor_name=item.get("Manufacturer"),
+            driver=item.get("Service"),
+            port=dev_id,
+        )
+        if "hub" in (dev.name or "").lower():
+            hubs[dev_id] = dev
+        else:
+            placed = False
+            for hub_id, hub in hubs.items():
+                if dev_id.startswith(hub_id.rsplit("\\", 1)[0]):
+                    hub.children.append(dev)
+                    placed = True
+                    break
+            if not placed:
+                orphans.append(dev)
+
+    result: List[USBDevice] = list(hubs.values())
+    result.extend(orphans)
+    return result

python_usb-0.1.0/python_usb/tree.py

@@ -0,0 +1,80 @@
+"""Render USB device tree to the terminal."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, TextIO
+
+from .device import USBDevice
+
+# ANSI color helpers — disabled when output is not a tty.
+_USE_COLOR = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+_RESET = "\033[0m" if _USE_COLOR else ""
+_BOLD = "\033[1m" if _USE_COLOR else ""
+_DIM = "\033[2m" if _USE_COLOR else ""
+_CYAN = "\033[36m" if _USE_COLOR else ""
+_YELLOW = "\033[33m" if _USE_COLOR else ""
+_GREEN = "\033[32m" if _USE_COLOR else ""
+_MAGENTA = "\033[35m" if _USE_COLOR else ""
+_WHITE = "\033[97m" if _USE_COLOR else ""
+
+_PIPE = "│   "
+_TEE = "├── "
+_LAST = "└── "
+_BLANK = "    "
+
+
+def render_tree(devices: List[USBDevice], file: TextIO = sys.stdout) -> None:
+    if not devices:
+        print("No USB devices found.", file=file)
+        return
+    for i, dev in enumerate(devices):
+        _render_node(dev, "", i == len(devices) - 1, file)
+
+
+def _render_node(dev: USBDevice, prefix: str, is_last: bool, file: TextIO) -> None:
+    connector = _LAST if is_last else _TEE
+
+    title = f"{_BOLD}{_WHITE}{dev.name}{_RESET}"
+    id_str = ""
+    if dev.id_pair:
+        id_str = f" {_CYAN}[{dev.id_pair}]{_RESET}"
+    print(f"{prefix}{connector}{title}{id_str}", file=file)
+
+    child_prefix = prefix + (_BLANK if is_last else _PIPE)
+
+    details = _detail_lines(dev)
+    for line in details:
+        print(f"{child_prefix}{_DIM}{line}{_RESET}", file=file)
+
+    for i, child in enumerate(dev.children):
+        _render_node(child, child_prefix, i == len(dev.children) - 1, file)
+
+
+def _detail_lines(dev: USBDevice) -> List[str]:
+    lines: List[str] = []
+
+    if dev.vendor_name:
+        lines.append(f"Vendor:    {dev.vendor_name}")
+    if dev.serial:
+        lines.append(f"Serial:    {dev.serial}")
+    if dev.speed:
+        lines.append(f"Speed:     {dev.speed}")
+    if dev.device_class:
+        lines.append(f"Class:     {dev.device_class}")
+    if dev.driver:
+        lines.append(f"Driver:    {dev.driver}")
+    if dev.bus or dev.address:
+        loc_parts = []
+        if dev.bus:
+            loc_parts.append(f"Bus {dev.bus}")
+        if dev.address:
+            loc_parts.append(f"Dev {dev.address}")
+        lines.append(f"Location:  {', '.join(loc_parts)}")
+    if dev.max_power:
+        lines.append(f"Power:     {dev.max_power}")
+    if dev.version:
+        lines.append(f"USB Ver:   {dev.version}")
+
+    return lines

python_usb-0.1.0/python_usb.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: python-usb
+Version: 0.1.0
+Summary: List all USB devices in a developer-friendly tree view (Windows/macOS/Linux)
+Author: Peter
+License: MIT
+Project-URL: Homepage, https://github.com/peterdemin/python-usb
+Project-URL: Issues, https://github.com/peterdemin/python-usb/issues
+Keywords: usb,devices,hardware,tree,cli,debug
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# python-usb
+
+List all USB devices in a developer-friendly tree view. Zero dependencies — works on **macOS**, **Linux**, and **Windows**.
+
+## Dev
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+python-usb
+```
+
+## Install
+
+```
+pip install python-usb
+```
+
+## Usage
+
+```
+python-usb
+```
+
+Example output (macOS):
+
+```
+└── USB 3.1 Bus
+    ├── USB Keyboard [05ac:024f]
+    │   Vendor:    Apple Inc.
+    │   Serial:    ABCD1234
+    │   Speed:     Full Speed
+    │   Power:     50 mA
+    ├── USB Mouse [046d:c077]
+    │   Vendor:    Logitech
+    │   Speed:     Low Speed
+    └── USB Hub [2109:2817]
+        Vendor:    VIA Labs, Inc.
+        Speed:     Super Speed
+        └── External SSD [0781:5583]
+            Vendor:    SanDisk
+            Serial:    12345678
+            Speed:     Super Speed
+            Power:     896 mA
+```
+
+### JSON output
+
+```
+python-usb --json
+```
+
+### What it shows
+
+| Field     | Description                      |
+|-----------|----------------------------------|
+| Name      | Product / device name            |
+| ID        | `vendor_id:product_id` (hex)     |
+| Vendor    | Manufacturer name                |
+| Serial    | Serial number                    |
+| Speed     | Low / Full / High / Super Speed  |
+| Class     | USB device class                 |
+| Driver    | Kernel driver in use             |
+| Location  | Bus and device number            |
+| Power     | Max power draw                   |
+| USB Ver   | USB specification version        |
+
+## How it works
+
+| Platform | Method                                    |
+|----------|-------------------------------------------|
+| macOS    | `system_profiler SPUSBDataType -json`      |
+| Linux    | `/sys/bus/usb/devices` sysfs (or `lsusb`) |
+| Windows  | PowerShell + WMI `Win32_PnPEntity`        |
+
+No compiled extensions, no `libusb` dependency.
+
+## Publish to PyPI
+
+1. Update the version in `pyproject.toml`.
+2. Create a PyPI API token at <https://pypi.org/manage/account/token/>.
+3. Install the publishing tools:
+
+```
+python -m pip install --upgrade build twine
+```
+
+4. Build the distribution files:
+
+```
+python -m build
+python -m twine check dist/*
+```
+
+5. Upload to PyPI:
+
+```
+python -m twine upload dist/*
+```
+
+Use `__token__` as the username and your PyPI API token as the password when prompted.
+
+## License
+
+MIT

python_usb-0.1.0/python_usb.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+python_usb/__init__.py
+python_usb/cli.py
+python_usb/device.py
+python_usb/discover.py
+python_usb/tree.py
+python_usb.egg-info/PKG-INFO
+python_usb.egg-info/SOURCES.txt
+python_usb.egg-info/dependency_links.txt
+python_usb.egg-info/entry_points.txt
+python_usb.egg-info/top_level.txt

python_usb-0.1.0/python_usb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_usb-0.1.0/python_usb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+python-usb = python_usb.cli:main

python_usb-0.1.0/python_usb.egg-info/top_level.txt

@@ -0,0 +1 @@
+python_usb

python_usb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+