vinegar.transform.mac_address

Transformations for MAC addresses.

vinegar.transform.mac_address.normalize(value: str, target_case: str = 'upper', delimiter: str = ':', raise_error_if_malformed: bool = False) → str

Normalize a MAC address.

This function takes a MAC address (as a str) and transforms it into a normalized form. This means that each byte of the MAC address is represented by exactly two characters (adding a leading “0” if needed). The MAC address is also transformed to consistenly use upper or lower case characters and to use the specified delimiter.

While an input MAC address can have mixed upper / lower case characters, it must consistently use one delimiter (“:” or “-“).

When a malformed MAC address is encountered, the behavior depends on the raise_error_if_malformed option. If that option is set to True, a ValueError is raised. If it is False (the default), the input value is returned unchanged.

Parameters:

  • value – input MAC address to be transformed.

  • target_case – upper if the transformed MAC address shall use upper-case characters, lower if the transformed MAC address shall use lower-case characters. The default is upper.

  • delimiter – : or colon if the bytes of the MAC address shall be separated by a colon and -, dash or minus if the bytes of the MAC address shall be separated by a minus sign. The default is :.

  • raise_error_if_malformed – True if a malformed MAC address should result in a ValueError being raised, False if it should result in the input value being returned as is. The default is False.

Returns:

normalized form of the input MAC address.