Keith/api/update parts from avl (#162)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: Keith Hanson <[email protected]>
Co-authored-by: Keith Hanson <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jeff Moody <[email protected]>
Co-authored-by: Jeff Moody <[email protected]>
Co-authored-by: ansys-pwalters <[email protected]>

Author: 6 people

doc/source/api/parts.rst

@@ -16,4 +16,5 @@ The ``parts`` module contains all parts management capabilities.
      ansys.sherlock.core.parts.Parts.update_parts_list
      ansys.sherlock.core.parts.Parts.update_parts_locations
      ansys.sherlock.core.parts.Parts.update_parts_locations_by_file
-     ansys.sherlock.core.parts.Parts.get_part_location
+     ansys.sherlock.core.parts.Parts.get_part_location
+     ansys.sherlock.core.parts.Parts.update_parts_from_AVL

doc/source/api/parts_types.rst

@@ -11,3 +11,7 @@ Constants and classes used for the Parts API.
      :toctree: _autosummary
 
      PartLocation
+     PartsListSearchMatchingMode
+     PartsListSearchDuplicationMode
+     AVLPartNum
+     AVLDescription

src/ansys/sherlock/core/errors.py

@@ -892,3 +892,20 @@ def __init__(self, message):
     def __str__(self):
         """Format error message."""
         return f"Update part modeling props error: {self.message}"
+
+
+class SherlockUpdatePartsFromAVLError(Exception):
+    """Contains the error raised when parts list cannot be updated by AVL."""
+
+    def __init__(self, message=None, error_array=None):
+        """Initialize error message."""
+        self.message = message
+        self.error_array = error_array
+
+    def str_itr(self):
+        """Create list of error messages."""
+        if self.message is None:
+            return [f"Update part from AVL error: {error}" for error in self.error_array]
+
+        assert self.error_array is None
+        return [f"Update part from AVL error: {self.message}"]

src/ansys/sherlock/core/parts.py

@@ -15,12 +15,19 @@
     SherlockExportPartsListError,
     SherlockGetPartLocationError,
     SherlockImportPartsListError,
+    SherlockUpdatePartsFromAVLError,
     SherlockUpdatePartsListError,
     SherlockUpdatePartsLocationsByFileError,
     SherlockUpdatePartsLocationsError,
 )
 from ansys.sherlock.core.grpc_stub import GrpcStub
-from ansys.sherlock.core.types.parts_types import PartLocation
+from ansys.sherlock.core.types.parts_types import (
+    AVLDescription,
+    AVLPartNum,
+    PartLocation,
+    PartsListSearchDuplicationMode,
+    PartsListSearchMatchingMode,
+)
 
 
 class Parts(GrpcStub):
@@ -34,6 +41,12 @@ def __init__(self, channel):
         self.BOARD_SIDES = None
         self.MATCHING_ARGS = ["Both", "Part"]
         self.DUPLICATION_ARGS = ["First", "Error", "Ignore"]
+        self.AVL_PART_NUM_ARGS = [
+            "AssignInternalPartNum",
+            "AssignVendorAndPartNum",
+            "DoNotChangeVendorOrPartNum",
+        ]
+        self.AVL_DESCRIPTION_ARGS = ["AssignApprovedDescription", "DoNotChangeDescription"]
 
     @staticmethod
     def _add_matching_duplication(request, matching, duplication):
