From c4ccc0bf31aec275e113315d5c5db8a68ff5d089 Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Thu, 12 Oct 2023 14:22:45 -0400 Subject: [PATCH 1/6] Correct descriptions of payloads. --- api/src/opentrons/execute.py | 47 +++++++++++++++++++---------------- api/src/opentrons/simulate.py | 22 ++++++++++------ 2 files changed, 41 insertions(+), 28 deletions(-) diff --git a/api/src/opentrons/execute.py b/api/src/opentrons/execute.py index 15f0acf84c2..8c54ac25c17 100644 --- a/api/src/opentrons/execute.py +++ b/api/src/opentrons/execute.py @@ -316,11 +316,32 @@ def execute( # noqa: C901 ``"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`` + 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: + + .. 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)``. + That usage is deprecated now. 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/simulate.py b/api/src/opentrons/simulate.py index d677d6e93fe..9cd31914cb9 100644 --- a/api/src/opentrons/simulate.py +++ b/api/src/opentrons/simulate.py @@ -440,14 +440,22 @@ 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)``. + 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)``. + That usage is deprecated now. 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 :py:obj:`logging.LogRecord`. :param protocol_file: The protocol file to simulate. :param file_name: The name of the file From 29956a031eee269dc7446159d45fdf870279e035 Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Mon, 23 Oct 2023 16:45:34 -0400 Subject: [PATCH 2/6] space hyphen space Co-authored-by: Ed Cormany --- api/src/opentrons/simulate.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/simulate.py b/api/src/opentrons/simulate.py index 9cd31914cb9..db146a66e37 100644 --- a/api/src/opentrons/simulate.py +++ b/api/src/opentrons/simulate.py @@ -439,7 +439,7 @@ 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 + - ``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 From 82b6605c15b10a7aac33790e1d750ef6f8424246 Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Mon, 23 Oct 2023 16:48:50 -0400 Subject: [PATCH 3/6] Standard Python LogRecord. Co-authored-by: Ed Cormany --- api/src/opentrons/simulate.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/simulate.py b/api/src/opentrons/simulate.py index db146a66e37..99f836ab394 100644 --- a/api/src/opentrons/simulate.py +++ b/api/src/opentrons/simulate.py @@ -455,7 +455,7 @@ def simulate( ``KeyError``. - ``logs``: Any log messages that occurred during execution of this - command, as a :py:obj:`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 From 660b0cd7538393c6c04c55c56d72c12cccd042bc Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Mon, 23 Oct 2023 17:02:42 -0400 Subject: [PATCH 4/6] "runlog" -> "run log" --- api/src/opentrons/execute.py | 4 ++-- api/src/opentrons/protocol_api/instrument_context.py | 2 +- api/src/opentrons/simulate.py | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/src/opentrons/execute.py b/api/src/opentrons/execute.py index 8c54ac25c17..d6611e597d3 100644 --- a/api/src/opentrons/execute.py +++ b/api/src/opentrons/execute.py @@ -315,9 +315,9 @@ 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 + :param emit_runlog: A callback for printing the run log. If specified, this will be called whenever a command adds an entry to the - runlog, which can be used for display and progress + 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: 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 99f836ab394..9560eee2bcb 100644 --- a/api/src/opentrons/simulate.py +++ b/api/src/opentrons/simulate.py @@ -482,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 From e4ec5418f95a90590a8f94edbc58a3060ae91a9d Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Mon, 23 Oct 2023 17:04:32 -0400 Subject: [PATCH 5/6] scooch --- api/src/opentrons/execute.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/execute.py b/api/src/opentrons/execute.py index d6611e597d3..605b0caedcd 100644 --- a/api/src/opentrons/execute.py +++ b/api/src/opentrons/execute.py @@ -328,9 +328,9 @@ def execute( # noqa: C901 'name': command_name, 'payload': { 'text': string_command_text, - # The rest of this struct is - # command-dependent; see - # opentrons.commands.commands. + # The rest of this struct is + # command-dependent; see + # opentrons.commands.commands. } } From 8e96a4b9bc2e8a3902d12363f6b8186cd4a3518d Mon Sep 17 00:00:00 2001 From: Max Marrone Date: Wed, 25 Oct 2023 12:52:32 -0400 Subject: [PATCH 6/6] Be precise and direct about what we mean by "that usage is deprecated." --- api/src/opentrons/execute.py | 2 +- api/src/opentrons/simulate.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/execute.py b/api/src/opentrons/execute.py index 605b0caedcd..21242be00c4 100644 --- a/api/src/opentrons/execute.py +++ b/api/src/opentrons/execute.py @@ -338,7 +338,7 @@ def execute( # noqa: C901 In older software versions, ``payload["text"]`` was a `format string `_. To get human-readable text, you had to do ``payload["text"].format(**payload)``. - That usage is deprecated now. If ``payload["text"]`` happens to contain any + 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``. diff --git a/api/src/opentrons/simulate.py b/api/src/opentrons/simulate.py index 9560eee2bcb..3c74d088994 100644 --- a/api/src/opentrons/simulate.py +++ b/api/src/opentrons/simulate.py @@ -450,7 +450,7 @@ def simulate( In older software versions, ``payload["text"]`` was a `format string `_. To get human-readable text, you had to do ``payload["text"].format(**payload)``. - That usage is deprecated now. If ``payload["text"]`` happens to contain any + 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``.