Merge pull request OpenAssetIO#1345 from feltech/work/856-managementPolicySingular

Singular managementPolicy overload

Author: feltech

RELEASE_NOTES.md

@@ -1,6 +1,15 @@
 Release Notes
 =============
 
+v1.0.0-beta.x.x
+---------------
+
+### Improvements
+
+- Added singular overload of `managementPolicy` for convenience.
+  [#856](https://github.com/OpenAssetIO/OpenAssetIO/issues/856)
+
+
 v1.0.0-beta.2.2
 ---------------
 
@@ -16,7 +25,7 @@ _The addition of a new virtual method,
   Notably, this includes `TraitsData`, which when printed now displays all the
   properties contained within the traits, rather than simply a list of trait
   ids.
-  
+
   Note: Due to this, some runtime string output may have slightly changed, and
   tests may need to be adjusted.
   [#1307](https://github.com/OpenAssetIO/OpenAssetIO/issues/1307)

doc/doxygen/src/Examples.dox

@@ -303,8 +303,8 @@
  * # the correct trait set to query. Using the standard definition
  * # ensures consistent behaviour across managers/hosts. We request
  * # the manager's policy for read access to this entity type.
- * [policy] = manager.managementPolicy(
- *  [TextFileSpecification.kTraitSet], PolicyAccess.kRead, context)
+ * policy = manager.managementPolicy(
+ *  TextFileSpecification.kTraitSet, PolicyAccess.kRead, context)
  *
  * # We can now check which traits were imbued in the policy, the
  * # absence of a trait means it is unsupported.
@@ -353,8 +353,8 @@
  * # The first step is to see if the manager wants to manage text files.
  * # Note that this time we request the manager's policy for write
  * # access.
- * [policy] = manager.managementPolicy(
- *     [TextFileSpecification.kTraitSet], PolicyAccess.kWrite, context)
+ * policy = manager.managementPolicy(
+ *     TextFileSpecification.kTraitSet, PolicyAccess.kWrite, context)
  *
  * if not ManagedTrait.isImbuedTo(policy):
  *   # The manager doesn't care about this type of asset
@@ -363,8 +363,8 @@
  * # Managers may want to dictate to the host some of the data to be
  * # published, e.g. tell us where to put files. So we ask the manager
  * # which traits, if any, it is interested in "driving" itself.
- * [manager_driven_policy] = manager.managementPolicy(
- *     [TextFileSpecification.kTraitSet], PolicyAccess.kManagerDriven, context)
+ * manager_driven_policy = manager.managementPolicy(
+ *     TextFileSpecification.kTraitSet, PolicyAccess.kManagerDriven, context)
  *
  * # Choose some defaults in case the manager cannot drive these values.
  * save_path = os.path.join(os.path.expanduser('~'), 'greeting.txt')

resources/abi/libopenassetio.so.1.0.0.xml

@@ -443,6 +443,29 @@ class OPENASSETIO_CORE_EXPORT Manager final {
                                                     access::PolicyAccess policyAccess,
                                                     const ContextConstPtr& context);
 
+  /**
+   * Management Policy queries allow a host to ask a Manager how they
+   * would like to interact with different kinds of entity.
+   *
+   * This includes the policy for a given trait set, as well as the
+   * per-trait policy, with the context for the policy determined by
+   * the @p policyAccess.
+   *
+   * See the @ref managementPolicy(const trait::TraitSets&,<!--
+   * -->access::PolicyAccess, const ContextConstPtr&) "batch overload"
+   * documentation for more details.
+   *
+   * @param traitSet The entity @ref trait "traits" to query.
+   *
+   * @param policyAccess Intended operation type to perform on entities.
+   *
+   * @param context The calling context.
+   *
+   * @return Policy for the @p traitSet.
+   */
+  [[nodiscard]] trait::TraitsDataPtr managementPolicy(const trait::TraitSet& traitSet,
+                                                      access::PolicyAccess policyAccess,
+                                                      const ContextConstPtr& context);
   /**
    * @}
    */

src/openassetio-core/include/openassetio/hostApi/Manager.hpp

@@ -20,6 +20,12 @@ namespace hostApi {
 // alternate, often friendlier signatures wrapping the core batch-first
 // callback-based member functions found in `Manager.cpp`
 
+trait::TraitsDataPtr Manager::managementPolicy(const trait::TraitSet &traitSet,
+                                               access::PolicyAccess policyAccess,
+                                               const ContextConstPtr &context) {
+  return managementPolicy(trait::TraitSets{traitSet}, policyAccess, context).at(0);
+}
+
 /******************************************
  * entityExists
  ******************************************/

src/openassetio-core/src/hostApi/ManagerConveniences.cpp

@@ -90,9 +90,17 @@ void registerManager(const py::module& mod) {
       .def("initialize", &Manager::initialize, py::arg("managerSettings"),
            py::call_guard<py::gil_scoped_release>{})
       .def("flushCaches", &Manager::flushCaches, py::call_guard<py::gil_scoped_release>{})
-      .def("managementPolicy", &Manager::managementPolicy, py::arg("traitSets"),
-           py::arg("policyAccess"), py::arg("context").none(false),
+      .def("managementPolicy",
+           py::overload_cast<const trait::TraitSet&, access::PolicyAccess, const ContextConstPtr&>(
+               &Manager::managementPolicy),
+           py::arg("traitSet"), py::arg("policyAccess"), py::arg("context").none(false),
            py::call_guard<py::gil_scoped_release>{})
+      .def(
+          "managementPolicy",
+          py::overload_cast<const trait::TraitSets&, access::PolicyAccess, const ContextConstPtr&>(
+              &Manager::managementPolicy),
+          py::arg("traitSets"), py::arg("policyAccess"), py::arg("context").none(false),
+          py::call_guard<py::gil_scoped_release>{})
       .def("createContext", &Manager::createContext, py::call_guard<py::gil_scoped_release>{})
       .def("createChildContext", &Manager::createChildContext,
            py::arg("parentContext").none(false), py::call_guard<py::gil_scoped_release>{})

src/openassetio-python/cmodule/src/hostApi/ManagerBinding.cpp

@@ -25,6 +25,7 @@
 from openassetio import access
 from openassetio.hostApi import Manager
 from openassetio.managerApi import ManagerStateBase
+from openassetio.trait import TraitsData
 
 
 class Test_Manager_gil:
@@ -226,7 +227,10 @@ def test_initialize(self, a_threaded_manager):
     def test_isEntityReferenceString(self, a_threaded_manager):
         a_threaded_manager.isEntityReferenceString("")
 
-    def test_managementPolicy(self, a_threaded_manager, a_context):
+    def test_managementPolicy(self, mock_manager_interface, a_threaded_manager, a_context):
+        mock_manager_interface.mock.managementPolicy.return_value = [TraitsData()]
+
+        a_threaded_manager.managementPolicy(set(), access.PolicyAccess.kRead, a_context)
         a_threaded_manager.managementPolicy([], access.PolicyAccess.kRead, a_context)
 
     def test_preflight(self, a_threaded_manager, an_entity_reference, a_traits_data, a_context):

src/openassetio-python/tests/cmodule/gil/test_manager_gil.py

@@ -2409,7 +2409,7 @@ def test_method_defined_in_cpp(self, method_introspector):
         assert not method_introspector.is_defined_in_python(Manager.managementPolicy)
         assert method_introspector.is_implemented_once(Manager, "managementPolicy")
 
-    def test_wraps_the_corresponding_method_of_the_held_interface(
+    def test_batch_overload_wraps_the_corresponding_method_of_the_held_interface(
         self, manager, mock_manager_interface, a_host_session, some_entity_trait_sets, a_context
     ):
         data1 = TraitsData()
@@ -2429,6 +2429,36 @@ def test_wraps_the_corresponding_method_of_the_held_interface(
             some_entity_trait_sets, access.PolicyAccess.kWrite, a_context, a_host_session
         )
 
+    def test_singular_overload_wraps_the_corresponding_method_of_the_held_interface(
+        self, manager, mock_manager_interface, a_host_session, an_entity_trait_set, a_context
+    ):
+        expected = TraitsData()
+        expected.setTraitProperty("t1", "p1", 1)
+        method = mock_manager_interface.mock.managementPolicy
+        method.return_value = [expected]
+
+        actual = manager.managementPolicy(
+            an_entity_trait_set, access.PolicyAccess.kWrite, a_context
+        )
+
+        assert actual == expected
+        method.assert_called_once_with(
+            [an_entity_trait_set], access.PolicyAccess.kWrite, a_context, a_host_session
+        )
+
+    def test_when_plugin_gives_no_result_then_singular_overload_raises(
+        self, manager, mock_manager_interface, an_entity_trait_set, a_context
+    ):
+        """
+        This is a truly exceptional exception, we're just checking that
+        we don't get a segfault. The message isn't important.
+        """
+        method = mock_manager_interface.mock.managementPolicy
+        method.return_value = []
+
+        with pytest.raises(IndexError):
+            manager.managementPolicy(an_entity_trait_set, access.PolicyAccess.kWrite, a_context)
+
 
 class Test_Manager_preflight(BatchFirstMethodTest):
     @pytest.fixture(autouse=True)