docs(api): Fix description of run log payload (#13776)

Co-authored-by: Ed Cormany <[email protected]>

api/src/opentrons/execute.py

@@ -315,12 +315,33 @@ def execute(  # noqa: C901
     :param log_level: The level of logs to emit on the command line:
                       ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
                       Defaults to ``"warning"``.
-    :param emit_runlog: A callback for printing the runlog. If specified, this
-                        will be called whenever a command adds an entry to the
-                        runlog, which can be used for display and progress
-                        estimation. If specified, the callback should take a
-                        single argument (the name doesn't matter) which will
-                        be a dictionary (see below). Default: ``None``
+    :param emit_runlog: A callback for printing the run log. If specified, this
+        will be called whenever a command adds an entry to the
+        run log, which can be used for display and progress
+        estimation. If specified, the callback should take a
+        single argument (the name doesn't matter) which will
+        be a dictionary:
+
+        .. code-block:: python
+
+          {
+            'name': command_name,
+            'payload': {
+              'text': string_command_text,
+              # The rest of this struct is
+              # command-dependent; see
+              # opentrons.commands.commands.
+             }
+          }
+
+        .. note::
+          In older software versions, ``payload["text"]`` was a
+          `format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
+          To get human-readable text, you had to do ``payload["text"].format(**payload)``.
+          Don't do that anymore. If ``payload["text"]`` happens to contain any
+          ``{`` or ``}`` characters, it can confuse ``.format()`` and cause it to raise a
+          ``KeyError``.
+
     :param custom_labware_paths: A list of directories to search for custom labware.
                                  Loads valid labware from these paths and makes them available
                                  to the protocol context. If this is ``None`` (the default), and
@@ -333,22 +354,6 @@ def execute(  # noqa: C901
                               non-recursive contents of specified directories
                               are presented by the protocol context in
                               ``ProtocolContext.bundled_data``.
-
-    The format of the runlog entries is as follows:
-
-    .. code-block:: python
-
-        {
-            'name': command_name,
-            'payload': {
-                 'text': string_command_text,
-                  # The rest of this struct is command-dependent; see
-                  # opentrons.commands.commands. Its keys match format
-                  # keys in 'text', so that
-                  # entry['payload']['text'].format(**entry['payload'])
-                  # will produce a string with information filled in
-             }
-        }
     """
     stack_logger = logging.getLogger("opentrons")
     stack_logger.propagate = propagate_logs

api/src/opentrons/protocol_api/instrument_context.py

@@ -1317,7 +1317,7 @@ def move_to(
                       individual axis speeds, you can use
                       :py:obj:`.ProtocolContext.max_speeds`.
         :param publish: Whether a call to this function should publish to the
-                        runlog or not.
+                        run log or not.
         """
         publish_ctx = nullcontext()
 

api/src/opentrons/simulate.py

@@ -439,15 +439,23 @@ def simulate(
 
     Each dict element in the run log has the following keys:
 
-        - ``level``: The depth at which this command is nested - if this an
-                     aspirate inside a mix inside a transfer, for instance,
-                     it would be 3.
-        - ``payload``: The command, its arguments, and how to format its text.
-                       For more specific details see
-                       ``opentrons.commands``. To format a message from
-                       a payload do ``payload['text'].format(**payload)``.
+        - ``level``: The depth at which this command is nested. If this an
+          aspirate inside a mix inside a transfer, for instance, it would be 3.
+
+        - ``payload``: The command. The human-readable run log text is available at
+          ``payload["text"]``. The other keys of ``payload`` are command-dependent;
+          see ``opentrons.commands``.
+
+          .. note::
+            In older software versions, ``payload["text"]`` was a
+            `format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
+            To get human-readable text, you had to do ``payload["text"].format(**payload)``.
+            Don't do that anymore. If ``payload["text"]`` happens to contain any
+            ``{`` or ``}`` characters, it can confuse ``.format()`` and cause it to raise a
+            ``KeyError``.
+
         - ``logs``: Any log messages that occurred during execution of this
-                    command, as a logging.LogRecord
+          command, as a standard Python :py:obj:`~logging.LogRecord`.
 
     :param protocol_file: The protocol file to simulate.
     :param file_name: The name of the file
@@ -474,7 +482,7 @@ def simulate(
                            occur during protocol simulation are best associated
                            with the actions in the protocol that cause them.
                            Default: ``False``
-    :param log_level: The level of logs to capture in the runlog:
+    :param log_level: The level of logs to capture in the run log:
                       ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
                       Defaults to ``"warning"``.
     :returns: A tuple of a run log for user output, and possibly the required