Command API

Helpers to call lspci in a more Pythonic way.

class pylspci.command.IDResolveOption(value)

lspci device, vendor, class names outputting options.

Both = '-nn'

Output both the names and hexadecimal IDs, in the format Name [ID].

IDOnly = '-n'

Only output the hexadecimal IDs. This is the only option that does not require a pciids file.

NameOnly = ''

Only output the names.

pylspci.command.list_access_methods() → List[str]

Calls lspci(access_method='help') to list the PCI access methods the underlying pcilib provides and parses the human-readable list into a machine-readable list.

Returns:

A list of access methods.

Return type:

List[str]

Raises:

subprocess.CalledProcessError – lspci returned a non-zero error code.

pylspci.command.list_pcilib_params() → List[PCIAccessParameter]

Calls lspci -Ohelp to list the PCI access parameters the underlying pcilib provides and parse the human-readable list into a machine-readable list.

Returns:

A list of available PCI access parameters.

Return type:

List[PCIAccessParameter]

Raises:

subprocess.CalledProcessError – lspci returned a non-zero error code.

pylspci.command.list_pcilib_params_raw() → List[str]

Calls lspci -Ohelp to list the PCI access parameters the underlying pcilib provides.

Returns:

A list of available PCI access parameters.

Return type:

List[str]

Raises:

subprocess.CalledProcessError – lspci returned a non-zero error code.

pylspci.command.lspci(pciids: Optional[Union[str, Path]] = None, pcimap: Optional[Union[str, Path]] = None, access_method: Optional[str] = None, pcilib_params: Mapping[str, Any] = {}, file: Optional[Union[str, Path]] = None, verbose: bool = False, kernel_drivers: bool = False, bridge_paths: bool = False, hide_single_domain: bool = True, id_resolve_option: IDResolveOption = IDResolveOption.Both, slot_filter: Optional[Union[SlotFilter, str]] = None, device_filter: Optional[Union[DeviceFilter, str]] = None) → str

Call the lspci command with various parameters.

Parameters:

• pciids (str or Path or None) – An optional path to a pciids file, to convert hexadecimal class, vendor or device IDs into names.

• pcimap (str or Path or None) – An optional path to a pcimap file, linking Linux kernel modules and their supported PCI IDs.

• access_method (str or None) – The access method to use to find devices. Set this to help to list the available access methods in a human-readable format. For the machine-readable format, see list_access_methods().

• pcilib_params (Mapping[str, Any] or None) – Parameters passed to pcilib’s access methods. To list the available parameters with their description and default values, see list_pcilib_params().

• file (str or Path or None) – An hexadecimal dump from lspci -x to load data from, instead of accessing real hardware.

• verbose (bool) – Increase verbosity. This radically changes the output format.

• kernel_drivers (bool) – Also include kernel modules and drivers in the output. Only has effect with the verbose output.

• bridge_paths (bool) – Add PCI bridge paths to slot numbers.

• hide_single_domain (bool) – If there is a single PCI domain on this machine and it is numbered 0000, hide it from the slot numbers.

• id_resolve_option (IDResolveOption) – Device, vendor or class ID outputting mode. See the IDResolveOption docs for more details.

• slot_filter (SlotFilter or str or None) – Filter devices by their slot (domain, bus, device, function)

• device_filter (DeviceFilter or str or None) – Filter devices by their vendor, device or class ID

Returns:

Any output from the lspci command.

Return type:

str

Raises:

subprocess.CalledProcessError – lspci returned a non-zero error code.

Command builder

class pylspci.command.CommandBuilder(**kwargs: Any)

Helper class to build a lspci call using a Builder pattern.

Iterating over the builder will result in the command being called, and will return strings, devices or pcilib parameters, one at a time, depending on the parsing settings.

__iter__() → Iterator[Union[str, Device, PCIAccessParameter]]

device_filter(*args: str, cls: Optional[int] = None, vendor: Optional[int] = None, device: Optional[int] = None) → CommandBuilder

Filter the devices logically. Can be passed a string in lspci’s filter syntax, or keyword arguments for each portion of the filter. See pylspci.filters.DeviceFilter.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

from_file(path: Optional[Union[str, Path]], check: bool = True) → CommandBuilder

Use a hexadecimal dump from a previous run of lspci instead of accessing the host’s devices directly.

Parameters:

• path (str or Path or None) – A string or path-like object pointing to the hex dump file to use. Set to None to not use a dump file.

• check (bool) – Whether to check for the file’s existence immediately, or delay that to the lspci invocation.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

hide_single_domain(value: bool = True) → CommandBuilder

Hide the domain numbers when there is only one domain, numbered zero.

Parameters:

