Install & Compatibility
Where this runs
tested against v0.4.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SimpleParser
✓ from pylspci import SimpleParser
✗ from pylspci import ScannerPCI
This quickstart demonstrates how to connect to a target (local or remote) using `pylspci.ScannerPCI` and then retrieve and filter PCI devices. It uses environment variables for sensitive credentials in remote connection examples. Ensure the target machine has `pciutils` installed and appropriate network access and authentication are configured.
import os
from pylspci import ScannerPCI
# Example for a remote connection, using environment variables for credentials
# For local scan, if current user can run lspci without sudo, password can be omitted.
# If local scan requires sudo, provide password or ensure user has sudo access without password.
# Replace with your target IP, username, and ensure PCI_PASSWORD is set in your environment
target_ip = os.environ.get('PCI_HOST_IP', '127.0.0.1')
username = os.environ.get('PCI_USERNAME', 'root')
password = os.environ.get('PCI_PASSWORD', '')
try:
# Connect to the target machine
# For local machine requiring sudo, you'd typically pass ip='127.0.0.1', password=password
# For remote, provide IP, username, and password.
if target_ip == '127.0.0.1' and not password: # Attempt local without password if not explicitly set
scanner = ScannerPCI(ip=target_ip)
elif target_ip == '127.0.0.1': # Local with password
scanner = ScannerPCI(ip=target_ip, password=password)
else: # Remote connection
scanner = ScannerPCI(ip=target_ip, username=username, password=password)
# Select all PCI devices
devices = scanner.select()
print(f"Found {len(devices)} PCI devices:")
for device in devices:
print(f" - {device.slot}: {device.vendor_name} {device.device_name} ({device.device_class_name})")
# Example: Find all network controllers
network_controllers = scanner.select(device_class_name='*Ethernet*')
if network_controllers:
print("\nNetwork Controllers:")
for nc in network_controllers:
print(f" - {nc.slot}: {nc.vendor_name} {nc.device_name}")
else:
print("\nNo network controllers found.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe underlying `lspci` command requires `sudo` privileges for full functionality and especially for accessing detailed configuration space information. If `pylspci` is run without sufficient permissions, it may return incomplete data or fail to connect. For local scans, provide a password if the user is not root; for remote scans, ensure the user has `sudo` access.fixEnsure the user executing the Python script has necessary permissions to run `lspci` (e.g., password-less sudo) or provide credentials to `ScannerPCI` for elevated access. For remote access, the user specified must have sudo privileges on the target machine.
affects: All versions
gotchaUsing extremely verbose `lspci` options (like `lspci -xxx` for hexadecimal dump of configuration space) can, in rare cases, crash certain PCI devices, potentially leading to system instability or data loss. While `pylspci` primarily uses `lspci -mmnn`, direct interaction with `lspci` or future `pylspci` features that expose more verbose modes should be handled with caution.fixAvoid direct `lspci -xxx` commands. When using `pylspci`, be aware of the underlying `lspci` behavior. Report any unexpected system instability to `pylspci` developers if it occurs during normal operation.
affects: All versions (inherent to `lspci` utility)
Upgrade
Version history
0.4.3latest on PyPI · released Aug 4, 2022
Audit
Dependencies
pciutilsrequiredProvides the `lspci` command-line tool, which `pylspci` parses. Must be installed on the target machine (local or remote).