131 locate free extensions (#139)

Co-authored-by: CHOPP3D <[email protected]>

odins_spear/exceptions.py

@@ -113,8 +113,22 @@ class OSInvalidPasswordType(OSError):
     """
 
     def __str__(self) -> str:
-        return f"Invalid or unsupported password, please review supported passwords."   
+        return f"Invalid or unsupported password, please review supported passwords."  
+
+class OSExtensionNotFound(OSError):
+    """ Raised when a searched extension is not found
+    """ 
+
+    def __str__(self) -> str:
+        return f"Cannot locate extension. Please alter search criteria"
 
+class OSRangeFault(OSError):
+    """ Raised when a numeric range is invalid to the context provided, 
+        E.G: uninitialised range values, disordered range values.
+    """
+
+    def __str__(self):
+        return f"Range fault raised. Please verify integrity of passed range values"
 
 class OSServiceNotAssigned(OSError):
     """ Raised a service needed is not assigned to a Broadworks entity.  
@@ -123,7 +137,6 @@ class OSServiceNotAssigned(OSError):
     def __str__(self) -> str:
         return f"Service not assigend to target Broadworks entity. Please check services assigned."   
 
-
 class OSFileNotFound(OSError):
     """ Raised when a file can not be found.  
     """

odins_spear/scripter.py

@@ -167,6 +167,21 @@ def remove_numbers(self, service_provider_id: str, group_id: str, start_of_range
         return scripts.remove_numbers.main(self.api, service_provider_id, group_id, start_of_range_number, 
                        end_of_range_number)
 
+    def locate_free_extension( self, service_provider_id: str, group_id: str, range_start: int, range_end: int ):
+        """Locates the lowest value free extension given the provided range of extension numbers.
+
+        Raises: OSExtensionNotFound: Raises when a free extension is not located within the passed range.
+
+        Args:
+            service_provider_id (str): Service Provider/ Enterprise ID where Group is located which hosts needed free extensions
+            group_id (str): Group ID where target extensions are located.
+            range_start (int): integral value specifying the starting range for free extensions
+            range_end (int): integral value specifying the ending range for free extensions
+
+        Returns:
+            JSON: JSON data of the free extension {extension: "1000"}
+        """
+        return scripts.locate_free_extension.main( self.api, service_provider_id, group_id, range_start, range_end )
 
     def service_provider_trunking_capacity(self, service_provider_id: str):
         """Returns a JSON breakdown of the Trunking Call Capacity of a Service Provider/ Enterprise (SP/ENT). 

odins_spear/scripts/__init__.py

@@ -25,3 +25,4 @@
 from .user_activity import main
 from .user_association import main
 from .webex_builder import main
+from .locate_free_extension import main

odins_spear/scripts/locate_free_extension.py

@@ -0,0 +1,40 @@
+from exceptions import OSExtensionNotFound, OSRangeFault
+
+def retrieve_extensions( api, service_provider_id: str, group_id: str ) -> list:
+
+    extensions = []
+
+    dataset = (
+       api.get.users( service_provider_id, group_id              ) +
+       api.get.group_hunt_groups( service_provider_id, group_id  ) +
+       api.get.group_call_centers( service_provider_id, group_id ) +
+       api.get.auto_attendants( service_provider_id, group_id    )
+    )
+
+    for data in dataset:
+        if not data['extension']:
+            continue
+
+        extensions.append( int(data['extension']) )
+
+    return extensions if extensions else None
+
+def main( api, service_provider_id: str, group_id: str, range_start: int, range_end: int ):
+    '''Retrieves The Lowest Free Extension Available In The Designated Group Passed.
+    '''
+
+    if range_start > range_end:
+        raise OSRangeFault
+
+    # Retrieve List Of Occupied Extensions Within The Group
+    extensions = retrieve_extensions(
+        api,
+        service_provider_id,
+        group_id,
+    )
+
+    for extension in range(range_start, range_end + 1):
+        if extension not in extensions:
+            return {'extension': extension}
+
+    raise OSExtensionNotFound