opentrons 8.3.2a0__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

opentrons/protocols/labware.py

@@ -4,7 +4,7 @@ import logging
 import json
 import os
 from pathlib import Path
-from typing import Any, AnyStr, Dict, Optional, Union, List, Sequence, Literal
+from typing import Mapping, Optional, Union, List, Sequence, Literal
 
 import jsonschema  # type: ignore
 
@@ -46,8 +46,8 @@ def get_labware_definition(
     load_name: str,
     namespace: Optional[str] = None,
     version: Optional[int] = None,
-    bundled_defs: Optional[Dict[str, LabwareDefinition]] = None,
-    extra_defs: Optional[Dict[str, LabwareDefinition]] = None,
+    bundled_defs: Optional[Mapping[str, LabwareDefinition]] = None,
+    extra_defs: Optional[Mapping[str, LabwareDefinition]] = None,
 ) -> LabwareDefinition:
     """
     Look up and return a definition by load_name + namespace + version and
@@ -147,51 +147,55 @@ def save_definition(
 
 
 def verify_definition(  # noqa: C901
-    contents: Union[AnyStr, LabwareDefinition, Dict[str, Any]]
+    contents: str | bytes | LabwareDefinition | object,
 ) -> LabwareDefinition:
     """Verify that an input string is a labware definition and return it.
 
-    If the definition is invalid, an exception is raised; otherwise parse the
-    json and return the valid definition.
+    :param contents: The untrusted input to parse and validate. If str or bytes, it's
+        parsed as JSON. Otherwise, it should be the output of json.load().
 
-    :raises json.JsonDecodeError: If the definition is not valid json
-    :raises jsonschema.ValidationError: If the definition is not valid.
-    :returns: The parsed definition
+    :raises NotALabwareError:
+
+    :returns: The parsed and validated definition
     """
     schemata_by_version = {
         2: json.loads(load_shared_data("labware/schemas/2.json").decode("utf-8")),
         3: json.loads(load_shared_data("labware/schemas/3.json").decode("utf-8")),
     }
 
-    if isinstance(contents, dict):
-        to_return = contents
-    else:
-        try:
-            to_return = json.loads(contents)
-        except json.JSONDecodeError as e:
-            raise NotALabwareError("invalid-json", [e]) from e
     try:
-        schema_version = to_return["schemaVersion"]
-    except KeyError as e:
-        raise NotALabwareError("no-schema-id", [e]) from e
+        parsed_json: object = (
+            json.loads(contents) if isinstance(contents, (str, bytes)) else contents
+        )
+    except json.JSONDecodeError as e:
+        raise NotALabwareError("invalid-json", [e]) from e
+
+    if isinstance(parsed_json, dict):
+        try:
+            schema_version: object = parsed_json["schemaVersion"]
+        except KeyError as e:
+            raise NotALabwareError("no-schema-id", [e]) from e
+    else:
+        raise NotALabwareError("no-schema-id", [])
 
     try:
-        schema = schemata_by_version[schema_version]
+        # we can type ignore this because we handle the KeyError below
+        schema = schemata_by_version[schema_version]  # type: ignore[index]
     except KeyError as e:
         raise NotALabwareError("bad-schema-id", [e]) from e
 
     try:
-        jsonschema.validate(to_return, schema)
+        jsonschema.validate(parsed_json, schema)
     except jsonschema.ValidationError as e:
         raise NotALabwareError("schema-mismatch", [e]) from e
 
     # we can type ignore this because if it passes the jsonschema it has
     # the correct structure
-    return to_return  # type: ignore[return-value]
+    return parsed_json  # type: ignore[return-value]
 
 
 def _get_labware_definition_from_bundle(
-    bundled_labware: Dict[str, LabwareDefinition],
+    bundled_labware: Mapping[str, LabwareDefinition],
     load_name: str,
     namespace: Optional[str] = None,
     version: Optional[int] = None,

opentrons/protocols/models/__init__.py

@@ -1,21 +0,0 @@
-# Convenience re-exports of models that are especially common or important.
-# More detailed sub-models are always available through the underlying
-# submodules.
-#
-# If re-exporting something, its name should still make sense when it's separated
-# from the name of its parent submodule. e.g. re-exporting models.json_protocol.Labware
-# as models.Labware could be confusing.
-
-# TODO(mc, 2022-03-11): remove this re-export when it won't break pickling
-# https://opentrons.atlassian.net/browse/RSS-94
-from opentrons_shared_data.labware.labware_definition import (
-    LabwareDefinition,
-    WellDefinition,
-)
-from .json_protocol import Model as JsonProtocol
-
-__all__ = [
-    "LabwareDefinition",
-    "WellDefinition",
-    "JsonProtocol",
-]

opentrons/simulate.py

@@ -71,7 +71,9 @@ from opentrons.protocols.api_support.deck_type import (
     should_load_fixed_trash_labware_for_python_protocol,
 )
 from opentrons.protocols.api_support.types import APIVersion
-from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons_shared_data.labware.labware_definition import (
+    labware_definition_type_adapter,
+)
 
 from .util import entrypoint_util
 
@@ -829,7 +831,7 @@ def _create_live_context_pe(
     # Non-async would use call_soon_threadsafe(), which makes the waiting harder.
     async def add_all_extra_labware() -> None:
         for labware_definition_dict in extra_labware.values():
-            labware_definition = LabwareDefinition.model_validate(
+            labware_definition = labware_definition_type_adapter.validate_python(
                 labware_definition_dict
             )
             pe.add_labware_definition(labware_definition)

opentrons/types.py

@@ -88,6 +88,15 @@ LocationLabware = Union[
 ]
 
 
+class MeniscusTrackingTarget(enum.Enum):
+    START = "start"
+    END = "end"
+    DYNAMIC = "dynamic"
+
+    def __str__(self) -> str:
+        return self.name
+
+
 class Location:
     """Location(point: Point, labware: Union["Labware", "Well", str, "ModuleGeometry", LabwareLike, None, "ModuleContext"])
 
@@ -129,12 +138,12 @@ class Location:
             "ModuleContext",
         ],
         *,
-        _ot_internal_is_meniscus: Optional[bool] = None,
+        _meniscus_tracking: Optional[MeniscusTrackingTarget] = None,
     ):
         self._point = point
         self._given_labware = labware
         self._labware = LabwareLike(labware)
-        self._is_meniscus = _ot_internal_is_meniscus
+        self._meniscus_tracking = _meniscus_tracking
 
     # todo(mm, 2021-10-01): Figure out how to get .point and .labware to show up
     # in the rendered docs, and then update the class docstring to use cross-references.
@@ -148,8 +157,8 @@ class Location:
         return self._labware
 
     @property
-    def is_meniscus(self) -> Optional[bool]:
-        return self._is_meniscus
+    def meniscus_tracking(self) -> Optional[MeniscusTrackingTarget]:
+        return self._meniscus_tracking
 
     def __iter__(self) -> Iterator[Union[Point, LabwareLike]]:
         """Iterable interface to support unpacking. Like a tuple.
@@ -167,7 +176,7 @@ class Location:
             isinstance(other, Location)
             and other._point == self._point
             and other._labware == self._labware
-            and other._is_meniscus == self._is_meniscus
+            and other._meniscus_tracking == self._meniscus_tracking
         )
 
     def move(self, point: Point) -> "Location":
@@ -190,10 +199,14 @@ class Location:
 
         """
 
-        return Location(point=self.point + point, labware=self._given_labware)
+        return Location(
+            point=self.point + point,
+            labware=self._given_labware,
+            _meniscus_tracking=self._meniscus_tracking,
+        )
 
     def __repr__(self) -> str:
