From 55441dc081905a77c5b4d08ef84777407b50c7b9 Mon Sep 17 00:00:00 2001
From: Jeremy Schulman <jeremy.schulman@mlb.com>
Date: Wed, 22 Sep 2021 13:49:37 -0400
Subject: [PATCH] v2.1

---
 macaddr.py | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 setup.py   |  2 +-
 2 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/macaddr.py b/macaddr.py
index 949c072..1bb53a2 100644
--- a/macaddr.py
+++ b/macaddr.py
@@ -51,9 +51,9 @@ def format(
         to_case: Optional[Callable] = None,
     ):
         """
-        Format the MAC address to the defined group size and group separator.  The default
-        settings of size=2 and sep=":" result in a MAC address format in "AA:BB:CC:DD:EE:FF"
-        notation, for example.
+        Format the MAC address to the defined group size and group separator.
+        The default settings of size=2 and sep=":" result in a MAC address
+        format in "AA:BB:CC:DD:EE:FF" notation, for example.
 
         The Caller can also use the `to_case` parameter to return the value
         using str.lower or str.upper case.  By default if `to_case` is not
@@ -90,6 +90,57 @@ def format(
         value = sep.join("".join(islice(i_chars, size)) for _ in range(chunks))
         return value if not to_case else to_case(value)
 
+    @lru_cache
+    def format_oui(
+        self,
+        size: Optional[int] = 2,
+        sep: Optional[str] = ":",
+        to_case: Optional[Callable] = None,
+    ):
+        """
+        Format the MAC address OUI to the defined group size and group
+        separator. The default settings of size=2 and sep=":" result in a MAC
+        address format in "AA:BB:CC" notation, for example.
+
+        The Caller can also use the `to_case` parameter to return the value
+        using str.lower or str.upper case.  By default if `to_case` is not
+        provided, then the character casing will be "as-is" passed in the
+        instance constructor.
+
+        The settings/return value are cached so that future calls using the same
+        criteria are optimized.  This is a desired condition since the MAC
+        address OUI format value may be used multiple times across many usages;
+        for example when looking for a MAC address maching an OUI in multiple
+        network devices.
+
+        Parameters
+        ----------
+        size: int - The group size of the octets.
+        sep: char - The group separator.
+        to_case: Callable - should generally be str.lower or str.upper for case formatting
+
+        Returns
+        -------
+        str - the formatted MAC address OUI string.
+
+        Raises
+        ------
+        ValueError if the `size` value is > 6; i.e. the max characters in an
+        OUI; not counting the separator character.
+        """
+        i_chars = iter(self.chars)
+        chunks, rem = divmod(6, size)
+
+        if not chunks:
+            raise ValueError(f"Invalid size {size}, not <= 6")
+
+        value = sep.join("".join(islice(i_chars, size)) for _ in range(chunks))
+
+        if rem:
+            value = f'{value}{sep}{"".join(islice(i_chars, rem))}'
+
+        return value if not to_case else to_case(value)
+
     def __repr__(self):
         return f"{self.__class__.__name__}({str(self)})"
 
diff --git a/setup.py b/setup.py
index 9fe9b56..9bc1693 100644
--- a/setup.py
+++ b/setup.py
@@ -30,7 +30,7 @@
 from setuptools import setup, find_packages
 
 package_name = "macaddr"
-package_version = "2.0"
+package_version = "2.1"
 
 
 with open("README.md", "r") as fh: