You're Invited:Meet the Socket Team at RSAC and BSidesSF 2026, March 23–26.RSVP →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

macaddress

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

macaddress - pypi Package Compare versions

Comparing version
1.0.0
 to
1.0.1
+234
-33
macaddress.egg-info/PKG-INFO
Metadata-Version: 1.1
Name: macaddress
Version: 1.0.0
Version: 1.0.1
Summary: Like ``ipaddress``, but for hardware identifiers such as MAC addresses.

@@ -52,7 +52,16 @@ Home-page: https://github.com/mentalisttraceur/python-macaddress

Several classes are provided to parse common hardware addresses
(``MAC``/``EUI48``, ``EUI64``, ``OUI``, etc), as well as
several less common ones (``EUI60``, ``CDI32``, etc). They each
support several common formats.
Classes 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.
Parse or Validate String
~~~~~~~~~~~~~~~~~~~~~~~~
When only one address type is valid:
````````````````````````````````````
All provided classes support the standard and common formats.
For example, the ``EUI48`` and ``MAC`` classes support the

@@ -80,31 +89,72 @@ following formats:

The first format listed in ``formats`` is also the one used
when stringifying (``str``) or representing (``repr``) the
object.
Each ``x`` in the format string matches one hexadecimal
"digit", and all other characters are matched literally.
Most classes supplied by this module have the ``oui``
attribute, which just returns their first three bytes as
an OUI object:
If the string does not match one of the formats, a
``ValueError`` is raised:
.. code:: python
>>> macaddress.EUI48('01:02:03:04:05:06').oui
>>> macaddress.MAC('foo bar')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 84, in __init__
self._address, _ = _parse(address, type(self))
File "/home/user/code/m/macaddress.py", line 357, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'foo bar' cannot be parsed as MAC
If you need to parse in a format that isn't supported,
you can define a subclass and add the format:
.. code:: python
>>> class MACAllowsTrailingDelimiters(macaddress.MAC):
... formats = macaddress.MAC.formats + (
... 'xx-xx-xx-xx-xx-xx-',
... 'xx:xx:xx:xx:xx:xx:',
... 'xxxx.xxxx.xxxx.',
... 'xxxxxxxxxxxx',
... )
...
>>> MACAllowsTrailingDelimiters('01-02-03-04-05-06-')
MACAllowsTrailingDelimiters('01-02-03-04-05-06')
When multiple address types are valid:
``````````````````````````````````````
There is also a ``parse`` function for when you have a string
which might be one of several classes:
.. code:: python
>>> macaddress.parse('01:02:03', macaddress.OUI, macaddress.MAC)
OUI('01-02-03')
>>> macaddress.parse('01:02:03:04:05:06', macaddress.OUI, macaddress.MAC)
MAC('01-02-03-04-05-06')
>>> macaddress.parse('010203040506', macaddress.EUI64, macaddress.EUI48)
EUI48('01-02-03-04-05-06')
>>> macaddress.parse('0102030405060708', macaddress.EUI64, macaddress.EUI48)
EUI64('01-02-03-04-05-06-07-08')
All ``macaddress`` classes support equality comparisons:
Note that the message of the ``ValueError`` tries to be helpful
to humans by mentioning what classes you tried to parse it as:
.. code:: python
>>> 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')
False
>>> macaddress.OUI('01-02-03') == macaddress.CDI32('01-02-03-04').oui
True
>>> macaddress.parse('x', macaddress.MAC, macaddress.OUI, macaddress.EUI64)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 335, in parse
address, cls = _parse(string, *classes)
File "/home/user/code/m/macaddress.py", line 363, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'x' cannot be parsed as MAC, OUI, or EUI64
All ``macaddress`` classes can be initialized with raw bytes
or raw integers representing their value instead of strings:
Parse from Bytes
~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw bytes:
.. code:: python

@@ -114,23 +164,150 @@

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:
.. code:: python
>>> macaddress.MAC(b'\x01\x02\x03')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 86, in __init__
raise _value_error(address, 'has wrong length for', type(self))
ValueError: b'\x01\x02\x03' has wrong length for MAC
Parse from Integers
~~~~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw integers:
.. code:: python
>>> 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:
.. code:: python
>>> macaddress.MAC(1)
MAC('00-00-00-00-00-01')
>>> macaddress.OUI(b'abc')
OUI('61-62-63')
>>> macaddress.OUI(0x010203)
OUI('01-02-03')
>>> macaddress.OUI(1)
OUI('00-00-01')
If any of the values passed to the constructors are invalid,
the constructors raise a ``TypeError`` or a ``ValueError``
as appropriate.
If the integer is too large for the hardware identifier class
that you're trying to construct, a ``ValueError`` is raised:
All ``macaddress`` classes also support total ordering. The
comparisons are intended to intuitively put identifiers
that start with the same bits next to each other sorting:
.. code:: python
>>> macaddress.OUI(1_000_000_000)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 78, in __init__
raise _value_error(address, 'is too big for', type(self))
ValueError: 1000000000 is too big for OUI
Get as String
~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> str(mac)
01-02-03-04-05-06
The first format listed in ``formats`` is used when
stringifying the object. If you want to use a
different format, you can override the ``formats``
attribute on the instance, or on a subclass:
.. code:: python
>>> mac.formats = ('xx:xx:xx:xx:xx:xx',)
>>> str(mac)
01-02-03-04-05-06
>>> class MACWithColonsByDefault(macaddress.MAC):
... formats = ('xx:xx:xx:xx:xx:xx',) + macaddress.MAC.formats
...
>>> MACWithColonsByDefault('ab:cd:ef:01:02:03')
MACWithColonsByDefault('AB:CD:EF:01:02:03')
>>> str(MACWithColonsByDefault('ab-cd-ef-01-02-03'))
AB:CD:EF:01:02:03
Note that appending the original ``formats``
tuple to the new custom formats ensures that
you can still *parse* all the valid formats.
Get as Bytes
~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('61-62-63-04-05-06')
>>> bytes(mac)
b'abc\x04\x05\x06'
Get as Integer
~~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> int(mac)
1108152157446
>>> int(mac) == 0x010203040506
True
Get the OUI
~~~~~~~~~~~
Most classes supplied by this module have the ``oui``
attribute, which returns their first three bytes as
an OUI object:
.. code:: python
>>> macaddress.MAC('01:02:03:04:05:06').oui
OUI('01-02-03')
Compare
~~~~~~~
Equality
````````
All ``macaddress`` classes support equality comparisons:
.. code:: python
>>> 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
False
Ordering
````````
All ``macaddress`` classes support total
ordering. The comparisons are designed to
intuitively sort identifiers that start
with the same bits next to each other:
.. code:: python
>>> some_values = [

@@ -149,2 +326,26 @@ ... MAC('ff-ee-dd-01-02-03'),

Define New Types
~~~~~~~~~~~~~~~~
This 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:
.. code:: python
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
)
Platform: UNKNOWN

@@ -151,0 +352,0 @@ Classifier: Development Status :: 5 - Production/Stable

+16
-7
macaddress.py

@@ -15,3 +15,3 @@ # SPDX-License-Identifier: 0BSD

)
__version__ = '1.0.0'
__version__ = '1.0.1'

@@ -28,5 +28,11 @@

class_names = [cls.__name__ for cls in classes]
if len(class_names) > 1:
number_of_classes = len(classes)
if number_of_classes < 2:
class_description = class_names[0]
elif number_of_classes == 2:
class_description = ' or '.join(class_names)
else:
class_names[-1] = 'or ' + class_names[-1]
return ValueError(repr(value) + ' ' + error + ' ' + ', '.join(class_names))
class_description = ', '.join(class_names)
return ValueError(repr(value) + ' ' + error + ' ' + class_description)

@@ -328,3 +334,6 @@