-        return f"Location(point={repr(self._point)}, labware={self._labware}, is_meniscus={self._is_meniscus if self._is_meniscus is not None else False})"
+        return f"Location(point={repr(self._point)}, labware={self._labware}, meniscus_tracking={self._meniscus_tracking})"
 
 
 # TODO(mc, 2020-10-22): use MountType implementation for Mount

opentrons/util/logging_config.py

@@ -1,7 +1,8 @@
 import logging
 from logging.config import dictConfig
+from logging.handlers import QueueListener, RotatingFileHandler
 import sys
-from typing import Any, Dict
+from queue import Queue
 
 from opentrons.config import CONFIG, ARCHITECTURE, SystemArchitecture
 
@@ -12,11 +13,33 @@ else:
     SENSOR_LOG_NAME = "unused"
 
 
-def _host_config(level_value: int) -> Dict[str, Any]:
+# We want this big enough to smooth over any temporary stalls in journald's ability
+# to consume our records--but bounded, so if we consistently outpace journald for
+# some reason, we don't leak memory or get latency from buffer bloat.
+# 50000 is basically an arbitrary guess.
+_LOG_QUEUE_SIZE = 50000
+
+
+log_queue = Queue[logging.LogRecord](maxsize=_LOG_QUEUE_SIZE)
+"""A buffer through which log records will pass.
+
+This is intended to work around problems when our logs are going to journald:
+we think journald can block for a while when it flushes records to the filesystem,
+and the backpressure from that will cause calls like `log.debug()` to block and
+interfere with timing-sensitive hardware control.
+https://github.com/Opentrons/opentrons/issues/18034
+
+`log_init()` will configure all the logs that this package knows about to pass through
+this queue. This queue is exposed so consumers of this package (i.e. robot-server)
+can do the same thing with their own logs, which is important to preserve ordering.
+"""
+
+
+def _config_for_host(level_value: int) -> None:
     serial_log_filename = CONFIG["serial_log_file"]
     api_log_filename = CONFIG["api_log_file"]
     sensor_log_filename = CONFIG["sensor_log_file"]
