A module for handling hardware identifiers like MAC addresses.
This module makes it easy to:
- check if a string represents a valid MAC address, or a similar hardware identifier like an EUI-64, OUI, etc,
- convert between string and binary forms of MAC addresses and other hardware identifiers,
and so on.
Heavily inspired by the ipaddress module, but not yet quite
as featureful.
This library's version numbers follow the SemVer 2.0.0 specification.
pip install macaddress
Import:
import macaddressClasses are provided for common hardware identifier
types (MAC/EUI48, EUI64, OUI, and
so on), as well as several less common ones. Others
might be added later. You can define ones that you
need in your code with just a few lines of code.
All provided classes support the standard and common formats.
For example, the EUI48 and MAC classes support the
following formats:
>>> macaddress.MAC('01-23-45-67-89-ab')
MAC('01-23-45-67-89-AB')
>>> macaddress.MAC('01:23:45:67:89:ab')
MAC('01-23-45-67-89-AB')
>>> macaddress.MAC('0123.4567.89ab')
MAC('01-23-45-67-89-AB')
>>> macaddress.MAC('0123456789ab')
MAC('01-23-45-67-89-AB')You can inspect what formats a hardware address class supports
by looking at its formats attribute:
>>> macaddress.OUI.formats
('xx-xx-xx', 'xx:xx:xx', 'xxxxxx')Each x in the format string matches one hexadecimal
"digit", and all other characters are matched literally.
If the string does not match one of the formats, a
ValueError is raised:
>>> try:
... macaddress.MAC('foo bar')
... except ValueError as error:
... print(error)
...
'foo bar' cannot be parsed as MACIf you need to parse in a format that isn't supported, you can define a subclass and add the format:
>>> class MACAllowsTrailingDelimiters(macaddress.MAC):
... formats = macaddress.MAC.formats + (
... 'xx-xx-xx-xx-xx-xx-',
... 'xx:xx:xx:xx:xx:xx:',
... 'xxxx.xxxx.xxxx.',
... )
...
>>> MACAllowsTrailingDelimiters('01-02-03-04-05-06-')
MACAllowsTrailingDelimiters('01-02-03-04-05-06')There is also a parse function for when you have a string
which might be one of several classes:
>>> from macaddress import EUI48, EUI64, MAC, OUI
>>> macaddress.parse('01:02:03', OUI, MAC)
OUI('01-02-03')
>>> macaddress.parse('01:02:03:04:05:06', OUI, MAC, EUI64)
MAC('01-02-03-04-05-06')
>>> macaddress.parse('010203040506', EUI64, EUI48)
EUI48('01-02-03-04-05-06')
>>> macaddress.parse('0102030405060708', EUI64, EUI48, OUI, MAC)
EUI64('01-02-03-04-05-06-07-08')If the input string cannot be parsed as any of
the given classes, a ValueError is raised:
>>> try:
... macaddress.parse('01:23', MAC, OUI)
... except ValueError as error:
... print(error)
...
'01:23' cannot be parsed as MAC or OUI
>>> try:
... macaddress.parse('01:23', MAC, OUI, EUI64)
... except ValueError as error:
... print(error)
...
'01:23' cannot be parsed as MAC, OUI, or EUI64Note that the message of the ValueError tries to be helpful
for developers, but it is not localized, nor is its exact text
part of the official public interface covered by SemVer.
All macaddress classes can be constructed from raw bytes:
>>> macaddress.MAC(b'abcdef')
MAC('61-62-63-64-65-66')
>>> macaddress.OUI(b'abc')
OUI('61-62-63')If the byte string is the wrong size, a ValueError is raised:
>>> try:
... macaddress.MAC(b'\x01\x02\x03')
... except ValueError as error:
... print(error)
...
b'\x01\x02\x03' has wrong length for MACAll macaddress classes can be constructed from raw integers:
>>> macaddress.MAC(0x010203ffeedd)
MAC('01-02-03-FF-EE-DD')
>>> macaddress.OUI(0x010203)
OUI('01-02-03')Note that the least-significant bit of the integer value maps to the last bit in the address type, so the same integer has a different meaning depending on the class you use it with:
>>> macaddress.MAC(1)
MAC('00-00-00-00-00-01')
>>> macaddress.OUI(1)
OUI('00-00-01')If the integer is too large for the hardware identifier class
that you're trying to construct, a ValueError is raised:
>>> try:
... macaddress.OUI(1_000_000_000)
... except ValueError as error:
... print(error)
...
1000000000 is too big for OUI>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> str(mac)
'01-02-03-04-05-06'
>>> str(mac).replace('-', ':')
'01:02:03:04:05:06'
>>> str(mac).replace('-', '')
'010203040506'>>> mac = macaddress.MAC('61-62-63-04-05-06')
>>> bytes(mac)
b'abc\x04\x05\x06'>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> int(mac)
1108152157446
>>> int(mac) == 0x010203040506
TrueMost classes supplied by this module have the oui
attribute, which returns their first three bytes as
an OUI object:
>>> macaddress.MAC('01:02:03:04:05:06').oui
OUI('01-02-03')All macaddress classes support equality comparisons:
>>> macaddress.OUI('01-02-03') == macaddress.OUI('01:02:03')
True
>>> macaddress.OUI('01-02-03') == macaddress.OUI('ff-ee-dd')
False
>>> macaddress.OUI('01-02-03') != macaddress.CDI32('01-02-03-04')
True
>>> macaddress.OUI('01-02-03') != macaddress.CDI32('01-02-03-04').oui
FalseAll macaddress classes support total
ordering. The comparisons are designed to
intuitively sort identifiers that start
with the same bits next to each other:
>>> some_values = [
... MAC('ff-ee-dd-01-02-03'),
... MAC('ff-ee-00-99-88-77'),
... MAC('ff-ee-dd-01-02-04'),
... OUI('ff-ee-dd'),
... ]
>>> for x in sorted(some_values):
... print(x)
FF-EE-00-01-02-03
FF-EE-DD
FF-EE-DD-01-02-03
FF-EE-DD-01-02-04This library is designed to make it very easy to use other hardware address types that this library does not currently define for you.
For example, if you want to handle IP-over-InfiniBand link-layer addresses, all you need to define is:
class InfiniBand(macaddress.HWAddress):
size = 20 * 8 # size in bits; 20 octets
formats = (
'xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx-xx',
'xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx',
'xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx',
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
# or whatever formats you want to support
)
# All formats are tried when parsing from string,
# and the first format is used when stringifying.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent