Typing for MFD

Module containing common data structures and utilities shared between MFD modules.

Supported structures

OSType

Structure for supported types of OS (compatible with platform.system)

class OSType(str, Enum):
    """Available OS types."""

    WINDOWS = "nt"
    POSIX = "posix"
    EFISHELL = "efishell"

OSName

Structure for supported names of OS (compatible with os.name)

class OSName(str, Enum):
    """Available os names."""

    WINDOWS = "Windows"
    LINUX = "Linux"
    FREEBSD = "FreeBSD"
    ESXI = "VMkernel"
    EFISHELL = "EFIShell"

OSBitness

Structure for bitness of OS

class OSBitness(str, Enum):
    """Available OS bitnesses."""

    OS_32BIT = "32bit"
    OS_64BIT = "64bit"

WindowsFlavour

Structure for supported Windows OS Versions

class WindowsFlavour(Enum):
    """Available Windows System Flavours."""
    WindowsServer2012R2 = "Microsoft Windows Server 2012 R2"
    WindowsServer2016 = "Microsoft Windows Server 2016"     # Windows-10.0.14393
    WindowsServer2019 = "Microsoft Windows Server 2019"     # Windows-10.0.17763
    WindowsServer2022 = "Microsoft Windows Server 2022"     # Windows-10.0.20348
    WindowsServer2025 = "Microsoft Windows Server 2025"     # Windows-10.0.26100
    WindowsServer2022H2 = "Microsoft Windows Server 2022 H2"   # Windows-10.0.22621
    AzureStackHCI22H2 = "Microsoft Azure Stack HCI 22H2"  # Windows-10.0.20349
    AzureStackHCI23H2 = "Microsoft Azure Stack HCI 23H2"  # Windows-10.0.25398
    AzureStackHCI24H2 = "Microsoft Azure Stack HCI 24H2"  # Windows-10.0.26100

CPUBitness

Structure for available CPU bitnesses

class CPUBitness(str, Enum):
    """Available CPU bitnesses."""

    CPU_32BIT = "32bit"
    CPU_64BIT = "64bit"

CPUArchitecture

Structure for available CPU architectures

class CPUArchitecture(str, Enum):
    """Available CPU architectures."""

    X86 = "x86"
    X86_64 = "x86-64"
    ARM = "ARM"
    ARM64 = "ARM64"

SystemInfo

Generic Information about the System Under Test

@dataclass
class SystemInfo:
    """Generic Information about the System Under Test."""

    host_name: str | None = None  # WINDOWS-2019
    os_name: str | None = None  # Microsoft Windows Server 2019 Standard
    os_version: str | None = None  # 10.0.17763 N/A Build 17763
    kernel_version: str | None = None  # 17763
    system_boot_time: str | None = None  # 4/4/2023, 2:40:55 PM
    system_manufacturer: str | None = None  # Intel Corporation
    system_model: str | None = None  # S2600BPB
    system_bitness: OSBitness | None = None  # x64-based PC -> OSBitness.OS_64BIT
    bios_version: str | None = None  # Intel Corporation SE5C620.86B.02.01.0012.070720200218, 7/7/2020
    total_memory: str | None = None  # 130,771 MB
    architecture_info: str | None = None  # x86_64

MACAddress

Structure for representing mac address

For more information on this class please check out netaddr documentation: here

Represents mac address in standard IEEE mac_eui48 format by default, raises exception if input is not MAC 48b format

Usage Examples:

• mac = MACAddress("00-1B-77-49-54-FD")
• int(mac) -> 117965411581
• hex(mac) -> '0x1b774954fd'
• oct(mac) -> '01556722252375'
• mac.bits() -> '00000000-00011011-01110111-01001001-01010100-11111101'
• mac.bin -> '0b1101101110111010010010101010011111101'
• str(MACAddress(mac1)) -> '00:1b:77:49:54:fd'
• MACAddress(mac1) == MACAddress(mac2)
• MACAddress(mac1) > MACAddress(mac2)
• MACAddress(mac1) < MACAddress(mac2)

Implemented methods

get_random_mac() -> MACAddress : Generate a random MAC address.

get_random_multicast_mac() -> MACAddress : Generate multicast MAC starting from '01:00:5e:xx:xx:xx', with the last 3 octets randomize.

get_random_unicast_mac() -> MACAddress : Generate unicast MAC starting from 'fa:xx:xx:xx:xx:xx'

get_random_mac_using_prefix(prefix: str = None) -> MACAddress : Generate a random MAC address from the range prefix:xx:xx:xx - prefix:xx:xx:xx. If prefix is not passed the MAC address generated will be fa:11:11:xx:xx:xx.

parse_mac(mac: MACAddress) -> str: Parse mac in special way to get i.e. from 3c:fd:fe:bc:b7:68 -> {0xffff,0xffff,0xffff}. The function creates a list from string and chops it to 3x 2 byte, and reverses bytes order for each couple.

InterfaceType

Structure for network interface types.

Available types:

