[Core] Add EntityTraits.

elliotcmorris · elliotcmorris · commit 081abcfb5691 · 2024-02-23T15:33:02.000Z
EntityTraits is a required method, and the template dosen't work
without it.

Add the method, as well as a business
logic test similar to resolve. as well
as relevant compliance suite fixtures.

Signed-off-by: Elliot Morris &lt;elliot.morris@foundry.com&gt;
diff --git a/plugin/my_asset_manager/MyAssetManagerInterface.py b/plugin/my_asset_manager/MyAssetManagerInterface.py
@@ -18,10 +18,12 @@
 # below two imports instead.
 # from openassetio.traits import TraitsData
 # from openassetio.errors import BatchElementError
-from openassetio.access import PolicyAccess, ResolveAccess
+from openassetio.access import PolicyAccess, ResolveAccess, EntityTraitsAccess
 from openassetio.managerApi import ManagerInterface
 from openassetio_mediacreation.traits.content import LocatableContentTrait
 from openassetio_mediacreation.traits.managementPolicy import ManagedTrait
+from openassetio_mediacreation.traits.application import ConfigTrait
+from openassetio_mediacreation.traits.usage import EntityTrait
 
 # OpenAssetIO is building out the implementation vertically, there are
 # known fails for missing abstract methods.
@@ -67,6 +69,7 @@ def hasCapability(self, capability):
             ManagerInterface.Capability.kEntityReferenceIdentification,
             ManagerInterface.Capability.kManagementPolicyQueries,
             ManagerInterface.Capability.kResolution,
+            ManagerInterface.Capability.kEntityTraitIntrospection,
         ):
             return True
 
@@ -121,6 +124,90 @@ def isEntityReferenceString(self, someString, hostSession):
         # info()
         return someString.startswith(self.__reference_prefix)
 
