MAC Address Validation in Python

import asyncio
import logging
import os
from isvalid_sdk import IsValidConfig, create_client

logger = logging.getLogger(__name__)
iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

async def validate_mac(mac: str) -> dict:
    result = await iv.mac_address(mac)

    if not result.valid:
        raise ValueError(f"Invalid MAC address: {mac!r}")

    if result.is_broadcast:
        raise ValueError("Broadcast address — not a valid device identifier")
    if result.is_multicast:
        raise ValueError("Multicast address — not suitable for device registration")
    if result.is_local:
        logger.warning("MAC %s is locally-administered — may be randomised", result.normalized)

    return result

# Register device — validate MAC and normalise before DB insert
async def register_device(raw_mac: str, device_name: str) -> dict:
    mac = await validate_mac(raw_mac)
    return {"mac": mac.normalized, "type": mac.type, "device_name": device_name}

# Batch validate from network scan
async def validate_network_scan(macs: list[str]) -> list[dict]:
    tasks = [iv.mac_address(m) for m in macs]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    return [
        {
            "mac": mac,
            "result": r if not isinstance(r, Exception) else None,
            "error": str(r) if isinstance(r, Exception) else None,
        }
        for mac, r in zip(macs, results)
    ]

async def main():
    device = await register_device("00-1B-44-11-3A-B7", "Raspberry Pi sensor")
    print(device["mac"])  # "00:1B:44:11:3A:B7"

asyncio.run(main())