• InterfaceType.GENERIC : default
• InterfaceType.ETH_CONTROLLER : network controller listed on pci (default for network device without loaded driver)
• InterfaceType.VIRTUAL_DEVICE : interface located in path ../devices/virtual/net/ (bridge, macvlan, loopback)
• InterfaceType.PF : regular physical interface; located on PCI bus (../devices/pci0000/..) (eth)
• InterfaceType.VF : virtual inteface (SRIOV); described as 'Virtual Interface' in lspci detailed info
• InterfaceType.VPORT : IPU-specific interface which shares PCI Address with other interfaces (extra VSI Info stored in VsiInfo)
• InterfaceType.VMNIC : ESXi-specific interface, not used in Linux
• InterfceType.VMBUS : Hyper-V specific for Linux Guests (https://docs.kernel.org/virt/hyperv/vmbus.html)
• InterfaceType.MANAGEMENT : interface having IPv4 Address in range of management network (from mfd_const.mfd_const import MANAGEMENT_NETWORK)
• InterfaceType.VLAN : virtual device which is assigned to 802.1Q VLAN (extra VLAN details stored in VlanInterfaceInfo)
• InterfaceType.CLUSTER_MANAGEMENT : cluster management interface type
• InterfaceType.CLUSTER_STORAGE : storage / compute interfaces in cluster nodes, marked as vSMB in system
• InterfaceType.BTS : Linux: BTS shares PCI bus, device ID and index, we will mark it based on name starting with nac
• InterfaceType.BOND : Linux: Bonding interface, which is a virtual interface that combines multiple physical interfaces into a single logical interface
• InterfaceType.BOND_SLAVE : Linux: Bonding interface slave, which is a physical interface that is part of a bonding interface

VlanInterfaceInfo

Structure for VSI Info

@dataclass
class VlanInterfaceInfo:
    """Structure for vlan interface info."""
    vlan_id: int
    parent: Optional[str] = None

VsiInfo

Structure for VSI Info

@dataclass
class VsiInfo:
    """Structure for VSI Info."""
    
    fn_id: int
    host_id: int
    is_vf: bool
    vsi_id: int
    vport_id: int
    is_created: bool
    is_enabled: bool

ClusterInfo

Structure for cluster Info

@dataclass
class ClusterInfo:
    """Structure for cluster info."""

    node: Optional[str] = None
    network: Optional[str] = None

InterfaceInfo

Structure for network interface info

@dataclass
class InterfaceInfo:
    """
    Structure for network interface info.

    All possible fields that can be helpful, while creating network interface.
    """

    pci_address: Optional[PCIAddress] = None
    pci_device: Optional[PCIDevice] = None
    name: Optional[str] = None
    interface_type: InterfaceType = InterfaceType.GENERIC
    mac_address: Optional[MACAddress] = None
    installed: Optional[bool] = None
    branding_string: Optional[str] = None
    vlan_info: Optional[VlanInterfaceInfo] = None

@dataclass
class LinuxInterfaceInfo(InterfaceInfo):
    """
    Structure for Linux network interface info.

    All possible fields that can be helpful, while creating network interface.
    """

    namespace: Optional[str] = None
    vsi_info: Optional[VsiInfo] = None

@dataclass
class WindowsInterfaceInfo(InterfaceInfo):
    """
    Structure for Windows network interface info.

    All possible fields that can be helpful, while creating network interface.
    """

    description: Optional[str] = None
    index: Optional[str] = None
    manufacturer: Optional[str] = None
    net_connection_status: Optional[str] = None
    pnp_device_id: Optional[str] = None
    product_name: Optional[str] = None
    service_name: Optional[str] = None
    guid: Optional[str] = None
    speed: Optional[str] = None
    cluster_info: Optional[ClusterInfo] = None

DriverInfo

Structure for information about driver.

@dataclass
class DriverInfo:
    """Structure for information about driver."""

    driver_name: str
    driver_version: str

For more information on this class please check out netaddr documentation: here

Raises exception if the input is not valid IPv4 or IPv6 address.

Usage examples

• ip = IPAddress('192.0.2.1')
• ip.version -> 4
• str(ip) -> '192.0.2.1'
• int(ip) -> 3221225985
• hex(ip) -> '0xc0000201'
• ip.bin -> '0b11000000000000000000001000000001'
• ip.bits() -> '11000000.00000000.00000010.00000001'
• ip.words() -> (192, 0, 2, 1)
• ip.is_multicast()
• ip.is_reserved()
• IPAddress(ip1) == IPAddress(ip2)

IPNetwork

Structure for representing IPv4 and IPv6 network or subnet

For more information on this class please check out netaddr documentation: here

Usage examples

• ip = IPNetwork('192.0.2.1/0')
• broadcast_ip = IPNetwork('192.0.2.0/24').broadcast
• IPNetwork('192.0.2.0/24').size
• ip = IPNetwork('fe80::dead:beef/64')
• netmask = IPNetwork('192.0.2.1/16').prefixlen

PCIAddress

Structure for representing pci address.

Structure contains domain, bus, slot and func as int's, but can convert input parameters into int, such as str, double

Example:

from mfd_typing.pci_address import PCIAddress
pci = PCIAddress('0', 0.0, '0', 0.0)
# PCIAddress(0,0,0,0)
print(pci.domain)
print(pci.bus)
print(pci.slot)
print(pci.func)

As an alternative, string with short bdf or full lspci can be provided as PCIAddress input parameter into data variable.

Example:

from mfd_typing.pci_address import PCIAddress
pci = PCIAddress("0000:00:00.0")
# equivalent of PCIAddress(0,0,0,0)
pci = PCIAddress("00:00.0")
# equivalent of PCIAddress(0,0,0,0) because `domain` default will be se on `0`

Usage examples

• PCIAddress(0, 94, 0, 1).sbdf == "00:094:00:01"
• PCIAddress(0, 26, 10, 1).lspci == "0000:1a:0a.1"
• PCI Address from hex to decimal -> PCIAddress(0xFFFF, 0xFF, 0x1F, 0x7).sbdf == "65535:255:31:07"
• PCI Address from decimal to hex -> PCIAddress(0, 26, 10, 1).lspci == "0000:1a:0a.1"
• PCIAddress(0, 0xFF, 0x1F, 0x7).lspci_short == "ff:1f.7"

PCIDevice

Structure for PCIDevice description: VendorID, DeviceID, SubVendorID, SubDeviceID

Usage:

PCIDevice(vendor_id: VendorID, device_id: DeviceID, sub_vendor_id: SubVendorID, sub_device_id: SubDeviceID) either: PCIDevice(data="vendor_id:device_id:sub_vendor_id:sub_device_id") where data are in string format separated by colon. or: PCIDevice(data="vendor_id:device_id") where data are in string format and default 0000 sub_vendor_id and sub_device_id are set.

where IDs can handle string or hexadecimal value in constructor IDs are hashable and comparable, the same as PCIDevice's

dataclass utils

Helper methods for dataclasses' typing:

• get_field_type - Get type hint of given field of given model.
• convert_value_field_to_typehint_type - Convert value of dataclass field to type expected in typehints for this field.

utils

Generic API's supported in MFD-Typing

Implemented methods

decimal_to_hex(decimal_value: Union[str, int]) -> str : Convert decimal value to hexadecimal.

decimal_to_bin(decimal_value: Union[str, int]) -> str : Convert decimal value to binary number.

get_number_based_on_string(input_string: str, range_of_results: int = 100) -> int : Get calculated number based on provided string from specific range.

compare_numbers_as_unsigned(number_1: int, number_2: int) -> bool : Compare numbers as unsigned. This accounts for possible overflow on negative values.

compare_non_conforming_versions(version_1: str, version_2: str) -> int : Compare versions that cannot be compared using StrictVersion class.

convert_port_dc_to_port_hex(port: Union[int, str]) : Convert Port number to comma separated hexadecimal port number.

convert_ip_dc_to_ip_hex(ip: "IPAddress", pad_ipv6_len=False) -> str : Convert IP address to comma separated hexadecimal IP address.

get_windows_version_from_kernel(kernel_version: str) -> WindowsFlavour : Map Kernel Version to Windows Flavour

strtobool(param: Union[str, bool]) -> bool : Convert strings to boolean True or False. "true", "yes", "1", "y", "t", "on" are cast to True, "false", "no", "0", "n", "f", "off" are cast to False, case insensitive

convert_ip_dc_to_hex_value(ip: "IPv4Address | IPv6Address | IPv4Interface | IPv6Interface") -> str: : Convert the IP value to its HEX value.

convert_ip_to_brackets_colon_format(ip: "IPAddress") -> str : Parse an IP address in a special way. The function creates a list from string and chops it to 2x 2 byte or 8x 2 byte, and reverses bytes order for each couple. For example:

• 1.2.1.1 -> {0x0201,0x0101}
• fe80::3efd:feff:febc:b4c9 -> {0x80fe,0x0000,0x0000,0x0000,0xfd3e,0xfffe,0xbcfe,0xc9b4}

convert_mac_string_to_hex(mac: str) -> str:: Convert the MAC string value to its HEX value.

format_mac_string_to_canonical(mac: str) -> str:: Format any mac format to canonical

get_sed_inline(act_line: str, new_line: str, filename: "str | Path", line_idx: int | str = 0) -> str - Prepare sed command with all needed parameters.

prepare_sed_string(input_str: str, pattern: str) -> str - Prepare str to be parsed as a literal string by sed.

OSNames for Switches

SWITCHES_OS_NAME_REGEXES contains regexes for OS names for switches.

SWITCHES_OS_NAME_REGEXES = {
    OSName.MELLANOX:
        [r"Onyx", r"SX_PPC_M460EX", r"MLNX-OS"]
}

OS supported:

• LNX
• WINDOWS
• ESXI
• FREEBSD
• EFI Shell

Issue reporting

If you encounter any bugs or have suggestions for improvements, you're welcome to contribute directly or open an issue here.