From c2501c3cc0cb76e39d083ad702c3a5ca9f3d2f36 Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Wed, 25 Oct 2023 13:13:51 -0400 Subject: [PATCH] docs(api): Fix description of run log payload (#13776) Co-authored-by: Ed Cormany --- api/src/opentrons/execute.py | 49 ++++++++++--------- .../protocol_api/instrument_context.py | 2 +- api/src/opentrons/simulate.py | 26 ++++++---- 3 files changed, 45 insertions(+), 32 deletions(-) diff --git a/api/src/opentrons/execute.py b/api/src/opentrons/execute.py index 15f0acf84c2..21242be00c4 100644 --- a/api/src/opentrons/execute.py +++ b/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 `_. + 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 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 0828e69572e..00de9ae472b 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/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() diff --git a/api/src/opentrons/simulate.py b/api/src/opentrons/simulate.py index d677d6e93fe..3c74d088994 100644 --- a/api/src/opentrons/simulate.py +++ b/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 `_. + 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