# -*- coding: utf-8 -*-
# http://web.archive.org/web/20140718071917/http://multivax.com/last_question.html

"""
Get the MAC address of remote hosts or network interfaces.

It provides a platform-independent interface to get the MAC addresses of:

- System network interfaces (by interface name)
- Remote hosts on the local network (by IPv4/IPv6 address or hostname)

It provides one function: ``get_mac_address()``

.. code-block:: python
   :caption: Examples

    from getmac import get_mac_address
    eth_mac = get_mac_address(interface="eth0")
    win_mac = get_mac_address(interface="Ethernet 3")
    ip_mac = get_mac_address(ip="192.168.0.1")
    ip6_mac = get_mac_address(ip6="::1")
    host_mac = get_mac_address(hostname="localhost")
    updated_mac = get_mac_address(ip="10.0.0.1", network_request=True)

"""
import ctypes
import logging
import os
import platform
import re
import shlex
import socket
import struct
import sys
import traceback
import warnings
from subprocess import CalledProcessError, check_output

try:  # Python 3
    from subprocess import DEVNULL  # type: ignore
except ImportError:  # Python 2
    DEVNULL = open(os.devnull, "wb")  # type: ignore

# Used for mypy (a data type analysis tool)
# If you're copying the code, this section can be safely removed
try:
    from typing import TYPE_CHECKING

    if TYPE_CHECKING:
        from typing import Dict, List, Optional, Set, Tuple, Type, Union
except ImportError:
    pass

# Configure logging
log = logging.getLogger("getmac")  # type: logging.Logger
if not log.handlers:
    log.addHandler(logging.NullHandler())

__version__ = "0.9.4"

PY2 = sys.version_info[0] == 2  # type: bool

# Configurable settings
DEBUG = 0  # type: int
PORT = 55555  # type: int

# Monkeypatch shutil.which for python 2.7 (TODO(python3): remove shutilwhich.py)
if PY2:
    from .shutilwhich import which
else:
    from shutil import which

# Platform identifiers
if PY2:
    _UNAME = platform.uname()  # type: Tuple[str, str, str, str, str, str]
    _SYST = _UNAME[0]  # type: str
else:
    _UNAME = platform.uname()  # type: platform.uname_result
    _SYST = _UNAME.system  # type: str
if _SYST == "Java":
    try:
        import java.lang

        _SYST = str(java.lang.System.getProperty("os.name"))
    except ImportError:
        _java_err_msg = "Can't determine OS: couldn't import java.lang on Jython"
        log.critical(_java_err_msg)
        warnings.warn(_java_err_msg, RuntimeWarning)

WINDOWS = _SYST == "Windows"  # type: bool
DARWIN = _SYST == "Darwin"  # type: bool

OPENBSD = _SYST == "OpenBSD"  # type: bool
FREEBSD = _SYST == "FreeBSD"  # type: bool
NETBSD = _SYST == "NetBSD"  # type: bool
SOLARIS = _SYST == "SunOS"  # type: bool

# Not including Darwin or Solaris as a "BSD"
BSD = OPENBSD or FREEBSD or NETBSD  # type: bool

# Windows Subsystem for Linux (WSL)
WSL = False  # type: bool
LINUX = False  # type: bool
if _SYST == "Linux":
    if "Microsoft" in platform.version():
        WSL = True
    else:
        LINUX = True

# NOTE: "Linux" methods apply to Android without modifications
# If there's Android-specific stuff then we can add a platform
# identifier for it.
ANDROID = (
    hasattr(sys, "getandroidapilevel") or "ANDROID_STORAGE" in os.environ
)  # type: bool

# Generic platform identifier used for filtering methods
PLATFORM = _SYST.lower()  # type: str
if PLATFORM == "linux" and "Microsoft" in platform.version():
    PLATFORM = "wsl"

# User-configurable override to force a specific platform
# This will change to a function argument in 1.0.0
OVERRIDE_PLATFORM = ""  # type: str

# Force a specific method to be used for all lookups
# Used for debugging and testing
FORCE_METHOD = ""  # type: str

# Get and cache the configured system PATH on import
# The process environment does not change after a process is started
PATH = os.environ.get("PATH", os.defpath).split(os.pathsep)  # type: List[str]
if not WINDOWS:
    PATH.extend(("/sbin", "/usr/sbin"))
else:
    # TODO: Prevent edge case on Windows where our script "getmac.exe"
    #   gets added to the path ahead of the actual Windows getmac.exe
    #   This just handles case where it's in a virtualenv, won't work /w global scripts
    PATH = [p for p in PATH if "\\getmac\\Scripts" not in p]
# Build the str after modifications are made
PATH_STR = os.pathsep.join(PATH)  # type: str

# Use a copy of the environment so we don't
# modify the process's current environment.
ENV = dict(os.environ)  # type: Dict[str, str]
ENV["LC_ALL"] = "C"  # Ensure ASCII output so we parse correctly

# Constants
IP4 = 0
IP6 = 1
INTERFACE = 2
HOSTNAME = 3

MAC_RE_COLON = r"([0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5})"
MAC_RE_DASH = r"([0-9a-fA-F]{2}(?:-[0-9a-fA-F]{2}){5})"
# On OSX, some MACs in arp output may have a single digit instead of two
# Examples: "18:4f:32:5a:64:5", "14:cc:20:1a:99:0"
# This can also happen on other platforms, like Solaris
MAC_RE_SHORT = r"([0-9a-fA-F]{1,2}(?::[0-9a-fA-F]{1,2}){5})"

# Ensure we only log the Python 2 warning once
WARNED_UNSUPPORTED_PYTHONS = False

# Cache of commands that have been checked for existence by check_command()
CHECK_COMMAND_CACHE = {}  # type: Dict[str, bool]


def check_command(command):
    # type: (str) -> bool
    if command not in CHECK_COMMAND_CACHE:
        CHECK_COMMAND_CACHE[command] = bool(which(command, path=PATH_STR))
    return CHECK_COMMAND_CACHE[command]


def check_path(filepath):
    # type: (str) -> bool
    return os.path.exists(filepath) and os.access(filepath, os.R_OK)


def _clean_mac(mac):
    # type: (Optional[str]) -> Optional[str]
    """Check and format a string result to be lowercase colon-separated MAC."""
    if mac is None:
        return None

    # Handle cases where it's bytes (which are the same as str in PY2)
    mac = str(mac)
    if not PY2:  # Strip bytestring conversion artifacts
        # TODO(python3): check for bytes and decode instead of this weird hack
        for garbage_string in ["b'", "'", "\\n", "\\r"]:
            mac = mac.replace(garbage_string, "")

    # Remove trailing whitespace, make lowercase, remove spaces,
    # and replace dashes '-' with colons ':'.
    mac = mac.strip().lower().replace(" ", "").replace("-", ":")

    # Fix cases where there are no colons
    if ":" not in mac and len(mac) == 12:
        log.debug("Adding colons to MAC %s", mac)
        mac = ":".join(mac[i : i + 2] for i in range(0, len(mac), 2))

    # Pad single-character octets with a leading zero (e.g. Darwin's ARP output)
    elif len(mac) < 17:
        log.debug(
            "Length of MAC %s is %d, padding single-character octets with zeros",
            mac,
            len(mac),
        )
        parts = mac.split(":")
        new_mac = []
        for part in parts:
            if len(part) == 1:
                new_mac.append("0" + part)
            else:
                new_mac.append(part)
        mac = ":".join(new_mac)

    # MAC address should ALWAYS be 17 characters before being returned
    if len(mac) != 17:
        log.warning("MAC address %s is not 17 characters long!", mac)
        mac = None
    elif mac.count(":") != 5:
        log.warning("MAC address %s is missing colon (':') characters", mac)
        mac = None
    return mac