-    return {
+    config = {
         "version": 1,
         "disable_existing_loggers": False,
         "formatters": {
@@ -90,13 +113,20 @@ def _host_config(level_value: int) -> Dict[str, Any]:
         },
     }
 
+    dictConfig(config)
 
-def _buildroot_config(level_value: int) -> Dict[str, Any]:
+
+def _config_for_robot(level_value: int) -> None:
     # Import systemd.journald here since it is generally unavailble on non
     # linux systems and we probably don't want to use it on linux desktops
     # either
+    from systemd.journal import JournalHandler  # type: ignore
+
     sensor_log_filename = CONFIG["sensor_log_file"]
-    return {
+
+    sensor_log_queue = Queue[logging.LogRecord](maxsize=_LOG_QUEUE_SIZE)
+
+    config = {
         "version": 1,
         "disable_existing_loggers": False,
         "formatters": {
@@ -104,36 +134,38 @@ def _buildroot_config(level_value: int) -> Dict[str, Any]:
         },
         "handlers": {
             "api": {
-                "class": "systemd.journal.JournalHandler",
+                "class": "opentrons.util.logging_queue_handler.CustomQueueHandler",
                 "level": logging.DEBUG,
                 "formatter": "message_only",
-                "SYSLOG_IDENTIFIER": "opentrons-api",
+                "extra": {"SYSLOG_IDENTIFIER": "opentrons-api"},
+                "queue": log_queue,
             },
             "serial": {
-                "class": "systemd.journal.JournalHandler",
+                "class": "opentrons.util.logging_queue_handler.CustomQueueHandler",
                 "level": logging.DEBUG,
                 "formatter": "message_only",
-                "SYSLOG_IDENTIFIER": "opentrons-api-serial",
+                "extra": {"SYSLOG_IDENTIFIER": "opentrons-api-serial"},
+                "queue": log_queue,
             },
             "can_serial": {
-                "class": "systemd.journal.JournalHandler",
+                "class": "opentrons.util.logging_queue_handler.CustomQueueHandler",
                 "level": logging.DEBUG,
                 "formatter": "message_only",
-                "SYSLOG_IDENTIFIER": "opentrons-api-serial-can",
+                "extra": {"SYSLOG_IDENTIFIER": "opentrons-api-serial-can"},
+                "queue": log_queue,
             },
             "usbbin_serial": {
-                "class": "systemd.journal.JournalHandler",
+                "class": "opentrons.util.logging_queue_handler.CustomQueueHandler",
                 "level": logging.DEBUG,
                 "formatter": "message_only",
-                "SYSLOG_IDENTIFIER": "opentrons-api-serial-usbbin",
+                "extra": {"SYSLOG_IDENTIFIER": "opentrons-api-serial-usbbin"},
+                "queue": log_queue,
             },
             "sensor": {
-                "class": "logging.handlers.RotatingFileHandler",
-                "formatter": "message_only",
-                "filename": sensor_log_filename,
-                "maxBytes": 1000000,
+                "class": "opentrons.util.logging_queue_handler.CustomQueueHandler",
                 "level": logging.DEBUG,
-                "backupCount": 3,
+                "formatter": "message_only",
+                "queue": sensor_log_queue,
             },
         },
         "loggers": {
@@ -169,12 +201,47 @@ def _buildroot_config(level_value: int) -> Dict[str, Any]:
         },
     }
 
+    # Start draining from the queue and sending messages to journald.
+    # Then, stash the queue listener in a global variable so it doesn't get garbage-collected.
+    # I don't know if we actually need to do this, but let's not find out the hard way.
+    global _queue_listener
+    if _queue_listener is not None:
+        # In case this log init function was called multiple times for some reason.
+        _queue_listener.stop()
+    _queue_listener = QueueListener(log_queue, JournalHandler())
+    _queue_listener.start()
+
+    # Sensor logs are a special one-off thing that go to their own file instead of journald.
+    # We apply the same QueueListener performance workaround for basically the same reasons.
+    sensor_rotating_file_handler = RotatingFileHandler(
+        filename=sensor_log_filename, maxBytes=1000000, backupCount=3
+    )
+    sensor_rotating_file_handler.setLevel(logging.DEBUG)
+    sensor_rotating_file_handler.setFormatter(logging.Formatter(fmt="%(message)s"))
+    global _sensor_queue_listener
+    if _sensor_queue_listener is not None:
+        _sensor_queue_listener.stop()
+    _sensor_queue_listener = QueueListener(
+        sensor_log_queue, sensor_rotating_file_handler
+    )
+    _sensor_queue_listener.start()
+
+    dictConfig(config)
 
-def _config(arch: SystemArchitecture, level_value: int) -> Dict[str, Any]:
-    return {
-        SystemArchitecture.YOCTO: _buildroot_config,
-        SystemArchitecture.BUILDROOT: _buildroot_config,
-        SystemArchitecture.HOST: _host_config,
+    # TODO(2025-04-15): We need some kind of log_deinit() function to call
+    # queue_listener.stop() before the process ends. Not doing that means we're
+    # dropping some records when the process shuts down.
+
+
+_queue_listener: QueueListener | None = None
+_sensor_queue_listener: QueueListener | None = None
+
+
+def _config(arch: SystemArchitecture, level_value: int) -> None:
+    {
+        SystemArchitecture.YOCTO: _config_for_robot,
+        SystemArchitecture.BUILDROOT: _config_for_robot,
+        SystemArchitecture.HOST: _config_for_host,
     }[arch](level_value)
 
 
@@ -191,6 +258,8 @@ def log_init(level_name: str) -> None:
             f"Defaulting to {fallback_log_level}\n"
         )
         ot_log_level = fallback_log_level
+
+    # todo(mm, 2025-04-14): Use logging.getLevelNamesMapping() when we have Python >=3.11.
     level_value = logging._nameToLevel[ot_log_level]
-    logging_config = _config(ARCHITECTURE, level_value)
-    dictConfig(logging_config)
+
+    _config(ARCHITECTURE, level_value)

opentrons/util/logging_queue_handler.py

@@ -0,0 +1,61 @@
+# noqa: D100
+
+
+import logging.handlers
+import logging
+from queue import Queue
+from typing import cast
+from typing_extensions import override
+
+
+class CustomQueueHandler(logging.handlers.QueueHandler):
+    """A logging.QueueHandler with some customizations.
+
+    - Allow adding `extra` data to handled log records.
+
+    - Simplify and optimize for single-process use.
+
+    - If a new message comes in but the queue is full, block until it has room.
+      (The default QueueHandler drops records in a way we probably wouldn't notice.)
+    """
+
+    def __init__(
+        self, *, queue: Queue[logging.LogRecord], extra: dict[str, object] | None = None
+    ) -> None:
+        """Construct the handler.
+
+        Args:
+            queue: When this handler receives a log record, it will insert the message
+                into this queue.
+            extra: Extra data to attach to each log record, to be interpreted by
+                whatever handler is on the consuming side of the queue. e.g. if that's
+                `systemd.journal.JournalHandler`, you could add a "SYSLOG_IDENTIFIER"
+                key here. This corresponds to the `extra` arg of `Logger.debug()`.
+        """
+        super().__init__(queue=queue)
+
+        # Double underscore because we're subclassing external code so we should try to
+        # avoid collisions with its attributes.
+        self.__extra = extra
+
+    @override
+    def prepare(self, record: logging.LogRecord) -> logging.LogRecord:
+        """Called internally by the superclass before enqueueing a record."""
+        if self.__extra is not None:
+            # This looks questionable, but updating __dict__ is the documented behavior
+            # of `Logger.debug(msg, extra=...)`.
+            record.__dict__.update(self.__extra)
+
+        # We intentionally do *not* call `super().prepare(record)`. It's documented to
+        # muck with the data in the LogRecord, apparently as part of supporting
+        # inter-process use. Since we don't need that, we can preserve the original
+        # data and also save some compute time.
+        return record
+
+    @override
+    def enqueue(self, record: logging.LogRecord) -> None:
+        """Called internally by the superclass to enqueue a record."""
+        # This cast is safe because we constrain the type of `self.queue`
+        # in our `__init__()` and nobody should mutate it after-the-fact, in practice.
+        queue = cast(Queue[logging.LogRecord], self.queue)
+        queue.put(record)

{opentrons-8.3.2a0.dist-info → opentrons-8.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: opentrons
-Version: 8.3.2a0
+Version: 8.4.0
 Summary: The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.
 Author: Opentrons
 Author-email: engineering@opentrons.com
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 License-File: ../LICENSE
-Requires-Dist: opentrons-shared-data (==8.3.2a0)
+Requires-Dist: opentrons-shared-data (==8.4.0)
 Requires-Dist: aionotify (==0.3.1)
 Requires-Dist: anyio (<4.0.0,>=3.6.1)
 Requires-Dist: jsonschema (<4.18.0,>=3.0.1)
@@ -35,9 +35,9 @@ Requires-Dist: pyusb (==1.2.1)
 Requires-Dist: packaging (>=21.0)
 Requires-Dist: importlib-metadata (>=1.0) ; python_version < "3.8"
 Provides-Extra: flex-hardware
-Requires-Dist: opentrons-hardware[flex] (==8.3.2a0) ; extra == 'flex-hardware'
+Requires-Dist: opentrons-hardware[flex] (==8.4.0) ; extra == 'flex-hardware'
 Provides-Extra: ot2-hardware
-Requires-Dist: opentrons-hardware (==8.3.2a0) ; extra == 'ot2-hardware'
+Requires-Dist: opentrons-hardware (==8.4.0) ; extra == 'ot2-hardware'
 
 .. _Full API Documentation: http://docs.opentrons.com