nbcli/hwaddress

Code Issues Pull requests Releases 3 Activity

Lightweight python library for EUI-48, EUI-64 based hardware (MAC) addresses. https://pypi.org/project/hwaddress/

python

Python 100%

Find a file

Eric Geldmacher 4f052c51a3 All checks were successful ci/woodpecker/push/python-publish Pipeline was successful Details ci/woodpecker/push/lint-format-test-coverage Pipeline was successful Details ci/woodpecker/pr/python-publish Pipeline was successful Details ci/woodpecker/pr/lint-format-test-coverage Pipeline was successful Details ci/woodpecker/pull_request_closed/python-publish Pipeline was successful Details ci/woodpecker/manual/python-publish Pipeline was successful Details bump version		2024年07月18日 15:11:31 -05:00
.woodpecker	update woodpecker files	2024年07月18日 12:55:17 -05:00
hwaddress	Format with black	2023年03月29日 14:32:23 -05:00
tests	Format with black	2023年03月29日 14:32:23 -05:00
LICENSE	add license	2020年10月27日 16:16:46 -05:00
pyproject.toml	bump version	2024年07月18日 15:11:31 -05:00
README.rst	README cleanup	2021年03月10日 14:04:37 -06:00

README.rst

hwaddress

Lightweight python library for EUI-48, EUI-64 based hardware (MAC) addresses.

Quick start & Example usage

Install hwaddress

 $ pip install hwaddress

Import a few hwaddress classes and create instances by passing string representations of hardware address to them.

 >>> from hwaddress import MAC, EUI_48
 >>>
 >>> MAC('12:34:56:78:90:ab') 
MAC(12:34:56:78:90:ab)
 >>>
 >>> EUI_48('12-34-56-78-90-ab')
EUI_48(12-34-56-78-90-ab)

Strings passed to hwaddress classes do not have to conform to a given format. All occurrences of '-', ':', '.', ' ', '0x' are removed, and as long as the remaining characters are hexadecimal digits matching the bit-length of the class, and instance will be created.

The following list of strings are able to create instances of both MAC and EUI_48 classes.

 >>> maclist = ['12:34:56:78:90:ab', '23-78-ab-CD-43-ff', '0xABCDEF123456', '56 78 ab cd 12 54', '5432.abcd.3456', 'ab cdef.12-45:90']
 >>>
 >>> [MAC(mac) for mac in maclist]
[MAC(12:34:56:78:90:ab), MAC(23:78:ab:cd:43:ff), MAC(ab:cd:ef:12:34:56), MAC(56:78:ab:cd:12:54), MAC(54:32:ab:cd:34:56), MAC(ab:cd:ef:12:45:90)]
 >>>
 >>> [EUI_48(mac) for mac in maclist]
[EUI_48(12-34-56-78-90-ab), EUI_48(23-78-ab-cd-43-ff), EUI_48(ab-cd-ef-12-34-56), EUI_48(56-78-ab-cd-12-54), EUI_48(54-32-ab-cd-34-56), EUI_48(ab-cd-ef-12-45-90)]

hwaddress classes have a strict classmethod that (by default) will only return an instance if it matches the format defined by the class.

 >>> MAC.strict('12:34:56:78:90:ab')
MAC(12:34:56:78:90:ab)
 >>>
 >>> MAC.strict('12-34-56-78-90-ab')
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/Users/egeldmac/git/hwaddress/hwaddress/core.py", line 228, in strict
 raise ValueError(f'{address} did not pass verification.')
 ValueError: 12-34-56-78-90-ab did not pass verification.
 >>>
 >>> EUI_48.strict('12-34-56-78-90-ab')
EUI_48(12-34-56-78-90-ab)
 >>>
 >>> EUI_48.strict('12:34:56:78:90:ab')
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/Users/egeldmac/git/hwaddress/hwaddress/core.py", line 228, in strict
 raise ValueError(f'{address} did not pass verification.')
 ValueError: 12:34:56:78:90:ab did not pass verification.

hwaddress classes also have a verify classmethod that check if a string conforms to the format specified by the class.

 >>> MAC.verify('12:34:56:78:90:ab')
 True
 >>> MAC.verify('12-34-56-78-90-ab')
 False
 >>>
 >>> EUI_48.verify('12:34:56:78:90:ab')
 False
 >>> EUI_48.verify('12-34-56-78-90-ab')
 True

There is also a get_verifier factory function available that, when given hwaddress classes as arguments, will return a verifier function. This function will return True if the address passed conforms to the format of any of the hwaddress classes passed to get_verifier.

 >>> from hwaddress import get_verifier
 >>>
 >>> verifier = get_verifier(MAC, EUI_48)
 >>>
 >>> verifier('12:34:56:78:90:ab')
 True
 >>> verifier('12-34-56-78-90-ab')
 True
 >>> verifier('1234.5678.90ab')
 False

The resulting verifier can be used to filter a list of possible hardware addresses or be passed to the strict classmethod.

 >>> maclist
['12:34:56:78:90:ab', '23-78-ab-CD-43-ff', '0xABCDEF123456', '56 78 ab cd 12 54', '5432.abcd.3456', 'ab cdef.12-45:90']
 >>>
 >>> [EUI_48(mac) for mac in filter(verifier, maclist)]
[EUI_48(12-34-56-78-90-ab), EUI_48(23-78-ab-cd-43-ff)]
 >>>
 >>> EUI_48.strict('12:34:56:78:90:ab', verifier=verifier)
EUI_48(12-34-56-78-90-ab)
 >>>
 >>> EUI_48.strict('12-34-56-78-90-ab', verifier=verifier)
EUI_48(12-34-56-78-90-ab)
 >>>
 >>> EUI_48.strict('1234.5678.90ab', verifier=verifier)
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/Users/egeldmac/git/hwaddress/hwaddress/core.py", line 228, in strict
 raise ValueError(f'{address} did not pass verification.')
 ValueError: 1234.5678.90ab did not pass verification.

Included Hardware Address Classes

Name	Format	Properties
MAC	ff:ff:ff:ff:ff:ff
MAC_64	ff:ff:ff:ff:ff:ff:ff:ff
GUID	ffffffff-ffff-ffff-ffff-ffffffffffff
EUI_48	ff-ff-ff-ff-ff-ff	oui, oui36, cid
EUI_64	ff-ff-ff-ff-ff-ff-ff-ff	oui, oui36, cid
WWN	ff:ff:ff:ff:ff:ff:ff:ff	naa, oui
WWNx	ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff	naa, oui
IB_LID	0xffff
IB_GUID	ffff:ffff:ffff:ffff
IB_GID	ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff	prefix, guid

Common Classmethods/Methods/Properties

All classes inheriting from MAC will have the following methods, classmethos, and properties.

Name	Type	Returns	Description
verify	classmethod	bool	Verify that address conforms to formatting defined by class.
strict	classmethod	class instance	Create instance only if it passes verification.
format	method	str	Format address with given formatting options.
int	property	int	Integer representation of address.
hex	property	str	Hexadecimal representation of address.
binary	property	str	Padded binary representation of each hex digit in address.

verify(address)

Verify that address conforms to formatting defined by class.

 >>> hwaddress.MAC.verify('12:34:56:78:90:ab')
 True
 >>> hwaddress.MAC.verify('1234.5678.90ab')
 False

strict(address, verifier=None)

Create object only if it passes verification.
If no verifier is passed, the classes verify classmethod will be used.

 >>> MAC.strict('12:34:56:78:90:ab')
MAC(12:34:56:78:90:ab)
 >>> MAC.strict('12-34-56-78-90-ab')
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/Users/egeldmac/git/hwaddress/hwaddress/core.py", line 228, in strict
 raise ValueError(f'{address} did not pass verification.')
 ValueError: 12-34-56-78-90-ab did not pass verification.

format(self, delimiter=None, group=None, upper=None)

Format address with given formatting options.
If an option is not specified,
the option defined by the class will be used
Args:
 delimiter (str): character separating hex digits.
 group (int): how many hex digits in each group.
 upper (bool): True for uppercase, False for lowercase.

 >>> mac = hwaddress.MAC('12:34:56:78:90:ab')
 >>> mac
MAC(12:34:56:78:90:ab)
 >>> str(mac)
 '12:34:56:78:90:ab'
 >>> mac.format('-')
 '12-34-56-78-90-ab'
 >>> mac.format('.', 4)
 '1234.5678.90ab'
 >>> mac.format(group=4, upper=True)
 '1234:5678:90AB'

int

 >>> mac.int
 20015998341291

hex

 >>> mac.hex
 '0x1234567890ab'

binary

 >>> mac.binary
 '0001 0010 0011 0100 0101 0110 0111 1000 1001 0000 1010 1011'

EUI Properties

Name	Returns	Description
oui	OIU	24-bit Organizationally Unique Identifier.
cid	CID	24-bit Company ID.
oui36	OUI36	36-bit Organizationally Unique Identifier.

WWN Properties

Name	Returns	Description
naa	str	Network Address Authority.
oui	OUI	24-bit Organizationally Unique Identifier.

IB_GID Properties

Name	Returns	Description
prefix	IB_GID_prefix	64-bit IB_GID_prefix.
guid	IB_GUID	Embedded 64-bit IB_GUID.

Factory Functions

new_hwaddress_class

 >>> from hwaddress import new_hwaddress_class

get_address_factory

Return a hwaddress object from objs tuple depending on the address passed as an argument.

 >>> from hwaddress import get_address_factory, EUI_48, EUI_64
 >>>
 >>> hw_address = get_address_factory()
 >>>
 >>> hw_address('12:34:56:78:90:ab')
MAC(12:34:56:78:90:ab)
 >>> hw_address('12:34:56:78:90:ab:cd:ef')
MAC_64(12:34:56:78:90:ab:cd:ef)
 >>>
 >>> eui_address = get_address_factory(EUI_48, EUI_64)

get_verifier

 >>> from hwaddress import MAC, EUI_48, get_verifier
 >>>
 >>> class MyMAC(MAC):
... _len_ = 48
... _del_ = '.'
... _grp_ = 4
...
 >>>
 >>> my_verifier = get_verifier(MAC, EUI_48, MyMAC)
 >>>
 >>> my_verifier('12:34:56:78:90:ab')
 True
 >>> my_verifier('12-34-56-78-90-ab')
 True
 >>> my_verifier('1234.5678.90ab')
 True
 >>> my_verifier('12.34.56.78.90.ab')
 False
 >>> my_verifier('1234-5678-90ab')
 False