@@ -155,8 +168,8 @@ def update_parts_list(
         project,
         cca_name,
         part_library,
-        matching,
-        duplication,
+        matching_mode,
+        duplication_mode,
     ):
         """Update a parts list based on matching and duplication preferences.
 
@@ -168,9 +181,9 @@ def update_parts_list(
             Name of the CCA.
         part_library : str
             Name of the parts library.
-        matching : UpdatesPartsListRequestMatchingMode
+        matching_mode : PartsListSearchMatchingMode
             Matching mode for updates.
-        duplication : UpdatesPartsListRequestDuplicationMode
+        duplication_mode : PartsListSearchDuplicationMode
             How to handle duplication during the update.
 
         Returns
@@ -219,7 +232,7 @@ def update_parts_list(
             project=project, ccaName=cca_name, partLibrary=part_library
         )
 
-        self._add_matching_duplication(request, matching, duplication)
+        self._add_matching_duplication(request, matching_mode, duplication_mode)
 
         response = self.stub.updatePartsList(request)
 
@@ -690,3 +703,104 @@ def get_part_location(self, project, cca_name, ref_des, location_units):
         except SherlockGetPartLocationError as e:
             LOG.error(str(e))
             raise e
+
+    def update_parts_from_AVL(
+        self,
+        project: str,
+        cca_name: str,
+        matching_mode: PartsListSearchMatchingMode,
+        duplication_mode: PartsListSearchDuplicationMode,
+        avl_part_num: AVLPartNum,
+        avl_description: AVLDescription,
+    ) -> SherlockPartsService_pb2.UpdatePartsListFromAVLResponse:
+        r"""Update the parts list from the Approved Vendor List (AVL).
+
+        Parameters
+        ----------
+        project : str
+            Name of the Sherlock project.
+        cca_name : str
+            Name of the CCA.
+        matching_mode: PartsListSearchMatchingMode
+            Determines how parts are matched against the AVL
+        duplication_mode: PartsListSearchDuplicationMode
+            Determines how duplicate part matches are handled when found
+        avl_part_num: AVLPartNum
+            Determines what part number info in the parts list is updated from the AVL
+        avl_description: AVLDescription
+            Determines if the part description is updated or not
+
+        Returns
+        -------
+        UpdatePartsListFromAVLResponse
+            - returnCode : ReturnCode
+                - value : int
+                    Status code of the response. 0 for success.
+                - message : str
+                    indicates general errors that occurred while attempting to update parts
+            - numPartsUpdated : int
+                Number of parts updated
+            - updateErrors : list<str>
+                Errors found when updating part
+
+        Examples
+        --------
+        >>> from ansys.sherlock.core.launcher import launch_sherlock
+        >>> from ansys.sherlock.core.types.parts_types import (
+            AVLDescription,
+            AVLPartNum,
+            UpdatesPartsListRequestDuplicationMode,
+            UpdatesPartsListRequestMatchingMode
+        )
+        >>> sherlock = launch_sherlock()
+        >>> sherlock.project.import_odb_archive(
+            "C:\\Program Files\\ANSYS Inc\\v241\\sherlock\\tutorial\\ODB++ Tutorial.tgz",
+            True,
+            True,
+            True,
+            True,
+            project="Test",
+            cca_name="Card",
+        )
+        >>> sherlock.parts.update_parts_from_AVL(
+            project="Test",
+            cca_name="Card",
+            matching_mode=UpdatesPartsListRequestMatchingMode.BOTH,
+            duplication=UpdatesPartsListRequestDuplicationMode.FIRST,
+            avl_part_num=AVLPartNum.ASSIGN_INTERNAL_PART_NUM,
+            avl_description=AVLDescription.ASSIGN_APPROVED_DESCRIPTION
+        )
+        """
+        try:
+            if project == "":
+                raise SherlockUpdatePartsFromAVLError(message="Project name is invalid.")
+            if cca_name == "":
+                raise SherlockUpdatePartsFromAVLError(message="CCA name is invalid.")
+
+            request = SherlockPartsService_pb2.UpdatePartsListFromAVLRequest(
+                project=project,
+                ccaName=cca_name,
+                matching=matching_mode,
+                duplication=duplication_mode,
+                avlPartNum=avl_part_num,
+                avlDesc=avl_description,
+            )
+
+            if not self._is_connection_up():
+                LOG.error("Not connected to a gRPC service.")
+                return
+
+            # Call method on server
+            response = self.stub.updatePartsListFromAVL(request)
+
+            return_code = response.returnCode
+
+            if return_code.value == -1:
+                if return_code.message == "":
+                    raise SherlockUpdatePartsFromAVLError(error_array=response.updateErrors)
+                raise SherlockUpdatePartsFromAVLError(message=return_code.message)
+
+            return response
+        except SherlockUpdatePartsFromAVLError as e:
+            LOG.error(str(e))
+            raise e

src/ansys/sherlock/core/types/parts_types.py

@@ -8,19 +8,36 @@
     from ansys.api.sherlock.v0 import SherlockPartsService_pb2
 
 
-class UpdatesPartsListRequestMatchingMode:
-    """Constants for Matching Mode in the Update Parts List request."""
+class PartsListSearchMatchingMode:
+    """Constants for Matching Mode in the Update Parts List and Update Parts from AVL request."""
 
-    BOTH = SherlockPartsService_pb2.UpdatePartsListRequest.MatchingMode.Both
-    PART = SherlockPartsService_pb2.UpdatePartsListRequest.MatchingMode.Part
+    BOTH = SherlockPartsService_pb2.MatchingMode.Both
+    PART = SherlockPartsService_pb2.MatchingMode.Part
 
 
-class UpdatesPartsListRequestDuplicationMode:
-    """Constants for Duplication Mode in the Update Parts List request."""
+class PartsListSearchDuplicationMode:
+    """Constants for Duplication Mode in the Update Parts List and Update Parts from AVL request."""
 
-    FIRST = SherlockPartsService_pb2.UpdatePartsListRequest.DuplicationMode.First
-    ERROR = SherlockPartsService_pb2.UpdatePartsListRequest.DuplicationMode.Error
-    IGNORE = SherlockPartsService_pb2.UpdatePartsListRequest.DuplicationMode.Ignore
+    FIRST = SherlockPartsService_pb2.DuplicationMode.First
+    ERROR = SherlockPartsService_pb2.DuplicationMode.Error
+    IGNORE = SherlockPartsService_pb2.DuplicationMode.Ignore
+
+
+class AVLPartNum:
+    """Constants for AVLPartNum in the Update Parts List from AVL request."""
+
+    ASSIGN_INTERNAL_PART_NUM = SherlockPartsService_pb2.AVLPartNum.AssignInternalPartNum
+    ASSIGN_VENDOR_AND_PART_NUM = SherlockPartsService_pb2.AVLPartNum.AssignVendorAndPartNum
+    DO_NOT_CHANGE_VENDOR_OR_PART_NUM = (
+        SherlockPartsService_pb2.AVLPartNum.DoNotChangeVendorOrPartNum
+    )
+
+
+class AVLDescription:
+    """Constants for AVLDescription in the Update Parts List from AVL request."""
+
+    ASSIGN_APPROVED_DESCRIPTION = SherlockPartsService_pb2.AVLDescription.AssignApprovedDescription
+    DO_NOT_CHANGE_DESCRIPTION = SherlockPartsService_pb2.AVLDescription.DoNotChangeDescription
 
 
 class PartLocation: