MRG: Merge pull request #524 from octue/feature/add-dynamic-children-…

…selection

Add dynamic children override

docs/source/asking_questions.rst

@@ -5,7 +5,7 @@ Asking services questions
 =========================
 
 Octue services
---------------
+==============
 
 There's a growing range of live :ref:`services <service_definition>` in the Octue ecosystem that you can ask questions
 to and get answers from. Currently, all of them are related to wind energy. Here's a quick glossary of terms before we
@@ -38,7 +38,7 @@ tell you more:
 
 
 How to ask a question
----------------------
+=====================
 You can ask any service a question if you have its service ID, project name, and permissions. The question is formed of
 input values and/or an input manifest.
 
@@ -51,7 +51,10 @@ input values and/or an input manifest.
         backend={"name": "GCPPubSubBackend", "project_name": "my-project"},
     )
 
-    answer = child.ask(input_values={"height": 32, "width": 3}, input_manifest=manifest)
+    answer = child.ask(
+        input_values={"height": 32, "width": 3},
+        input_manifest=manifest,
+    )
 
     answer["output_values"]
     >>> {"some": "data"}
@@ -62,9 +65,12 @@ input values and/or an input manifest.
 
 You can also set the following options when you call :mod:`Child.ask <octue.resources.child.Child.ask>`:
 
+- ``children`` - If the child has children of its own (i.e. grandchildren of the parent), this optional argument can be used to override the child's "default" children. This allows you to specify particular versions of grandchildren to use (see :ref:`this subsection below <overriding_children>`).
 - ``subscribe_to_logs`` - if true, the child will forward its logs to you
 - ``allow_local_files`` - if true, local files/datasets are allowed in any input manifest you supply
 - ``handle_monitor_message`` - if provided a function, it will be called on any monitor messages from the child
+- ``record_messages_to`` – if given a path to a JSON file, messages received from the parent while it processes the question are saved to it
+- ``allow_save_diagnostics_data_on_crash`` – if true, the input values and input manifest (including its datasets) will be saved by the child for future crash diagnostics if it fails while processing them
 - ``question_uuid`` - if provided, the question will use this UUID instead of a generated one
 - ``timeout`` - how long in seconds to wait for an answer (``None`` by default - i.e. don't time out)
 
@@ -78,7 +84,7 @@ sent back to the parent. If you're not sure how long a particular analysis might
 
 
 Asking multiple questions in parallel
--------------------------------------
+=====================================
 You can also ask multiple questions to a service in parallel.
 
 .. code-block:: python
@@ -98,7 +104,7 @@ This method uses threads, allowing all the questions to be asked at once instead
 
 
 Asking a question within a service
-----------------------------------
+==================================
 If you have :doc:`created your own Octue service <creating_services>` and want to ask children questions, you can do
 this more easily than above. Children are accessible from the ``analysis`` object by the keys you give them in the
 :ref:`app configuration <app_configuration>` file. For example, you can ask an ``elevation`` service a question like
@@ -154,3 +160,73 @@ See the parent service's `app configuration <https://github.com/octue/octue-sdk-
 and `app.py file <https://github.com/octue/octue-sdk-python/blob/main/octue/templates/template-child-services/parent_service/app.py>`_
 in the  `child-services app template <https://github.com/octue/octue-sdk-python/tree/main/octue/templates/template-child-services>`_
 to see this in action.
+
+.. _overriding_children:
+
+Overriding a child's children
+=============================
+If the child you're asking a question to has its own children (static children), you can override these by providing the
+IDs of the children you want it to use (dynamic children) to the :mod:`Child.ask <octue.resources.child.Child.ask>`
+method. Questions that would have gone to the static children will instead go to the dynamic children. Note that:
+
+- You must provide the children in the same format as they're provided in the :ref:`app configuration <app_configuration>`
+- If you override one static child, you must override others, too
+- The dynamic children must have the same keys as the static children (so the child knows which service to ask which
+  questions)
+- You should ensure the dynamic children you provide are compatible with and appropriate for questions from the child
+  service
+
+For example, if the child requires these children in its app configuration:
+
+.. code-block:: json
+
+    [
+        {
+            "key": "wind_speed",
+            "id": "template-child-services/wind-speed-service",
+            "backend": {
+                "name": "GCPPubSubBackend",
+                "project_name": "octue-amy"
+            },
+        },
+        {
+            "key": "elevation",
+            "id": "template-child-services/elevation-service",
+            "backend": {
+                "name": "GCPPubSubBackend",
+                "project_name": "octue-amy"
+            },
+        }
+    ]
+
+then you can override them like this:
+
+.. code-block:: python
+
+    answer = child.ask(
+        input_values={"height": 32, "width": 3},
+        children=[
+            {
+                "key": "wind_speed",
+                "id": "my/own-service",
+                "backend": {
+                    "name": "GCPPubSubBackend",
+                    "project_name": "octue-amy"
+                },
+            },
+            {
+                "key": "elevation",
+                "id": "organisation/another-service",
+                "backend": {
+                    "name": "GCPPubSubBackend",
+                    "project_name": "octue-amy"
+                },
+            },
+        ],
+    )
+
+Overriding beyond the first generation
+--------------------------------------
+It's an intentional choice to only go one generation deep with overriding children. If you need to be able to specify a
+whole tree of children, grandchildren, and so on, please `upvote this issue.
+<https://github.com/octue/octue-sdk-python/issues/528>`_