+    def entityTraits(
+        self,
+        entityReferences,
+        entityTraitsAccess,
+        context,
+        _hostSession,
+        successCallback,
+        errorCallback,
+    ):
+        # This function is used by the host to retrieve the trait sets
+        # for specific entities. The behaviour of this function differs
+        # per access mode. `kRead` is a request for an exhaustive trait
+        # set for an entity according to this manager, whilst `kWrite`
+        # is a request for the minimal trait set required to publish to
+        # that entity. As this manager example is read-only, we will
+        # simply reject any `kWrite` requests.
+
+        # For the purposes of this template, we use this fake map of
+        # traits to serve as our "database", arbitrarily assuming that
+        # asset 2 is a config entity of some sort.
+        # Replace this with querying your backend systems.
+        managed_assets_map = {
+            "my_asset_manager:///anAsset": {EntityTrait.kId, LocatableContentTrait.kId},
+            "my_asset_manager:///anAsset2": {
+                EntityTrait.kId,
+                LocatableContentTrait.kId,
+                ConfigTrait.kId,
+            },
+            "my_asset_manager:///anAsset3": {EntityTrait.kId, LocatableContentTrait.kId},
+        }
+
+        # If your manager doesn't support write, like this one, reject
+        # a write access mode via calling the error callback.
+        if entityTraitsAccess != EntityTraitsAccess.kRead:
+            result = BatchElementError(
+                BatchElementError.ErrorCode.kEntityAccessError, "Entities are read-only"
+            )
+            for idx in range(len(entityReferences)):
+                errorCallback(idx, result)
+            return
+
+        # Iterate over all the entity references, calling the correct
+        # error/success callbacks into the host.
+        # You should handle success/failure on an entity-by-entity
+        # basis, do not abort your entire operation because any single
+        # entity is malformed/can't be processed for any reason, use
+        # the error callback and continue.
+        for idx, ref in enumerate(entityReferences):
+            # It may be that one of the references you are provided is
+            # recognized for this manager, but has some syntax error or
+            # is otherwise incorrect for your specific resolve context.
+            # For example, an asset reference that specifies a version
+            # for an un-versioned entity could be considered malformed.
+            #
+            # N.B. It's not required to perform an explicit check here
+            # if this is naturally serviced during your backend lookup,
+            # the key is not to error the whole batch, but use the error
+            # callback for relevant references.
+            identifier_is_malformed = is_malformed_ref(ref)
+            if identifier_is_malformed:
+                error_result = BatchElementError(
+                    BatchElementError.ErrorCode.kMalformedEntityReference,
+                    "Entity identifier is malformed",
+                )
+                errorCallback(idx, error_result)
+            else:
+                # If our manager has the asset in question, we can
+                # let the host know which traits make up this specific
+                # entity.
+                if ref.toString() in managed_assets_map:
+                    # Return the traits imbued the the entity in
+                    # question
+                    success_result = managed_assets_map[ref.toString()]
+                    successCallback(idx, success_result)
+                else:
+                    # Otherwise, we don't know about the entity, so call
+                    # the error callback with an entity resolution error
+                    # for this specific entity.
+                    error_result = BatchElementError(
+                        BatchElementError.ErrorCode.kEntityResolutionError,
+                        f"Entity '{ref.toString()}' not found",
+                    )
+                    errorCallback(idx, error_result)
+
     def resolve(
         self,
         entityReferences,
@@ -208,11 +295,11 @@ def resolve(
                     errorCallback(idx, error_result)
 
 
-# Internal function used in Resolve, replace with logic based on what a
-# malformed ref means in your backend. For the demonstrative purposes of
-# this template, we pretend to support query parameters, then invent a
-# completely arbitrary query parameter that we don't support. (We then
-# test our implementation using the api compliance suite, see
-# fixtures.py)
+# Internal function used in Resolve and EntityTraits, replace with logic
+# based on what a malformed ref means in your backend. For the
+# demonstrative purposes of this template, we pretend to support query
+# parameters, then invent a completely arbitrary query parameter that we
+# don't support. (We then test our implementation using the api
+# compliance suite, see fixtures.py)
 def is_malformed_ref(entityReference):
     return "?unsupportedQueryParam" in entityReference.toString()
diff --git a/pyproject.toml b/pyproject.toml
@@ -6,8 +6,8 @@ name = "my_asset_manager"
 version = "1.0.0"
 requires-python = ">=3.7"
 dependencies = [
-    "openassetio >= 1.0.0a14",
-    "openassetio-mediacreation == 1.0.0a7"
+    "openassetio>=1.0.0b1.rev0",
+    "openassetio-mediacreation == 1.0.0a8"
 ]
 
 authors = [
diff --git a/tests/business_logic_suite.py b/tests/business_logic_suite.py
@@ -8,14 +8,15 @@
 
 # pylint: disable=invalid-name, missing-function-docstring, missing-class-docstring
 
-from openassetio.access import ResolveAccess
+from openassetio.access import ResolveAccess, EntityTraitsAccess
 from openassetio.test.manager.harness import FixtureAugmentedTestCase
 from openassetio_mediacreation.traits.content import LocatableContentTrait
+from openassetio_mediacreation.traits.usage import EntityTrait
 
 
 class Test_resolve(FixtureAugmentedTestCase):
     """
-    Test suite for the business logic of MyAssetManager
+    Test suite for the Resolve business logic of MyAssetManager
 
     The test here is illustrative only, you should extend this suite
     to provide full coverage of all of the behaviour of your asset
@@ -57,3 +58,38 @@ def error_cb(idx, batchElementError):
             self.assertTrue(result[0].hasTrait(trait))
             for property_, value in self.__test_entity[1][trait].items():
                 self.assertEqual(result[0].getTraitProperty(trait, property_), value)
+
+
+class Test_entityTraits(FixtureAugmentedTestCase):
+    """
+    Test suite for the EntityTraits business logic of MyAssetManager
+
+    The test here is illustrative only, you should extend this suite
+    to provide full coverage of all of the behaviour of your asset
+    manager.
+    """
+
+    def test_when_refs_found_then_success_callback_called_with_expected_values(self):
+        entity_reference = self._manager.createEntityReference("my_asset_manager:///anAsset")
+
+        context = self.createTestContext()
+
+        results = [None]
+
+        def success_cb(idx, trait_set):
+            print("Success", trait_set)
+            results[idx] = trait_set
+
+        def error_cb(idx, batchElementError):
+            self.fail(
+                f"Unexpected error for '{entity_reference.toString()}':"
+                f" {batchElementError.message}"
+            )
+
+        self._manager.entityTraits(
+            [entity_reference], EntityTraitsAccess.kRead, context, success_cb, error_cb
+        )
+
+        self.assertTrue(len(results) == 1)
+        expected_trait_set = {EntityTrait.kId, LocatableContentTrait.kId}
+        assert results[0] == expected_trait_set
diff --git a/tests/fixtures.py b/tests/fixtures.py
@@ -6,14 +6,19 @@
 """
 from openassetio import constants
 from openassetio_mediacreation.traits.content import LocatableContentTrait
-
+from openassetio_mediacreation.traits.application import ConfigTrait
+from openassetio_mediacreation.traits.usage import EntityTrait
 
 IDENTIFIER = "myorg.manager.my_asset_manager"
 
 VALID_REF = "my_asset_manager:///AssetIdentifier"
 NON_REF = "not a Ŕeference"
 MALFORMED_REF = "my_asset_manager:///AssetIdentifier?unsupportedQueryParam"
 EXISTING_REF = "my_asset_manager:///anAsset"
+MISSING_ENTITY_REF = "my_asset_manager:///missing_entity"
+ERROR_MSG_MALFORMED_REF = "Entity identifier is malformed"
+ERROR_MSG_MISSING_ENTITY = "Entity 'my_asset_manager:///missing_entity' not found"
+ERROR_READ_ONLY_ACCESS = "Entities are read-only"
 
 # This dictionary serves as expected outputs for the OpenAssetIO api
 # compliance suite. This suite tests that your implementation functions
@@ -39,12 +44,41 @@
             "a_set_of_valid_traits": {LocatableContentTrait.kId},
             "a_reference_to_a_readonly_entity": EXISTING_REF,
             "the_error_string_for_a_reference_to_a_readonly_entity": "Entities are read-only",
-            "a_reference_to_a_missing_entity": "my_asset_manager:///missing_entity",
+            "a_reference_to_a_missing_entity": MISSING_ENTITY_REF,
             "the_error_string_for_a_reference_to_a_missing_entity": (
                 "Entity 'my_asset_manager:///missing_entity' not found"
             ),
             "a_malformed_reference": MALFORMED_REF,
             "the_error_string_for_a_malformed_reference": "Entity identifier is malformed",
         }
     },
+    "Test_entityTraits": {
+        "shared": {
+            "a_reference_to_a_readonly_entity": EXISTING_REF,
+            "a_reference_to_a_missing_entity": MISSING_ENTITY_REF,
+            "a_malformed_reference": MALFORMED_REF,
+        },
+        "test_when_querying_malformed_reference_then_malformed_reference_error_is_returned": {
+            "expected_error_message": ERROR_MSG_MALFORMED_REF,
+        },
+        "test_when_querying_missing_reference_for_read_then_resolution_error_is_returned": {
+            "expected_error_message": ERROR_MSG_MISSING_ENTITY
+        },
+        "test_when_read_only_entity_queried_for_write_then_access_error_is_returned": {
+            "expected_error_message": ERROR_READ_ONLY_ACCESS
+        },
+        "test_when_multiple_references_for_read_then_same_number_of_returned_trait_sets": {
+            "first_entity_reference": "my_asset_manager:///anAsset",
+            "second_entity_reference": "my_asset_manager:///anAsset2",
+            "first_entity_trait_set": {
+                EntityTrait.kId,
+                LocatableContentTrait.kId,
+            },
+            "second_entity_trait_set": {
+                EntityTrait.kId,
+                LocatableContentTrait.kId,
+                ConfigTrait.kId,
+            },
+        },
+    },
 }