def _read_file(filepath):
    # type: (str) -> Optional[str]
    try:
        with open(filepath) as f:
            return f.read()
    # This is IOError on Python 2.7
    except (OSError, IOError):  # noqa: B014
        log.debug("Could not find file: '%s'", filepath)
        return None


def _search(regex, text, group_index=0, flags=0):
    # type: (str, str, int, int) -> Optional[str]
    if not text:
        if DEBUG:
            log.debug("No text to _search()")
        return None

    match = re.search(regex, text, flags)
    if match:
        return match.groups()[group_index]

    return None


def _popen(command, args):
    # type: (str, str) -> str
    for directory in PATH:
        executable = os.path.join(directory, command)
        if (
            os.path.exists(executable)
            and os.access(executable, os.F_OK | os.X_OK)
            and not os.path.isdir(executable)
        ):
            break
    else:
        executable = command

    if DEBUG >= 3:
        log.debug("Running: '%s %s'", executable, args)

    return _call_proc(executable, args)


def _call_proc(executable, args):
    # type: (str, str) -> str
    if WINDOWS:
        cmd = executable + " " + args  # type: ignore
    else:
        cmd = [executable] + shlex.split(args)  # type: ignore

    output = check_output(cmd, stderr=DEVNULL, env=ENV)

    if DEBUG >= 4:
        log.debug("Output from '%s' command: %s", executable, str(output))

    if not PY2 and isinstance(output, bytes):
        return str(output, "utf-8")
    else:
        return str(output)


def _uuid_convert(mac):
    # type: (int) -> str
    return ":".join(("%012X" % mac)[i : i + 2] for i in range(0, 12, 2))


def _fetch_ip_using_dns():
    # type: () -> str
    """
    Determines the IP address of the default network interface.

    Sends a UDP packet to Cloudflare's DNS (``1.1.1.1``), which should go through
    the default interface. This populates the source address of the socket,
    which we then inspect and return.
    """
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    s.connect(("1.1.1.1", 53))
    ip = s.getsockname()[0]
    s.close()  # NOTE: sockets don't have context manager in 2.7 :(
    return ip


class Method:
    #: Valid platform identifier strings
    VALID_PLATFORM_NAMES = {
        "android",
        "darwin",
        "linux",
        "windows",
        "wsl",
        "openbsd",
        "freebsd",
        "sunos",
        "other",
    }

    #: Platforms supported by a method
    platforms = set()  # type: Set[str]

    #: The type of method, e.g. does it get the MAC of a interface?
    #: Allowed values: {ip, ip4, ip6, iface, default_iface}
    method_type = ""  # type: str

    #: If the method makes a network request as part of the check
    network_request = False  # type: bool

    #: Marks the method as unable to be used, e.g. if there was a runtime
    #: error indicating the method won't work on the current platform.
    unusable = False  # type: bool

    def test(self):  # type: () -> bool  # noqa: T484
        """Low-impact test that the method is feasible, e.g. command exists."""
        pass  # pragma: no cover

    # TODO: automatically clean MAC on return
    def get(self, arg):  # type: (str) -> Optional[str]
        """
        Core logic of the method that performs the lookup.

        .. warning::
           If the method itself fails to function an exception will be raised!
           (for instance, if some command arguments are invalid, or there's an
           internal error with the command, or a bug in the code).

        Args:
            arg (str): What the method should get, such as an IP address
                or interface name. In the case of default_iface methods,
                this is not used and defaults to an empty string.

        Returns:
            Lowercase colon-separated MAC address, or None if one could
            not be found.
        """
        pass  # pragma: no cover

    @classmethod
    def __str__(cls):  # type: () -> str
        return cls.__name__


# TODO(python3): do we want to keep this around? It calls 3 commands and is
#   quite inefficient. We should just take the methods and use directly.
class UuidArpGetNode(Method):
    platforms = {"linux", "darwin", "sunos", "other"}
    method_type = "ip"

    def test(self):  # type: () -> bool
        try:
            from uuid import _arp_getnode  # type: ignore

            return True
        except Exception:
            return False

    def get(self, arg):  # type: (str) -> Optional[str]
        from uuid import _arp_getnode  # type: ignore

        backup = socket.gethostbyname
        try:
            socket.gethostbyname = lambda x: arg  # noqa: F841
            mac1 = _arp_getnode()
            if mac1 is not None:
                mac1 = _uuid_convert(mac1)
                mac2 = _arp_getnode()
                mac2 = _uuid_convert(mac2)
                if mac1 == mac2:
                    return mac1
        except Exception:
            raise
        finally:
            socket.gethostbyname = backup

        return None


class ArpFile(Method):
    platforms = {"linux"}
    method_type = "ip4"
    _path = os.environ.get("ARP_PATH", "/proc/net/arp")  # type: str

    def test(self):  # type: () -> bool
        return check_path(self._path)

    def get(self, arg):  # type: (str) -> Optional[str]
        if not arg:
            return None

        data = _read_file(self._path)

        if data is None:
            self.unusable = True
            return None

        if data is not None and len(data) > 1:
            # Need a space, otherwise a search for 192.168.16.2
            # will match 192.168.16.254 if it comes first!
            return _search(re.escape(arg) + r" .+" + MAC_RE_COLON, data)

        return None


class ArpFreebsd(Method):
    platforms = {"freebsd"}
    method_type = "ip"

    def test(self):  # type: () -> bool
        return check_command("arp")

    def get(self, arg):  # type: (str) -> Optional[str]
        regex = r"\(" + re.escape(arg) + r"\)\s+at\s+" + MAC_RE_COLON
        return _search(regex, _popen("arp", arg))


class ArpOpenbsd(Method):
    platforms = {"openbsd"}
    method_type = "ip"
    _regex = r"[ ]+" + MAC_RE_COLON  # type: str

    def test(self):  # type: () -> bool
        return check_command("arp")

    def get(self, arg):  # type: (str) -> Optional[str]
        return _search(re.escape(arg) + self._regex, _popen("arp", "-an"))


class ArpVariousArgs(Method):
    platforms = {"linux", "darwin", "freebsd", "sunos", "other"}
    method_type = "ip"
    _regex_std = r"\)\s+at\s+" + MAC_RE_COLON  # type: str
    _regex_darwin = r"\)\s+at\s+" + MAC_RE_SHORT  # type: str
    _args = (
        ("", True),  # "arp 192.168.1.1"
        # Linux
        ("-an", False),  # "arp -an"
        ("-an", True),  # "arp -an 192.168.1.1"
        # Darwin, WSL, Linux distros???
        ("-a", False),  # "arp -a"
        ("-a", True),  # "arp -a 192.168.1.1"
    )
    _args_tested = False  # type: bool
    _good_pair = ()  # type: Union[Tuple, Tuple[str, bool]]
    _good_regex = ""  # type: str

    def test(self):  # type: () -> bool
        return check_command("arp")

    def get(self, arg):  # type: (str) -> Optional[str]
        if not arg:
            return None

        # Ensure output from testing command on first call isn't wasted
        command_output = ""

        # Test which arguments are valid to the command
        # This will NOT test which regex is valid
        if not self._args_tested:
            for pair_to_test in self._args:
                try:
                    cmd_args = [pair_to_test[0]]

                    # if True, then include IP as a command argument
                    if pair_to_test[1]:
                        cmd_args.append(arg)

                    command_output = _popen("arp", " ".join(cmd_args))
                    self._good_pair = pair_to_test
                    break
                except CalledProcessError as ex:
                    if DEBUG:
                        log.debug(
                            "ArpVariousArgs pair test failed for (%s, %s): %s",
                            pair_to_test[0],
                            pair_to_test[1],
                            str(ex),
                        )

            if not self._good_pair:
                self.unusable = True
                return None
            self._args_tested = True

        if not command_output:
            # if True, then include IP as a command argument
            cmd_args = [self._good_pair[0]]

            if self._good_pair[1]:
                cmd_args.append(arg)

            command_output = _popen("arp", " ".join(cmd_args))

        escaped = re.escape(arg)
        if self._good_regex:
            return _search(r"\(" + escaped + self._good_regex, command_output)

        # try linux regex first
        # try darwin regex next
        #   if a regex succeeds the first time, cache the successful regex
        #   otherwise, don't bother, since it's a miss anyway
        for regex in (self._regex_std, self._regex_darwin):
            # NOTE: Darwin regex will return MACs without leading zeroes,
            # e.g. "58:6d:8f:7:c9:94" instead of "58:6d:8f:07:c9:94"
            found = _search(r"\(" + escaped + regex, command_output)
            if found:
                self._good_regex = regex
                return found

        return None


class ArpExe(Method):
    """
    Query the Windows ARP table using ``arp.exe`` to find the MAC address of a remote host.
    This only works for IPv4, since the ARP table is IPv4-only.

    Microsoft Documentation: `arp <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/arp>`
    """  # noqa: E501

    platforms = {"windows", "wsl"}
    method_type = "ip4"

    def test(self):  # type: () -> bool
        # NOTE: specifying "arp.exe" instead of "arp" lets this work
        # seamlessly on WSL1 as well. On WSL2 it doesn't matter, since
        # it's basically just a Linux VM with some lipstick.
        return check_command("arp.exe")

    def get(self, arg):  # type: (str) -> Optional[str]
        return _search(MAC_RE_DASH, _popen("arp.exe", "-a %s" % arg))


class ArpingHost(Method):
    """
    Use ``arping`` command to determine the MAC of a host.

    Supports three variants of ``arping``

    - "habets" arping by Thomas Habets
        (`GitHub <https://github.com/ThomasHabets/arping>`__)
        On Debian-based distros, ``apt install arping`` will install
        Habets arping.
    - "iputils" arping, from the ``iputils-arping``
        `package <https://packages.debian.org/sid/iputils-arping>`__
    - "busybox" arping, included with BusyBox (a small executable "distro")
        (`further reading <https://boxmatrix.info/wiki/Property:arping>`__)

    BusyBox's arping quite similar to iputils-arping. The arguments for
    our purposes are the same, and the output is also the same.
    There's even a TODO in busybox's arping code referencing iputils arping.
    There are several differences:
    - The return code from bad arguments is 1, not 2 like for iputils-arping
    - The MAC address in output is lowercase (vs. uppercase in iputils-arping)

    This was a pain to obtain samples for busybox on Windows. I recommend
    using WSL and arping'ing the Docker gateway (for WSL2 distros).
    NOTE: it must be run as root using ``sudo busybox arping``.
    """

    platforms = {"linux", "darwin"}
    method_type = "ip4"
    network_request = True
    _is_iputils = True  # type: bool
    _habets_args = "-r -C 1 -c 1 %s"  # type: str
    _iputils_args = "-f -c 1 %s"  # type: str

    def test(self):  # type: () -> bool
        return check_command("arping")

    def get(self, arg):  # type: (str) -> Optional[str]
        # If busybox or iputils, this will just work, and if host ping fails,
        # then it'll exit with code 1 and this function will return None.
        #
        # If it's Habets, then it'll exit code 1 and have "invalid option"
        # and/or the help message in the output.
        # In the case of Habets, set self._is_iputils to False,
        # then re-try with Habets args.
        try:
            if self._is_iputils:
                command_output = _popen("arping", self._iputils_args % arg)
                if command_output:
                    return _search(
                        r" from %s \[(%s)\]" % (re.escape(arg), MAC_RE_COLON),
                        command_output,
                    )
            else:
                return self._call_habets(arg)
        except CalledProcessError as ex:
            if ex.output and self._is_iputils:
                if not PY2 and isinstance(ex.output, bytes):
                    output = str(ex.output, "utf-8").lower()
                else:
                    output = str(ex.output).lower()

                if "habets" in output or "invalid option" in output:
                    if DEBUG:
                        log.debug("Falling back to Habets arping")
                    self._is_iputils = False
                    try:
                        return self._call_habets(arg)
                    except CalledProcessError:
                        pass

        return None

    def _call_habets(self, arg):  # type: (str) -> Optional[str]
        command_output = _popen("arping", self._habets_args % arg)
        if command_output:
            return command_output.strip()
        else:
            return None


class CtypesHost(Method):
    """
    Uses ``SendARP`` from the Windows ``Iphlpapi`` to get the MAC address
    of a remote IPv4 host.

    Microsoft Documentation: `SendARP function (iphlpapi.h) <https://learn.microsoft.com/en-us/windows/win32/api/iphlpapi/nf-iphlpapi-sendarp>`__
    """  # noqa: E501

    platforms = {"windows"}
    method_type = "ip4"
    network_request = True

    def test(self):  # type: () -> bool
        try:
            return ctypes.windll.wsock32.inet_addr(b"127.0.0.1") > 0  # noqa: T484
        except Exception:
            return False

    def get(self, arg):  # type: (str) -> Optional[str]
        if not PY2:  # Convert to bytes on Python 3+ (Fixes GitHub issue #7)
            arg = arg.encode()  # type: ignore

        try:
            inetaddr = ctypes.windll.wsock32.inet_addr(arg)  # type: ignore
            if inetaddr in (0, -1):
                raise Exception
        except Exception:
            # TODO: this assumes failure is due to arg being a hostname
            #   We should be explicit about only accepting ipv4 addresses
            #   and handle any hostname resolution in calling code
            hostip = socket.gethostbyname(arg)
            inetaddr = ctypes.windll.wsock32.inet_addr(hostip)  # type: ignore

        buffer = ctypes.c_buffer(6)
        addlen = ctypes.c_ulong(ctypes.sizeof(buffer))

        # https://docs.microsoft.com/en-us/windows/win32/api/iphlpapi/nf-iphlpapi-sendarp
        send_arp = ctypes.windll.Iphlpapi.SendARP  # type: ignore
        if send_arp(inetaddr, 0, ctypes.byref(buffer), ctypes.byref(addlen)) != 0:
            return None

        # Convert binary data into a string.
        macaddr = ""
        for intval in struct.unpack("BBBBBB", buffer):  # type: ignore
            if intval > 15:
                replacestr = "0x"
            else:
                replacestr = "x"
            macaddr = "".join([macaddr, hex(intval).replace(replacestr, "")])

        return macaddr


class IpNeighborShow(Method):
    platforms = {"linux", "other"}
    method_type = "ip"  # IPv6 and IPv4

    def test(self):  # type: () -> bool
        return check_command("ip")

    def get(self, arg):  # type: (str) -> Optional[str]
        output = _popen("ip", "neighbor show %s" % arg)
        if not output:
            return None

        try:
            # NOTE: the space prevents accidental matching of partial IPs
            return (
                output.partition(arg + " ")[2].partition("lladdr")[2].strip().split()[0]
            )
        except IndexError as ex:
            log.debug("IpNeighborShow failed with exception: %s", str(ex))
            return None


class SysIfaceFile(Method):
    platforms = {"linux", "wsl"}
    method_type = "iface"
    _path = "/sys/class/net/"  # type: str

    def test(self):  # type: () -> bool
        # Imperfect, but should work well enough
        return check_path(self._path)

    def get(self, arg):  # type: (str) -> Optional[str]
        data = _read_file(self._path + arg + "/address")

        # NOTE: if "/sys/class/net/" exists, but interface file doesn't,
        # then that means the interface doesn't exist
        # Sometimes this can be empty or a single newline character
        return None if data is not None and len(data) < 17 else data


class UuidLanscan(Method):
    platforms = {"other"}
    method_type = "iface"

    def test(self):  # type: () -> bool
        try:
            from uuid import _find_mac  # noqa: T484

            return check_command("lanscan")
        except Exception:
            return False

    def get(self, arg):  # type: (str) -> Optional[str]
        from uuid import _find_mac  # type: ignore

        if not PY2:
            arg = bytes(arg, "utf-8")  # type: ignore

        mac = _find_mac("lanscan", "-ai", [arg], lambda i: 0)

        if mac:
            return _uuid_convert(mac)

        return None


class FcntlIface(Method):
    platforms = {"linux", "wsl"}
    method_type = "iface"

    def test(self):  # type: () -> bool
        try:
            import fcntl

            return True
        except Exception:  # Broad except to handle unknown effects
            return False

    def get(self, arg):  # type: (str) -> Optional[str]
        import fcntl

        if not PY2:
            arg = arg.encode()  # type: ignore

        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

        # 0x8927 = SIOCGIFADDR
        info = fcntl.ioctl(s.fileno(), 0x8927, struct.pack("256s", arg[:15]))

        if PY2:
            return ":".join(["%02x" % ord(char) for char in info[18:24]])
        else:
            return ":".join(["%02x" % ord(chr(char)) for char in info[18:24]])


class GetmacExe(Method):
    """
    Uses Windows-builtin ``getmac.exe`` to get a interface's MAC address.

    Microsoft Documentation: `getmac <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/getmac>`__
    """  # noqa: E501

    platforms = {"windows"}
    method_type = "iface"
    _regexes = [
        # Connection Name
        (r"\r\n", r".*" + MAC_RE_DASH + r".*\r\n"),
        # Network Adapter (the human-readable name)
        (r"\r\n.*", r".*" + MAC_RE_DASH + r".*\r\n"),
    ]  # type: List[Tuple[str, str]]
    _champ = ()  # type: Union[tuple, Tuple[str, str]]

    def test(self):  # type: () -> bool
        # NOTE: the scripts from this library (getmac) are excluded from the
        # path used for checking variables, in getmac.getmac.PATH (defined
        # at the top of this file). Otherwise, this would get messy quickly :)
        return check_command("getmac.exe")

    def get(self, arg):  # type: (str) -> Optional[str]
        try:
            # /nh: Suppresses table headers
            # /v:  Verbose
            command_output = _popen("getmac.exe", "/NH /V")
        except CalledProcessError as ex:
            # This shouldn't cause an exception if it's valid command
            log.error("getmac.exe failed, marking unusable. Exception: %s", str(ex))
            self.unusable = True
            return None

        if self._champ:
            return _search(self._champ[0] + arg + self._champ[1], command_output)

        for pair in self._regexes:
            result = _search(pair[0] + arg + pair[1], command_output)
            if result:
                self._champ = pair
                return result

        return None


class IpconfigExe(Method):
    """
    Uses ``ipconfig.exe`` to find interface MAC addresses on Windows.

    This is generally pretty reliable and works across a wide array of
    versions and releases. I'm not sure if it works pre-XP though.

    Microsoft Documentation: `ipconfig <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/ipconfig>`__
    """  # noqa: E501

    platforms = {"windows"}
    method_type = "iface"
    _regex = (
        r"(?:\n?[^\n]*){1,8}Physical Address[ .:]+" + MAC_RE_DASH + r"\r\n"
    )  # type: str

    def test(self):  # type: () -> bool
        return check_command("ipconfig.exe")

    def get(self, arg):  # type: (str) -> Optional[str]
        return _search(arg + self._regex, _popen("ipconfig.exe", "/all"))


class WmicExe(Method):
    """
    Use ``wmic.exe`` on Windows to find the MAC address of a network interface.

    Microsoft Documentation: `wmic <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/wmic>`__

    .. warning::
       WMIC is deprecated as of Windows 10 21H1. This method may not work on
       Windows 11 and may stop working at some point on Windows 10 (unlikely,
       but possible).
    """  # noqa: E501

    platforms = {"windows"}
    method_type = "iface"

    def test(self):  # type: () -> bool
        return check_command("wmic.exe")

    def get(self, arg):  # type: (str) -> Optional[str]
        command_output = _popen(
            "wmic.exe",
            'nic where "NetConnectionID = \'%s\'" get "MACAddress" /value' % arg,
        )

        # Negative: "No Instance(s) Available"
        # Positive: "MACAddress=00:FF:E7:78:95:A0"
        # NOTE: .partition() always returns 3 parts,
        # therefore it won't cause an IndexError
        return command_output.strip().partition("=")[2]


class DarwinNetworksetupIface(Method):
    """
    Use ``networksetup`` on MacOS (Darwin) to get the MAC address of a specific interface.

    I think that this is or was a BSD utility, but I haven't seen it on other BSDs
    (FreeBSD, OpenBSD, etc.). So, I'm treating it as a Darwin-specific utility
    until further notice. If you know otherwise, please open a PR :)

    If the command is present, it should always work, though naturally that is contingent
    upon the whims of Apple in newer MacOS releases.

    Man page: `networksetup (8) <https://www.manpagez.com/man/8/networksetup/>`__
    """

    platforms = {"darwin"}
    method_type = "iface"

    def test(self):  # type: () -> bool
        return check_command("networksetup")

    def get(self, arg):  # type: (str) -> Optional[str]
        command_output = _popen("networksetup", "-getmacaddress %s" % arg)
        return _search(MAC_RE_COLON, command_output)


# This only took 15-20 hours of throwing my brain against a wall multiple times
# over the span of 1-2 years to figure out. It works for almost all conceivable
# output from "ifconfig", and probably netstat too. It can probably be made more
# efficient by someone who actually knows how to write regex.
# [: ]\s?(?:flags=|\s).*?(?:(?:\w+[: ]\s?flags=)|\s(?:ether|address|HWaddr|hwaddr|lladdr)[ :]?\s?([0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}))  # noqa: E501
IFCONFIG_REGEX = (
    r"[: ]\s?(?:flags=|\s).*?(?:"
    r"(?:\w+[: ]\s?flags=)|"  # Prevent interfaces w/o a MAC from matching
    r"\s(?:ether|address|HWaddr|hwaddr|lladdr)[ :]?\s?"  # Handle various prefixes
    r"([0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}))"  # Match the MAC
)


def _parse_ifconfig(iface, command_output):
    # type: (str, str) -> Optional[str]
    if not iface or not command_output:
        return None

    # Sanity check on input e.g. if user does "eth0:" as argument
    iface = iface.strip(":")

    # "(?:^|\s)": prevent an input of "h0" from matching on "eth0"
    search_re = r"(?:^|\s)" + iface + IFCONFIG_REGEX

    return _search(search_re, command_output, flags=re.DOTALL)


