Skip to content

Mac Address

netutils.mac

Functions for working with MAC addresses.

get_oui(mac)

Returns the company name for a given mac as defined by the IEEE.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required

Returns:

Type Description
str

The name of the company the mac is related to.

Examples:

>>> from netutils.mac import get_oui
>>> from netutils.data_files.oui_mappings import OUI_MAPPINGS
>>> get_oui("cc.79.d7.dd.ee.ff")
'Cisco Systems, Inc'
>>>
Source code in netutils/mac.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
@_valid_mac
def get_oui(mac: str) -> str:
    """Returns the company name for a given mac as defined by the IEEE.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.

    Returns:
        The name of the company the mac is related to.

    Examples:
        >>> from netutils.mac import get_oui
        >>> from netutils.data_files.oui_mappings import OUI_MAPPINGS
        >>> get_oui("cc.79.d7.dd.ee.ff")
        'Cisco Systems, Inc'
        >>>
    """
    from netutils.data_files.oui_mappings import OUI_MAPPINGS  # pylint: disable=import-outside-toplevel

    normalized_mac_prefix = mac_normalize(mac)[0:6]
    oui_company = OUI_MAPPINGS.get(normalized_mac_prefix)

    if not oui_company:
        raise ValueError(f"There was no matching entry in OUI_MAPPINGS for {normalized_mac_prefix}.")

    return oui_company

is_valid_mac(mac)

Verifies whether or not a string is a valid MAC address.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required

Returns:

Type Description
bool

The result as to whether or not the string is a valid MAC address.

Examples:

>>> from netutils.mac import is_valid_mac
>>> is_valid_mac("aa.bb.cc.dd.ee.ff")
True
>>> is_valid_mac("aa.bb.cc.dd.ee.gg")
False
>>>
Source code in netutils/mac.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def is_valid_mac(mac: str) -> bool:
    """Verifies whether or not a string is a valid MAC address.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.

    Returns:
        The result as to whether or not the string is a valid MAC address.

    Examples:
        >>> from netutils.mac import is_valid_mac
        >>> is_valid_mac("aa.bb.cc.dd.ee.ff")
        True
        >>> is_valid_mac("aa.bb.cc.dd.ee.gg")
        False
        >>>
    """
    for pattern in list(MAC_REGEX.values()):
        if re.fullmatch(pattern, mac):
            return True
    return False

mac_normalize(mac)

Return the MAC address with only the address, and no special characters.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required

Returns:

Type Description
str

The MAC address with no special characters.

Examples:

>>> from netutils.mac import mac_normalize
>>> mac_normalize("aa.bb.cc.dd.ee.ff")
'aabbccddeeff'
>>>
Source code in netutils/mac.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
@_valid_mac
def mac_normalize(mac: str) -> str:
    """Return the MAC address with only the address, and no special characters.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.

    Returns:
        The MAC address with no special characters.

    Examples:
        >>> from netutils.mac import mac_normalize
        >>> mac_normalize("aa.bb.cc.dd.ee.ff")
        'aabbccddeeff'
        >>>
    """
    chars = ":-."
    for char in chars:
        if char in mac:
            mac = mac.replace(char, "")
    return mac

mac_to_format(mac, frmt='MAC_NO_SPECIAL')

Converts the MAC address to a specific format.

The frmt is a combination delimiter (COLON, DASH, DOT) and number of characters (TWO, FOUR), e.g. f'MAC_{delimiter}_{char_num}' or if no special characters as MAC_NO_SPECIAL.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required
frmt str

A format in which the MAC address should be returned in, one of MAC_COLON_TWO, MAC_COLON_FOUR, MAC_DASH_TWO, MAC_DASH_FOUR, MAC_DOT_TWO, MAC_DOT_FOUR, MAC_NO_SPECIAL.

 'MAC_NO_SPECIAL'

Returns:

Type Description
str

A MAC address in the specified format.

Examples:

>>> from netutils.mac import mac_to_format
>>> mac_to_format("aa.bb.cc.dd.ee.ff", "MAC_DASH_FOUR")
'aabb-ccdd-eeff'
>>>
Source code in netutils/mac.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@_valid_mac
def mac_to_format(mac: str, frmt: str = "MAC_NO_SPECIAL") -> str:
    """Converts the MAC address to a specific format.

    The `frmt` is a combination delimiter (COLON, DASH, DOT) and number
    of characters (TWO, FOUR), e.g. f'MAC_{delimiter}_{char_num}' or if no
    special characters as `MAC_NO_SPECIAL`.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.
        frmt: A format in which the MAC address should be returned in, one of MAC_COLON_TWO, MAC_COLON_FOUR, MAC_DASH_TWO, MAC_DASH_FOUR, MAC_DOT_TWO, MAC_DOT_FOUR, MAC_NO_SPECIAL.

    Returns:
        A MAC address in the specified format.

    Examples:
        >>> from netutils.mac import mac_to_format
        >>> mac_to_format("aa.bb.cc.dd.ee.ff", "MAC_DASH_FOUR")
        'aabb-ccdd-eeff'
        >>>
    """
    if not MAC_CREATE.get(frmt):
        format_choices = ", ".join(MAC_CREATE)
        raise ValueError(f"An invalid mac format was provided in: `{frmt}`, not one of [{format_choices}]")
    mac = mac_normalize(mac)
    count = MAC_CREATE[frmt]["count"]
    char = MAC_CREATE[frmt]["char"]
    return char.join([mac[i : i + count] for i in range(0, len(mac), count)])  # type: ignore # noqa: E203

mac_to_int(mac)

Converts the MAC address to an integer.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required

Returns:

Type Description
int

The valid MAC address converted to an integer.

Examples:

>>> from netutils.mac import mac_to_int
>>> mac_to_int("aa.bb.cc.dd.ee.ff")
187723572702975
>>>
Source code in netutils/mac.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@_valid_mac
def mac_to_int(mac: str) -> int:
    """Converts the MAC address to an integer.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.

    Returns:
        The valid MAC address converted to an integer.

    Examples:
        >>> from netutils.mac import mac_to_int
        >>> mac_to_int("aa.bb.cc.dd.ee.ff")
        187723572702975
        >>>
    """
    return int(mac_normalize(mac), 16)

mac_type(mac)

Retuns the "type" of MAC address, as defined by the regex pattern names.

Parameters:

Name Type Description Default
mac str

A MAC address in string format that matches one of the defined regex patterns.

 required

Returns:

Type Description
Optional[str]

The regex pattern type of the MAC address.

Examples:

>>> from netutils.mac import mac_type
>>> mac_type("aa.bb.cc.dd.ee.ff")
'MAC_DOT_TWO'
>>> mac_type("aabb.ccdd.eeff")
'MAC_DOT_FOUR'
>>>
Source code in netutils/mac.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@_valid_mac
def mac_type(mac: str) -> t.Optional[str]:
    """Retuns the "type" of MAC address, as defined by the regex pattern names.

    Args:
        mac: A MAC address in string format that matches one of the defined regex patterns.

    Returns:
        The regex pattern type of the MAC address.

    Examples:
        >>> from netutils.mac import mac_type
        >>> mac_type("aa.bb.cc.dd.ee.ff")
        'MAC_DOT_TWO'
        >>> mac_type("aabb.ccdd.eeff")
        'MAC_DOT_FOUR'
        >>>
    """
    for name, pattern in MAC_REGEX.items():
        if re.fullmatch(pattern, mac):
            return name
    return None