given classes.
TypeError: If the string is not actually a string.
"""
if not isinstance(string, str):
return TypeError
if not classes:

@@ -336,4 +345,4 @@ return None

def _parse(input, *classes):
length = len(input)
def _parse(string, *classes):
length = len(string)
if length < 1:

@@ -351,3 +360,3 @@ raise ValueError('hardware address cannot be an empty string')

for index in range(length):
character = input[index]
character = string[index]
if character in _HEX_DIGITS:

@@ -362,3 +371,3 @@ address <<= 4

if start >= end:
raise _value_error(input, 'cannot be parsed as', *classes)
raise _value_error(string, 'cannot be parsed as', *classes)
_, cls = candidates[start]

@@ -365,0 +374,0 @@ offset = (4 - cls.size) & 3

+234
-33
PKG-INFO
Metadata-Version: 1.1
Name: macaddress
Version: 1.0.0
Version: 1.0.1
Summary: Like ``ipaddress``, but for hardware identifiers such as MAC addresses.

@@ -52,7 +52,16 @@ Home-page: https://github.com/mentalisttraceur/python-macaddress

Several classes are provided to parse common hardware addresses
(``MAC``/``EUI48``, ``EUI64``, ``OUI``, etc), as well as
several less common ones (``EUI60``, ``CDI32``, etc). They each
support several common formats.
Classes 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.
Parse or Validate String
~~~~~~~~~~~~~~~~~~~~~~~~
When only one address type is valid:
````````````````````````````````````
All provided classes support the standard and common formats.
For example, the ``EUI48`` and ``MAC`` classes support the

@@ -80,31 +89,72 @@ following formats:

The first format listed in ``formats`` is also the one used
when stringifying (``str``) or representing (``repr``) the
object.
Each ``x`` in the format string matches one hexadecimal
"digit", and all other characters are matched literally.
Most classes supplied by this module have the ``oui``
attribute, which just returns their first three bytes as
an OUI object:
If the string does not match one of the formats, a
``ValueError`` is raised:
.. code:: python
>>> macaddress.EUI48('01:02:03:04:05:06').oui
>>> macaddress.MAC('foo bar')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 84, in __init__
self._address, _ = _parse(address, type(self))
File "/home/user/code/m/macaddress.py", line 357, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'foo bar' cannot be parsed as MAC
If you need to parse in a format that isn't supported,
you can define a subclass and add the format:
.. code:: python
>>> class MACAllowsTrailingDelimiters(macaddress.MAC):
... formats = macaddress.MAC.formats + (
... 'xx-xx-xx-xx-xx-xx-',
... 'xx:xx:xx:xx:xx:xx:',
... 'xxxx.xxxx.xxxx.',
... 'xxxxxxxxxxxx',
... )
...
>>> MACAllowsTrailingDelimiters('01-02-03-04-05-06-')
MACAllowsTrailingDelimiters('01-02-03-04-05-06')
When multiple address types are valid:
``````````````````````````````````````
There is also a ``parse`` function for when you have a string
which might be one of several classes:
.. code:: python
>>> macaddress.parse('01:02:03', macaddress.OUI, macaddress.MAC)
OUI('01-02-03')
>>> macaddress.parse('01:02:03:04:05:06', macaddress.OUI, macaddress.MAC)
MAC('01-02-03-04-05-06')
>>> macaddress.parse('010203040506', macaddress.EUI64, macaddress.EUI48)
EUI48('01-02-03-04-05-06')
>>> macaddress.parse('0102030405060708', macaddress.EUI64, macaddress.EUI48)
EUI64('01-02-03-04-05-06-07-08')
All ``macaddress`` classes support equality comparisons:
Note that the message of the ``ValueError`` tries to be helpful
to humans by mentioning what classes you tried to parse it as:
.. code:: python
>>> 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')
False
>>> macaddress.OUI('01-02-03') == macaddress.CDI32('01-02-03-04').oui
True
>>> macaddress.parse('x', macaddress.MAC, macaddress.OUI, macaddress.EUI64)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 335, in parse
address, cls = _parse(string, *classes)
File "/home/user/code/m/macaddress.py", line 363, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'x' cannot be parsed as MAC, OUI, or EUI64
All ``macaddress`` classes can be initialized with raw bytes
or raw integers representing their value instead of strings:
Parse from Bytes
~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw bytes:
.. code:: python

@@ -114,23 +164,150 @@

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:
.. code:: python
>>> macaddress.MAC(b'\x01\x02\x03')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 86, in __init__
raise _value_error(address, 'has wrong length for', type(self))
ValueError: b'\x01\x02\x03' has wrong length for MAC
Parse from Integers
~~~~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw integers:
.. code:: python
>>> 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:
.. code:: python
>>> macaddress.MAC(1)
MAC('00-00-00-00-00-01')
>>> macaddress.OUI(b'abc')
OUI('61-62-63')
>>> macaddress.OUI(0x010203)
OUI('01-02-03')
>>> macaddress.OUI(1)
OUI('00-00-01')
If any of the values passed to the constructors are invalid,
the constructors raise a ``TypeError`` or a ``ValueError``
as appropriate.
If the integer is too large for the hardware identifier class
that you're trying to construct, a ``ValueError`` is raised:
All ``macaddress`` classes also support total ordering. The
comparisons are intended to intuitively put identifiers
that start with the same bits next to each other sorting:
.. code:: python
>>> macaddress.OUI(1_000_000_000)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 78, in __init__
raise _value_error(address, 'is too big for', type(self))
ValueError: 1000000000 is too big for OUI
Get as String
~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> str(mac)
01-02-03-04-05-06
The first format listed in ``formats`` is used when
stringifying the object. If you want to use a
different format, you can override the ``formats``
attribute on the instance, or on a subclass:
.. code:: python
>>> mac.formats = ('xx:xx:xx:xx:xx:xx',)
>>> str(mac)
01-02-03-04-05-06
>>> class MACWithColonsByDefault(macaddress.MAC):
... formats = ('xx:xx:xx:xx:xx:xx',) + macaddress.MAC.formats
...
>>> MACWithColonsByDefault('ab:cd:ef:01:02:03')
MACWithColonsByDefault('AB:CD:EF:01:02:03')
>>> str(MACWithColonsByDefault('ab-cd-ef-01-02-03'))
AB:CD:EF:01:02:03
Note that appending the original ``formats``
tuple to the new custom formats ensures that
you can still *parse* all the valid formats.
Get as Bytes
~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('61-62-63-04-05-06')
>>> bytes(mac)
b'abc\x04\x05\x06'
Get as Integer
~~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> int(mac)
1108152157446
>>> int(mac) == 0x010203040506
True
Get the OUI
~~~~~~~~~~~
Most classes supplied by this module have the ``oui``
attribute, which returns their first three bytes as
an OUI object:
.. code:: python
>>> macaddress.MAC('01:02:03:04:05:06').oui
OUI('01-02-03')
Compare
~~~~~~~
Equality
````````
All ``macaddress`` classes support equality comparisons:
.. code:: python
>>> 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
False
Ordering
````````
All ``macaddress`` classes support total
ordering. The comparisons are designed to
intuitively sort identifiers that start
with the same bits next to each other:
.. code:: python
>>> some_values = [

@@ -149,2 +326,26 @@ ... MAC('ff-ee-dd-01-02-03'),

Define New Types
~~~~~~~~~~~~~~~~
This 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:
.. code:: python
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
)
Platform: UNKNOWN

@@ -151,0 +352,0 @@ Classifier: Development Status :: 5 - Production/Stable

+233
-32
README.rst

@@ -44,7 +44,16 @@ macaddress

Several classes are provided to parse common hardware addresses
(``MAC``/``EUI48``, ``EUI64``, ``OUI``, etc), as well as
several less common ones (``EUI60``, ``CDI32``, etc). They each
support several common formats.
Classes 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.
Parse or Validate String
~~~~~~~~~~~~~~~~~~~~~~~~
When only one address type is valid:
````````````````````````````````````
All provided classes support the standard and common formats.
For example, the ``EUI48`` and ``MAC`` classes support the

@@ -72,31 +81,72 @@ following formats:

The first format listed in ``formats`` is also the one used
when stringifying (``str``) or representing (``repr``) the
object.
Each ``x`` in the format string matches one hexadecimal
"digit", and all other characters are matched literally.
Most classes supplied by this module have the ``oui``
attribute, which just returns their first three bytes as
an OUI object:
If the string does not match one of the formats, a
``ValueError`` is raised:
.. code:: python
>>> macaddress.EUI48('01:02:03:04:05:06').oui
>>> macaddress.MAC('foo bar')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 84, in __init__
self._address, _ = _parse(address, type(self))
File "/home/user/code/m/macaddress.py", line 357, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'foo bar' cannot be parsed as MAC
If you need to parse in a format that isn't supported,
you can define a subclass and add the format:
.. code:: python
>>> class MACAllowsTrailingDelimiters(macaddress.MAC):
... formats = macaddress.MAC.formats + (
... 'xx-xx-xx-xx-xx-xx-',
... 'xx:xx:xx:xx:xx:xx:',
... 'xxxx.xxxx.xxxx.',
... 'xxxxxxxxxxxx',
... )
...
>>> MACAllowsTrailingDelimiters('01-02-03-04-05-06-')
MACAllowsTrailingDelimiters('01-02-03-04-05-06')
When multiple address types are valid:
``````````````````````````````````````
There is also a ``parse`` function for when you have a string
which might be one of several classes:
.. code:: python
>>> macaddress.parse('01:02:03', macaddress.OUI, macaddress.MAC)
OUI('01-02-03')
>>> macaddress.parse('01:02:03:04:05:06', macaddress.OUI, macaddress.MAC)
MAC('01-02-03-04-05-06')
>>> macaddress.parse('010203040506', macaddress.EUI64, macaddress.EUI48)
EUI48('01-02-03-04-05-06')
>>> macaddress.parse('0102030405060708', macaddress.EUI64, macaddress.EUI48)
EUI64('01-02-03-04-05-06-07-08')
All ``macaddress`` classes support equality comparisons:
Note that the message of the ``ValueError`` tries to be helpful
to humans by mentioning what classes you tried to parse it as:
.. code:: python
>>> 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')
False
>>> macaddress.OUI('01-02-03') == macaddress.CDI32('01-02-03-04').oui
True
>>> macaddress.parse('x', macaddress.MAC, macaddress.OUI, macaddress.EUI64)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 335, in parse
address, cls = _parse(string, *classes)
File "/home/user/code/m/macaddress.py", line 363, in _parse
raise _value_error(input, 'cannot be parsed as', *classes)
ValueError: 'x' cannot be parsed as MAC, OUI, or EUI64
All ``macaddress`` classes can be initialized with raw bytes
or raw integers representing their value instead of strings:
Parse from Bytes
~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw bytes:
.. code:: python

@@ -106,23 +156,150 @@

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:
.. code:: python
>>> macaddress.MAC(b'\x01\x02\x03')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 86, in __init__
raise _value_error(address, 'has wrong length for', type(self))
ValueError: b'\x01\x02\x03' has wrong length for MAC
Parse from Integers
~~~~~~~~~~~~~~~~~~~
All ``macaddress`` classes can be constructed from raw integers:
.. code:: python
>>> 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:
.. code:: python
>>> macaddress.MAC(1)
MAC('00-00-00-00-00-01')
>>> macaddress.OUI(b'abc')
OUI('61-62-63')
>>> macaddress.OUI(0x010203)
OUI('01-02-03')
>>> macaddress.OUI(1)
OUI('00-00-01')
If any of the values passed to the constructors are invalid,
the constructors raise a ``TypeError`` or a ``ValueError``
as appropriate.
If the integer is too large for the hardware identifier class
that you're trying to construct, a ``ValueError`` is raised:
All ``macaddress`` classes also support total ordering. The
comparisons are intended to intuitively put identifiers
that start with the same bits next to each other sorting:
.. code:: python
>>> macaddress.OUI(1_000_000_000)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/user/code/m/macaddress.py", line 78, in __init__
raise _value_error(address, 'is too big for', type(self))
ValueError: 1000000000 is too big for OUI
Get as String
~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> str(mac)
01-02-03-04-05-06
The first format listed in ``formats`` is used when
stringifying the object. If you want to use a
different format, you can override the ``formats``
attribute on the instance, or on a subclass:
.. code:: python
>>> mac.formats = ('xx:xx:xx:xx:xx:xx',)
>>> str(mac)
01-02-03-04-05-06
>>> class MACWithColonsByDefault(macaddress.MAC):
... formats = ('xx:xx:xx:xx:xx:xx',) + macaddress.MAC.formats
...
>>> MACWithColonsByDefault('ab:cd:ef:01:02:03')
MACWithColonsByDefault('AB:CD:EF:01:02:03')
>>> str(MACWithColonsByDefault('ab-cd-ef-01-02-03'))
AB:CD:EF:01:02:03
Note that appending the original ``formats``
tuple to the new custom formats ensures that
you can still *parse* all the valid formats.
Get as Bytes
~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('61-62-63-04-05-06')
>>> bytes(mac)
b'abc\x04\x05\x06'
Get as Integer
~~~~~~~~~~~~~~
.. code:: python
>>> mac = macaddress.MAC('01-02-03-04-05-06')
>>> int(mac)
1108152157446
>>> int(mac) == 0x010203040506
True
Get the OUI
~~~~~~~~~~~
Most classes supplied by this module have the ``oui``
attribute, which returns their first three bytes as
an OUI object:
.. code:: python
>>> macaddress.MAC('01:02:03:04:05:06').oui
OUI('01-02-03')
Compare
~~~~~~~
Equality
````````
All ``macaddress`` classes support equality comparisons:
.. code:: python
>>> 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
False
Ordering
````````
All ``macaddress`` classes support total
ordering. The comparisons are designed to
intuitively sort identifiers that start
with the same bits next to each other:
.. code:: python
>>> some_values = [

@@ -140,1 +317,25 @@ ... MAC('ff-ee-dd-01-02-03'),

FF-EE-DD-01-02-04
Define New Types
~~~~~~~~~~~~~~~~
This 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:
.. code:: python
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
)