class IfconfigWithIfaceArg(Method):
    """
    ``ifconfig`` command with the interface name as an argument
    (e.g. ``ifconfig eth0``).
    """

    platforms = {"linux", "wsl", "freebsd", "openbsd", "other"}
    method_type = "iface"

    def test(self):  # type: () -> bool
        return check_command("ifconfig")

    def get(self, arg):  # type: (str) -> Optional[str]
        try:
            command_output = _popen("ifconfig", arg)
        except CalledProcessError as err:
            # Return code of 1 means interface doesn't exist
            if err.returncode == 1:
                return None
            else:
                raise err  # this will cause another method to be used

        return _parse_ifconfig(arg, command_output)


# TODO: combine this with IfconfigWithArg/IfconfigNoArg
#       (need to do live testing on Darwin)
class IfconfigEther(Method):
    platforms = {"darwin"}
    method_type = "iface"
    _tested_arg = False  # type: bool
    _iface_arg = False  # type: bool

    def test(self):  # type: () -> bool
        return check_command("ifconfig")

    def get(self, arg):  # type: (str) -> Optional[str]
        # Check if this version of "ifconfig" accepts an interface argument
        command_output = ""

        if not self._tested_arg:
            try:
                command_output = _popen("ifconfig", arg)
                self._iface_arg = True
            except CalledProcessError:
                self._iface_arg = False
            self._tested_arg = True

        if self._iface_arg and not command_output:  # Don't repeat work on first run
            command_output = _popen("ifconfig", arg)
        else:
            command_output = _popen("ifconfig", "")

        return _parse_ifconfig(arg, command_output)


# TODO: create new methods, IfconfigNoArgs and IfconfigVariousArgs
# TODO: unit tests
class IfconfigOther(Method):
    """
    Wild 'Shot in the Dark' attempt at ``ifconfig`` for unknown platforms.
    """

    platforms = {"linux", "other"}
    method_type = "iface"
    # "-av": Tru64 system?
    _args = (
        ("", (r"(?::| ).*?\sether\s", r"(?::| ).*?\sHWaddr\s")),
        ("-a", r".*?HWaddr\s"),
        ("-v", r".*?HWaddr\s"),
        ("-av", r".*?Ether\s"),
    )
    _args_tested = False  # type: bool
    _good_pair = []  # type: List[Union[str, Tuple[str, str]]]

    def test(self):  # type: () -> bool
        return check_command("ifconfig")

    def get(self, arg):  # type: (str) -> Optional[str]
        if not arg:
            return None

        # Cache output from testing command so first call isn't wasted
        command_output = ""

        # Test which arguments are valid to the command
        if not self._args_tested:
            for pair_to_test in self._args:
                try:
                    command_output = _popen("ifconfig", pair_to_test[0])
                    self._good_pair = list(pair_to_test)  # noqa: T484
                    if isinstance(self._good_pair[1], str):
                        self._good_pair[1] += MAC_RE_COLON
                    break
                except CalledProcessError as ex:
                    if DEBUG:
                        log.debug(
                            "IfconfigOther pair test failed for (%s, %s): %s",
                            pair_to_test[0],
                            pair_to_test[1],
                            str(ex),
                        )

            if not self._good_pair:
                self.unusable = True
                return None

            self._args_tested = True

        if not command_output and isinstance(self._good_pair[0], str):
            command_output = _popen("ifconfig", self._good_pair[0])

        # Handle the two possible search terms
        if isinstance(self._good_pair[1], tuple):
            for term in self._good_pair[1]:
                regex = term + MAC_RE_COLON
                result = _search(re.escape(arg) + regex, command_output)

                if result:
                    # changes type from tuple to str, so the else statement
                    # will be hit on the next call to this method
                    self._good_pair[1] = regex
                    return result
            return None
        else:
            return _search(re.escape(arg) + self._good_pair[1], command_output)


class NetstatIface(Method):
    platforms = {"linux", "wsl", "other"}
    method_type = "iface"

    # ".*?": non-greedy
    # https://docs.python.org/3/howto/regex.html#greedy-versus-non-greedy
    _regexes = [
        r": .*?ether " + MAC_RE_COLON,
        r": .*?HWaddr " + MAC_RE_COLON,
        # Ubuntu 12.04 and other older kernels
        r" .*?Link encap:Ethernet  HWaddr " + MAC_RE_COLON,
    ]  # type: List[str]
    _working_regex = ""  # type: str

    def test(self):  # type: () -> bool
        return check_command("netstat")

    # TODO: consolidate the parsing logic between IfconfigOther and netstat
    def get(self, arg):  # type: (str) -> Optional[str]
        # NOTE: netstat and ifconfig pull from the same kernel source and
        # therefore have the same output format on the same platform.
        command_output = _popen("netstat", "-iae")
        if not command_output:
            log.warning("no netstat output, marking unusable")
            self.unusable = True
            return None

        if self._working_regex:
            # Use regex that worked previously. This can still return None in
            # the case of interface not existing, but at least it's a bit faster.
            return _search(arg + self._working_regex, command_output, flags=re.DOTALL)

        # See if either regex matches
        for regex in self._regexes:
            result = _search(arg + regex, command_output, flags=re.DOTALL)
            if result:
                self._working_regex = regex
                return result

        return None


# TODO: Add to IpLinkIface
# TODO: New method for "ip addr"? (this would be useful for CentOS and others as a fallback)
# (r"state UP.*\n.*ether " + MAC_RE_COLON, 0, "ip", ["link","addr"]),
# (r"wlan.*\n.*ether " + MAC_RE_COLON, 0, "ip", ["link","addr"]),
# (r"ether " + MAC_RE_COLON, 0, "ip", ["link","addr"]),
# _regexes = (
#     r".*\n.*link/ether " + MAC_RE_COLON,
#     # Android 6.0.1+ (and likely other platforms as well)
#     r"state UP.*\n.*ether " + MAC_RE_COLON,
#     r"wlan.*\n.*ether " + MAC_RE_COLON,
#     r"ether " + MAC_RE_COLON,
# )  # type: Tuple[str, str, str, str]


class IpLinkIface(Method):
    platforms = {"linux", "wsl", "android", "other"}
    method_type = "iface"
    _regex = r".*\n.*link/ether " + MAC_RE_COLON  # type: str
    _tested_arg = False  # type: bool
    _iface_arg = False  # type: bool

    def test(self):  # type: () -> bool
        return check_command("ip")

    def get(self, arg):  # type: (str) -> Optional[str]
        # Check if this version of "ip link" accepts an interface argument
        # Not accepting one is a quirk of older versions of 'iproute2'
        # TODO: is it "ip link <arg>" on some platforms and "ip link show <arg>" on others?
        command_output = ""

        if not self._tested_arg:
            try:
                command_output = _popen("ip", "link show " + arg)
                self._iface_arg = True
            except CalledProcessError as err:
                # Output: 'Command "eth0" is unknown, try "ip link help"'
                if err.returncode != 255:
                    raise err
            self._tested_arg = True

        if self._iface_arg:
            if not command_output:  # Don't repeat work on first run
                command_output = _popen("ip", "link show " + arg)
            return _search(arg + self._regex, command_output)
        else:
            # TODO: improve this regex to not need extra portion for no arg
            command_output = _popen("ip", "link")
            return _search(arg + r":" + self._regex, command_output)