value (bool) – Whether or not to hide the domain numbers for a single domain.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

include_bridge_paths(value: bool = True) → CommandBuilder

Include the PCI bridge paths along with the IDs. Implies .with_ids().

Parameters:

value (bool) – Whether or not to include the PCI bridge paths.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

include_kernel_drivers(value: bool = True) → CommandBuilder

Under Linux, includes the available kernel modules for each device. Implies .verbose().

Parameters:

value (bool) – Whether or not to include the available kernel modules for each device.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

list_access_methods(value: bool = True) → CommandBuilder

List the pcilib access methods instead of listing devices.

Parameters:

value (bool) – Whether or not to list the access methods.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

list_pcilib_params(value: bool = True, raw: bool = False) → CommandBuilder

List the pcilib parameters instead of listing devices.

Parameters:

• value (bool) – Whether or not to list the pcilib parameters.

• raw (bool) – When listing the pcilib parameters, whether to return the raw strings or parse them into PCIAccessParameter instances.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

slot_filter(*args: str, domain: Optional[int] = None, bus: Optional[int] = None, device: Optional[int] = None, function: Optional[int] = None) → CommandBuilder

Filter the devices geographically. Can be passed a string in lspci’s filter syntax, or keyword arguments for each portion of the filter. See pylspci.filters.SlotFilter.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

use_access_method(method: Optional[str]) → CommandBuilder

Use a specific access method to list all devices.

Parameters:

method (str or None) – Name of the access method to use. Set to None to use lspci’s default method.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

use_pciids(path: Optional[Union[str, Path]], check: bool = True) → CommandBuilder

Use a PCI IDs file from a given path.

Parameters:

• path (str or Path or None) – A string or path-like object pointing to the PCI IDs file to use. Set to None to use the default files from lspci.

• check (bool) – Whether to check for the file’s existence immediately, or delay that to the lspci invocation.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

use_pcimap(path: Optional[Union[str, Path]], check: bool = True) → CommandBuilder

Use a kernel module mapping file from a given path.

Parameters:

• path (str or Path or None) – A string or path-like object pointing to the mapping file to use. Set to None to use the default files from lspci.

• check (bool) – Whether to check for the file’s existence immediately, or delay that to the lspci invocation.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

verbose(value: bool = True) → CommandBuilder

Enable verbose mode.

Parameters:

value (bool) – Whether or not to use verbose mode.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

with_default_parser() → CommandBuilder

Use the default parser compatible with the current set of settings. Note that this should be used as one of the last instructions of the builder, as the default parser can change if the settings are updated.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

with_ids(value: bool = True) → CommandBuilder

Include PCI device IDs. If disabled, implies .with_names().

Parameters:

value (bool) – Whether or not to include the PCI device IDs.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

with_names(value: bool = True) → CommandBuilder

Include PCI device names. If disabled, implies .with_ids().

Parameters:

value (bool) – Whether or not to include the PCI device names.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

with_parser(parser: Optional[Parser] = None) → CommandBuilder

Use a pylspci parser to get parsed Device instances instead of strings.

Parameters:

parser (pylspci.parsers.Parser) – The parser to use. Set to None to disable parsing.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

with_pcilib_params(*args: Mapping[str, Any], **kwargs: Any) → CommandBuilder

Override some pcilib parameters. When given a dict, will rewrite the parameters with the new dict. When given keyword arguments, will update the existing parameters. Pass None or {} to reset all of the parameters.

Returns:

The current CommandBuilder instance.

Return type:

CommandBuilder

Device selection

class pylspci.filters.DeviceFilter(*, cls: Optional[int] = None, vendor: Optional[int] = None, device: Optional[int] = None)

Describes a device filter, to filter devices logically.

Any field set to None will remove filtering.

Create a filter.

cls: Optional[int] = None

Device class ID, as a four-digit hexadecimal number.

device: Optional[int] = None

Device ID, as a four-digit hexadecimal number.

vendor: Optional[int] = None

Device vendor ID, as a four-digit hexadecimal number.

class pylspci.filters.Filter(**kwargs: Any)

Create a filter.

classmethod parse(value: str) → T

class pylspci.filters.SlotFilter(*, domain: Optional[int] = None, bus: Optional[int] = None, device: Optional[int] = None, function: Optional[int] = None)

Describes a slot filter, to filter devices geographically.

Any field set to None will remove filtering.

Create a filter.

bus: Optional[int] = None

Device bus, as a two-digit hexadecimal number.

device: Optional[int] = None

Device number, as a two-digit hexadecimal number, up to 0x1f.

domain: Optional[int] = None

Device domain, as a four-digit hexadecimal number.

function: Optional[int] = None

The slot’s function, as a single octal digit.