class DefaultIfaceLinuxRouteFile(Method):
    """
    Get the default interface by parsing the ``/proc/net/route`` file.

    This is the same source as the ``route`` command, however it's much
    faster to read this file than to call ``route``. If it fails for whatever
    reason, we can fall back on the system commands (e.g for a platform that
    has a route command, but doesn't use ``/proc``, such as BSD-based platforms).
    """

    platforms = {"linux", "wsl"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_path("/proc/net/route")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        data = _read_file("/proc/net/route")

        if data is not None and len(data) > 1:
            for line in data.split("\n")[1:-1]:
                line = line.strip()
                if not line:
                    continue

                # Some have tab separators, some have spaces
                if "\t" in line:
                    sep = "\t"
                else:
                    sep = "    "

                iface_name, dest = line.split(sep)[:2]

                if dest == "00000000":
                    return iface_name

            if DEBUG:
                log.debug(
                    "Failed to find default interface in data from "
                    "'/proc/net/route', no destination of '00000000' was found"
                )
        elif DEBUG:
            log.warning("No data from /proc/net/route")

        return None


class DefaultIfaceRouteCommand(Method):
    platforms = {"linux", "wsl", "other"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_command("route")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        output = _popen("route", "-n")

        try:
            return output.partition("0.0.0.0")[2].partition("\n")[0].split()[-1]
        except IndexError as ex:  # index errors means no default route in output?
            log.debug("DefaultIfaceRouteCommand failed for %s: %s", arg, str(ex))
            return None


class DefaultIfaceRouteGetCommand(Method):
    platforms = {"darwin", "freebsd", "other"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_command("route")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        output = _popen("route", "get default")

        if not output:
            return None

        try:
            return output.partition("interface: ")[2].strip().split()[0].strip()
        except IndexError as ex:
            log.debug("DefaultIfaceRouteCommand failed for %s: %s", arg, str(ex))
            return None


class DefaultIfaceIpRoute(Method):
    # NOTE: this is slightly faster than "route" since
    # there is less output than "route -n"
    platforms = {"linux", "wsl", "other"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_command("ip")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        output = _popen("ip", "route list 0/0")

        if not output:
            if DEBUG:
                log.debug("DefaultIfaceIpRoute failed: no output")
            return None

        return output.partition("dev")[2].partition("proto")[0].strip()


class DefaultIfaceOpenBsd(Method):
    platforms = {"openbsd"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_command("route")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        output = _popen("route", "-nq show -inet -gateway -priority 1")
        return output.partition("127.0.0.1")[0].strip().rpartition(" ")[2]


class DefaultIfaceFreeBsd(Method):
    platforms = {"freebsd"}
    method_type = "default_iface"

    def test(self):  # type: () -> bool
        return check_command("netstat")

    def get(self, arg=""):  # type: (str) -> Optional[str]
        output = _popen("netstat", "-r")
        return _search(r"default[ ]+\S+[ ]+\S+[ ]+(\S+)[\r\n]+", output)


# TODO: order methods by effectiveness/reliability
#   Use a class attribute maybe? e.g. "score", then sort by score in cache
METHODS = [
    # NOTE: CtypesHost is faster than ArpExe because of sub-process startup times :)
    CtypesHost,
    ArpFile,
    ArpingHost,
    SysIfaceFile,
    FcntlIface,
    UuidLanscan,
    GetmacExe,
    IpconfigExe,
    WmicExe,
    ArpExe,
    DarwinNetworksetupIface,
    ArpFreebsd,
    ArpOpenbsd,
    IfconfigWithIfaceArg,
    IfconfigEther,
    IfconfigOther,
    IpLinkIface,
    NetstatIface,
    IpNeighborShow,
    ArpVariousArgs,
    UuidArpGetNode,
    DefaultIfaceLinuxRouteFile,
    DefaultIfaceIpRoute,
    DefaultIfaceRouteCommand,
    DefaultIfaceRouteGetCommand,
    DefaultIfaceOpenBsd,
    DefaultIfaceFreeBsd,
]  # type: List[Type[Method]]

# Primary method to use for a given method type
METHOD_CACHE = {
    "ip4": None,
    "ip6": None,
    "iface": None,
    "default_iface": None,
}  # type: Dict[str, Optional[Method]]


# Order of methods is determined by:
#   Platform + version
#   Performance (file read > command)
#   Reliability (how well I know/understand the command to work)
FALLBACK_CACHE = {
    "ip4": [],
    "ip6": [],
    "iface": [],
    "default_iface": [],
}  # type: Dict[str, List[Method]]


DEFAULT_IFACE = ""  # type: str


def get_method_by_name(method_name):
    # type: (str) -> Optional[Type[Method]]
    for method in METHODS:
        if method.__name__.lower() == method_name.lower():
            return method

    return None


def get_instance_from_cache(method_type, method_name):
    # type: (str, str) -> Optional[Method]
    """
    Get the class for a named Method from the caches.

    METHOD_CACHE is checked first, and if that fails,
    then any entries in FALLBACK_CACHE are checked.
    If both fail, None is returned.

    Args:
        method_type: method type to initialize the cache for.
            Allowed values are:  ``ip4`` | ``ip6`` | ``iface`` | ``default_iface``
    """

    if str(METHOD_CACHE[method_type]) == method_name:
        return METHOD_CACHE[method_type]

    for f_meth in FALLBACK_CACHE[method_type]:
        if str(f_meth) == method_name:
            return f_meth

    return None


def _swap_method_fallback(method_type, swap_with):
    # type: (str, str) -> bool
    if str(METHOD_CACHE[method_type]) == swap_with:
        return True

    found = None  # type: Optional[Method]
    for f_meth in FALLBACK_CACHE[method_type]:
        if str(f_meth) == swap_with:
            found = f_meth
            break

    if not found:
        return False

    curr = METHOD_CACHE[method_type]
    FALLBACK_CACHE[method_type].remove(found)
    METHOD_CACHE[method_type] = found
    FALLBACK_CACHE[method_type].insert(0, curr)  # noqa: T484

    return True


def _warn_critical(err_msg):
    # type: (str) -> None
    log.critical(err_msg)
    warnings.warn(
        "%s. NOTICE: this warning will likely turn into a raised exception in getmac 1.0.0!"
        % err_msg,
        RuntimeWarning,
    )


def initialize_method_cache(
    method_type, network_request=True
):  # type: (str, bool) -> bool
    """
    Initialize the method cache for the given method type.

    Args:
        method_type: method type to initialize the cache for.
            Allowed values are:  ``ip4`` | ``ip6`` | ``iface`` | ``default_iface``
        network_request: if methods that make network requests should be included
            (those methods that have the attribute ``network_request`` set to ``True``)
    """
    if METHOD_CACHE.get(method_type):
        if DEBUG:
            log.debug(
                "Method cache already initialized for method type '%s'", method_type
            )
        return True

    log.debug("Initializing '%s' method cache (platform: '%s')", method_type, PLATFORM)

    if OVERRIDE_PLATFORM:
        log.warning(
            "Platform override is set, using '%s' as platform "
            "instead of detected platform '%s'",
            OVERRIDE_PLATFORM,
            PLATFORM,
        )
        platform = OVERRIDE_PLATFORM
    else:
        platform = PLATFORM

    if DEBUG >= 4:
        meth_strs = ", ".join(m.__name__ for m in METHODS)  # type: str
        log.debug("%d methods available: %s", len(METHODS), meth_strs)

    # Filter methods by the type of MAC we're looking for, such as "ip"
    # for remote host methods or "iface" for local interface methods.
    type_methods = [
        method
        for method in METHODS
        if (method.method_type != "ip" and method.method_type == method_type)
        # Methods with a type of "ip" can handle both IPv4 and IPv6
        or (method.method_type == "ip" and method_type in ["ip4", "ip6"])
    ]  # type: List[Type[Method]]

    if not type_methods:
        _warn_critical("No valid methods matching MAC type '%s'" % method_type)
        return False

    if DEBUG >= 2:
        type_strs = ", ".join(tm.__name__ for tm in type_methods)  # type: str
        log.debug(
            "%d type-filtered methods for '%s': %s",
            len(type_methods),
            method_type,
            type_strs,
        )

    # Filter methods by the platform we're running on
    platform_methods = [
        method for method in type_methods if platform in method.platforms
    ]  # type: List[Type[Method]]

    if not platform_methods:
        # If there isn't a method for the current platform,
        # then fallback to the generic platform "other".
        warn_msg = (
            "No methods for platform '%s'! Your system may not be supported. "
            "Falling back to platform 'other'." % platform
        )
        log.warning(warn_msg)
        warnings.warn(warn_msg, RuntimeWarning)
        platform_methods = [
            method for method in type_methods if "other" in method.platforms
        ]

    if DEBUG >= 2:
        plat_strs = ", ".join(pm.__name__ for pm in platform_methods)  # type: str
        log.debug(
            "%d platform-filtered methods for '%s' (method_type='%s'): %s",
            len(platform_methods),
            platform,
            method_type,
            plat_strs,
        )

    if not platform_methods:
        _warn_critical(
            "No valid methods found for MAC type '%s' and platform '%s'"
            % (method_type, platform)
        )
        return False

    filtered_methods = platform_methods  # type: List[Type[Method]]

    # If network_request is False, then remove any methods that have network_request=True
    if not network_request:
        filtered_methods = [m for m in platform_methods if not m.network_request]

    # Determine which methods work on the current system
    tested_methods = []  # type: List[Method]

    for method_class in filtered_methods:
        method_instance = method_class()  # type: Method
        try:
            test_result = method_instance.test()  # type: bool
        except Exception:
            test_result = False
        if test_result:
            tested_methods.append(method_instance)
            # First successful test goes in the cache
            if not METHOD_CACHE[method_type]:
                METHOD_CACHE[method_type] = method_instance
        elif DEBUG:
            log.debug("Test failed for method '%s'", str(method_instance))

    if not tested_methods:
        _warn_critical(
            "All %d '%s' methods failed to test!" % (len(filtered_methods), method_type)
        )
        return False

    if DEBUG >= 2:
        tested_strs = ", ".join(str(ts) for ts in tested_methods)  # type: str
        log.debug(
            "%d tested methods for '%s': %s",
            len(tested_methods),
            method_type,
            tested_strs,
        )

    # Populate fallback cache with all the tested methods, minus the currently active method
    if METHOD_CACHE[method_type] and METHOD_CACHE[method_type] in tested_methods:
        tested_methods.remove(METHOD_CACHE[method_type])  # noqa: T484

    FALLBACK_CACHE[method_type] = tested_methods

    if DEBUG:
        log.debug(
            "Current method cache: %s",
            str({k: str(v) for k, v in METHOD_CACHE.items()}),
        )
        log.debug(
            "Current fallback cache: %s",
            str({k: str(v) for k, v in FALLBACK_CACHE.items()}),
        )
    log.debug("Finished initializing '%s' method cache", method_type)

    return True


def _remove_unusable(method, method_type):  # type: (Method, str) -> Optional[Method]
    if not FALLBACK_CACHE[method_type]:
        log.warning("No fallback method for unusable method '%s'!", str(method))
        METHOD_CACHE[method_type] = None
    else:
        METHOD_CACHE[method_type] = FALLBACK_CACHE[method_type].pop(0)
        log.warning(
            "Falling back to '%s' for unusable method '%s'",
            str(METHOD_CACHE[method_type]),
            str(method),
        )

    return METHOD_CACHE[method_type]


def _attempt_method_get(
    method, method_type, arg
):  # type: (Method, str, str) -> Optional[str]
    """
    Attempt to use methods, and if they fail, fallback to the next method in the cache.
    """
    if not METHOD_CACHE[method_type] and not FALLBACK_CACHE[method_type]:
        _warn_critical("No usable methods found for MAC type '%s'" % method_type)
        return None

    if DEBUG:
        log.debug(
            "Attempting get() (method='%s', method_type='%s', arg='%s')",
            str(method),
            method_type,
            arg,
        )

    result = None
    try:
        result = method.get(arg)
    except CalledProcessError as ex:
        # Don't mark return code 1 on a process as unusable!
        #   Example of return code 1 on ifconfig from WSL:
        #     Blake:goesc$ ifconfig eth8
        #     eth8: error fetching interface information: Device not found
        #     Blake:goesc$ echo $?
        #     1
        # Methods where an exit code of 1 makes it invalid should handle the
        # CalledProcessError, inspect the return code, and set self.unusable = True
        if ex.returncode != 1:
            log.warning(
                "Cached Method '%s' failed for '%s' lookup with process exit "
                "code '%d' != 1, marking unusable. Exception: %s",
                str(method),
                method_type,
                ex.returncode,
                str(ex),
            )
            method.unusable = True
    except Exception as ex:
        log.warning(
            "Cached Method '%s' failed for '%s' lookup with unhandled exception: %s",
            str(method),
            method_type,
            str(ex),
        )
        method.unusable = True

    # When an unhandled exception occurs (or exit code other than 1), remove
    # the method from the cache and reinitialize with next candidate.
    if not result and method.unusable:
        new_method = _remove_unusable(method, method_type)

        if not new_method:
            return None

        return _attempt_method_get(new_method, method_type, arg)

    return result


def get_by_method(method_type, arg="", network_request=True):
    # type: (str, str, bool) -> Optional[str]
    """
    Query for a MAC using a specific method.

    Args:
        method_type: the type of lookup being performed.
            Allowed values are: ``ip4``, ``ip6``, ``iface``, ``default_iface``
        arg: Argument to pass to the method, e.g. an interface name or IP address
        network_request: if methods that make network requests should be included
            (those methods that have the attribute ``network_request`` set to ``True``)
    """
    if not arg and method_type != "default_iface":
        log.error("Empty arg for method '%s' (raw value: %s)", method_type, repr(arg))
        return None

    if FORCE_METHOD:
        log.warning(
            "Forcing method '%s' to be used for '%s' lookup (arg: '%s')",
            FORCE_METHOD,
            method_type,
            arg,
        )

        forced_method = get_method_by_name(FORCE_METHOD)

        if not forced_method:
            log.error("Invalid FORCE_METHOD method name '%s'", FORCE_METHOD)
            return None

        return forced_method().get(arg)

    method = METHOD_CACHE.get(method_type)  # type: Optional[Method]

    if not method:
        # Initialize the cache if it hasn't been already
        if not initialize_method_cache(method_type, network_request):
            log.error(
                "Failed to initialize method cache for method '%s' (arg: '%s')",
                method_type,
                arg,
            )
            return None

        method = METHOD_CACHE[method_type]

    if not method:
        log.error(
            "Initialization failed for method '%s'. It may not be supported "
            "on this platform or another issue occurred.",
            method_type,
        )
        return None

    # TODO: add a "net_ok" argument, check network_request attribute
    #   on method in CACHE, if not then keep checking for method in
    #   FALLBACK_CACHE that has network_request.
    result = _attempt_method_get(method, method_type, arg)

    # Log normal get() failures if debugging is enabled
    if DEBUG and not result:
        log.debug("Method '%s' failed for '%s' lookup", str(method), method_type)

    return result


def get_mac_address(  # noqa: C901
    interface=None, ip=None, ip6=None, hostname=None, network_request=True
):
    # type: (Optional[str], Optional[str], Optional[str], Optional[str], bool) -> Optional[str]
    """
    Get an Unicast IEEE 802 MAC-48 address from a local interface or remote host.

    Only ONE of the first four arguments may be used
    (``interface``,``ip``, ``ip6``, or ``hostname``).
    If none of the arguments are selected, the default network interface for
    the system will be used.

    .. warning::
       In getmac 1.0.0, exceptions will be raised if the method cache initialization fails
       (in other words, if there are no valid methods found for the type of MAC requested).

    .. warning::
       You MUST provide :class:`str` typed arguments, REGARDLESS of Python version

    .. note::
       ``"localhost"`` or ``"127.0.0.1"`` will always return ``"00:00:00:00:00:00"``

    .. note::
       It is assumed that you are using Ethernet or Wi-Fi. While other protocols
       such as Bluetooth may work, this has not been tested and should not be
       relied upon. If you need this functionality, please open an issue
       (or better yet, a Pull Request ;))!

    .. note::
       Exceptions raised by methods are handled silently and returned as :obj:`None`.

    Args:
        interface (str): Name of a local network interface (e.g "Ethernet 3", "eth0", "ens32")
        ip (str): Canonical dotted decimal IPv4 address of a remote host (e.g ``192.168.0.1``)
        ip6 (str): Canonical shortened IPv6 address of a remote host (e.g ``ff02::1:ffe7:7f19``)
        hostname (str): DNS hostname of a remote host (e.g "router1.mycorp.com", "localhost")
        network_request (bool): If network requests should be made when attempting to find the
            MAC of a remote host. If the ``arping`` command is available, this will be used.
            If not, a UDP packet will be sent to the remote host to populate
            the ARP/NDP tables for IPv4/IPv6. The port this packet is sent to can
            be configured using the module variable ``getmac.PORT``.

    Returns:
        Lowercase colon-separated MAC address, or :obj:`None` if one could not be
        found or there was an error.
    """  # noqa: E501

    if DEBUG:
        import timeit

        start_time = timeit.default_timer()

    if PY2 or (sys.version_info[0] == 3 and sys.version_info[1] < 7):
        global WARNED_UNSUPPORTED_PYTHONS
        if not WARNED_UNSUPPORTED_PYTHONS:
            warning_string = (
                "Support for Python versions < 3.7 is deprecated and will be "
                "removed in getmac 1.0.0. If you are stuck on an unsupported "
                "Python, considor loosely pinning the version of this package "
                'in your dependency list, e.g. "getmac<1.0.0" or "getmac~=0.9.0".'
            )
            warnings.warn(warning_string, DeprecationWarning)
            log.warning(warning_string)  # Ensure it appears in any logs
            WARNED_UNSUPPORTED_PYTHONS = True

    if (hostname and hostname == "localhost") or (ip and ip == "127.0.0.1"):
        return "00:00:00:00:00:00"

    # Resolve hostname to an IP address
    if hostname:
        # Exceptions will be handled silently and returned as a None
        try:
            # TODO: can this return a IPv6 address? If so, handle that!
            ip = socket.gethostbyname(hostname)
        except Exception as ex:
            log.error("Could not resolve hostname '%s': %s", hostname, ex)
            if DEBUG:
                log.debug(traceback.format_exc())
            return None

    if ip6:
        if not socket.has_ipv6:
            log.error(
                "Cannot get the MAC address of a IPv6 host: "
                "IPv6 is not supported on this system"
            )
            return None
        elif ":" not in ip6:
            log.error("Invalid IPv6 address (no ':'): %s", ip6)
            return None

    mac = None

    if network_request and (ip or ip6):
        send_udp_packet = True  # type: bool

        # If IPv4, use ArpingHost or CtypesHost if they're available instead
        # of populating the ARP table. This provides more reliable results
        # and a ARP packet is lower impact than a UDP packet.
        if ip:
            if not METHOD_CACHE["ip4"]:
                initialize_method_cache("ip4", network_request)

            # If ArpFile succeeds, just use that, since it's
            # significantly faster than arping (file read vs.
            # spawning a process).
            if not FORCE_METHOD or FORCE_METHOD.lower() == "arpfile":
                af_meth = get_instance_from_cache("ip4", "ArpFile")
                if af_meth:
                    mac = _attempt_method_get(af_meth, "ip4", ip)

            # TODO: add tests for this logic (arpfile => fallback)
            # This seems to be a common course of GitHub issues,
            # so fixing it for good and adding robust tests is
            # probably a good idea.

            if not mac:
                for arp_meth in ["CtypesHost", "ArpingHost"]:
                    if FORCE_METHOD and FORCE_METHOD.lower() != arp_meth:
                        continue

                    if arp_meth == str(METHOD_CACHE["ip4"]):
                        send_udp_packet = False
                        break
                    elif any(
                        arp_meth == str(x) for x in FALLBACK_CACHE["ip4"]
                    ) and _swap_method_fallback("ip4", arp_meth):
                        send_udp_packet = False
                        break

        # Populate the ARP table by sending an empty UDP packet to a high port
        if send_udp_packet and not mac:
            if DEBUG:
                log.debug(
                    "Attempting to populate ARP table with UDP packet to %s:%d",
                    ip if ip else ip6,
                    PORT,
                )

            if ip:
                sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
            else:
                sock = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)

            try:
                if ip:
                    sock.sendto(b"", (ip, PORT))
                else:
                    sock.sendto(b"", (ip6, PORT))
            except Exception:
                log.error("Failed to send ARP table population packet")
                if DEBUG:
                    log.debug(traceback.format_exc())
            finally:
                sock.close()
        elif DEBUG:
            log.debug(
                "Not sending UDP packet, using network request method '%s' instead",
                str(METHOD_CACHE["ip4"]),
            )

    # Setup the address hunt based on the arguments specified
    if not mac:
        if ip6:
            mac = get_by_method("ip6", ip6)
        elif ip:
            mac = get_by_method("ip4", ip)
        elif interface:
            mac = get_by_method("iface", interface)
        else:  # Default to searching for interface
            # Default to finding MAC of the interface with the default route
            if WINDOWS and network_request:
                default_iface_ip = _fetch_ip_using_dns()
                mac = get_by_method("ip4", default_iface_ip)
            elif WINDOWS:
                # TODO: implement proper default interface detection on windows
                #   (add a Method subclass to implement DefaultIface on Windows)
                mac = get_by_method("iface", "Ethernet")
            else:
                global DEFAULT_IFACE

                if not DEFAULT_IFACE:
                    DEFAULT_IFACE = get_by_method("default_iface")  # noqa: T484

                    if DEFAULT_IFACE:
                        DEFAULT_IFACE = str(DEFAULT_IFACE).strip()

                    # TODO: better fallback if default iface lookup fails
                    if not DEFAULT_IFACE and BSD:
                        DEFAULT_IFACE = "em0"
                    elif not DEFAULT_IFACE and DARWIN:  # OSX, maybe?
                        DEFAULT_IFACE = "en0"
                    elif not DEFAULT_IFACE:
                        DEFAULT_IFACE = "eth0"

                mac = get_by_method("iface", DEFAULT_IFACE)

                # TODO: hack to fallback to loopback if lookup fails
                if not mac:
                    mac = get_by_method("iface", "lo")

    log.debug("Raw MAC found: %s", mac)

    # Log how long it took
    if DEBUG:
        duration = timeit.default_timer() - start_time
        log.debug("getmac took %.4f seconds", duration)

    return _clean_mac(mac)